docs~/zaguan-blade/docsuser guide
$getting started with blade

How Zaguán Bladeworks with you.

Zaguán Blade is an AI-native desktop code editor. It reads your project context, proposes edits as diffs you review, and runs commands only when you approve. Use it with local AI (Ollama/OpenAI-compatible) or a Zaguán subscription.

The Loop

What Blade Does

Blade is built around an inspect, change, and validate loop:

👁

Inspect

It uses editor state, open files, cursor, selection, project structure, symbol indexes, terminal output, and uncommitted changes as context.

🔧

Change

It proposes or applies file edits, runs approved commands, and helps inspect and validate the workspace.

⚡

Validate

AI edits are tracked so you can review, accept, reject, or undo the resulting file changes.

Getting Started

Set Up Blade

1

Local AI

Use Blade without a subscription by enabling a local provider.

  1. Open Settings.
  2. Go to Local AI.
  3. Enable one or more providers:
    • Ollama (Local) at http://localhost:11434
    • Ollama Cloud with an Ollama API key
    • OpenAI-compatible Server for llama.cpp, LocalAI, vLLM, and similar
  4. Click Test Connection.
  5. Click Refresh Models.
  6. Save settings and pick the model from the chat model picker.

Local providers do not have built-in web fetch or research.

OpenAI-compatible setup →
2

Zaguán Subscription

Connect to the hosted Zaguán Coder Daemon for the full workflow.

  1. Subscribe at ZaguanAI.com.
  2. Open Settings → Account.
  3. Paste your Zaguán API key.
  4. Save settings.

Hosted models appear in the model picker when the key is valid.

3

First Project Setup

When you open a project for the first time, Blade asks where to store conversation history:

Local StorageServer Storage

Local Storage stores conversations and artifacts under .zblade/ in the project. Server Storage stores conversations on Zaguán servers. Blade keeps project settings, indexes, cache, and history under .zblade/ and ensures it is ignored by Git.

The Interface

Interface Overview

🗂️

App Bar

File menu, window controls, fullscreen handling, and project/app actions.

📁

Activity Bar

  • Explorer — Browse and manage files.
  • Git — Inspect changes, stage/unstage, commit, push, pull, fetch, and generate commit messages with AI.
  • File History — View snapshots for the active file and revert when needed.
  • Settings — Configure account, local AI, storage, context, remote control, appearance, language, and app details.
💻

Editor

CodeMirror 6

Syntax highlighting for Rust, TypeScript, JavaScript, Python, Go, C/C++, HTML, CSS, JSON, YAML, PHP, Markdown, and more. Markdown files can switch between edit and view modes with Ctrl+E.

🤖

Chat Panel

AI
  • Code / Plan mode toggle.
  • Model picker with hosted, Ollama, and Local Server sections.
  • Image/screenshot attachment controls when the model supports images.
  • @ suggestions for workspace paths and commands like @web and @research.
  • Inline command approval cards and tool progress.
⌨️

Terminal

Integrated

Integrated terminals with copy, paste, search, split, clear, and shell selection. AI-triggered commands require approval unless YOLO mode is enabled.

Keyboard Shortcuts

Keyboard Shortcuts

App and Tabs

F11Toggle fullscreen
Ctrl+WClose current tab
Ctrl+TabCycle to next tab
Ctrl+Shift+TabCycle to previous tab
EscapeClose open modal, picker, or menu

Files and Editor

Ctrl+NNew file in the explorer
Ctrl+Shift+NNew folder in the explorer
Ctrl+OOpen folder from the file menu
Ctrl+SSave active file
Ctrl+Shift+SSave as
Ctrl+ZUndo
Ctrl+Shift+ZRedo
Ctrl+FFind in file
F2Rename symbol
Ctrl+EToggle Markdown edit/view mode

Chat Composer

EnterSend message
Shift+EnterInsert newline
@Open command/path suggestions
Tab or EnterAccept active suggestion
EscapeClose suggestions
Arrow Up / Arrow DownNavigate message history when cursor is at the start/end

Terminal

Ctrl+Shift+CCopy terminal selection
Ctrl+Shift+VPaste into terminal
Ctrl+FFind in terminal
Working With AI

Working With AI

Chat Modes

Use Plan mode when you want investigation and a concrete plan before implementation. Use Code mode when you want the assistant to implement and validate changes.

Useful Request Patterns

  • “Explain the active file.”
  • “Find where this symbol is used.”
  • “Plan the safest way to refactor this component.”
  • “Run the relevant tests and fix the failure.”
  • “Use @src/path/to/file.ts as context.”

What the AI Knows

When Blade has local indexes available, the assistant can use symbol search, file ranges, semantic anchors, impact analysis, and workspace structure rather than reading the whole project.

Reviewing Changes

Reviewing AI Changes

Disk-First Change Model

AI file changes are written to disk with a history snapshot and tracked as uncommitted Blade changes.

  • Accept keeps the current file contents.
  • Reject restores the snapshot captured before the AI change.
  • Accept All and Reject All operate on the current pending change set.
  • File tabs show when AI edits are pending or unread.

The Git panel remains the source of truth for repository-level commits and staging.

Settings

Settings

⚙️

Configuration

  • Theme — Zaguán Dark, Blade Coder, Blade Cream, Blade Robot.
  • Text Size — Editor and chat font sizes.
  • Language — English, Spanish.
  • YOLO Mode — Auto-approve run_command requests for the current project only.
👤

Account

  • API Key — Your Zaguán subscription key.
  • Manage Subscription — Links to subscription management or pricing.
🤖

Local AI

  • Ollama local URL — Default: http://localhost:11434.
  • Ollama Cloud API key.
  • OpenAI-compatible server URL — Default: http://localhost:8080.
  • Test Connection and Refresh Models.
💾

Storage

  • Local or server conversation storage.
  • Metadata sync for local storage.
  • Context cache toggle and cache size.
🧠

Context

Per-project
  • Max Context Tokens — 2K to 32K.
  • Context Compression — Remote or local compression model.
  • Allow .gitignored Files — Include gitignored files in AI context (default: false).
📱

Remote

  • Telegram Bot Token — Connect to a Telegram bot for remote control.
ℹ️

About

Screenshots

Screenshots and Images

🖼️

Capture Window

Select a window from the picker and attach a full screenshot.

✂️

Capture Region

Select a window, then drag to crop a specific region.

📤

Upload or Paste

Upload an image from disk or paste from clipboard.

✏️

Annotate

Draw arrows, rectangles, ellipses, text, and freehand before attaching.

Image Support

Image attachments require a model that supports images. They are disabled when only local models are available and for known unsupported models such as GLM.

Screenshots work best when the window you want is visible on the current workspace. Some desktop environments have platform-specific limits; see the advanced docs for details.

Privacy & Data

Privacy and Data

🚫

No Telemetry

Blade does not enable usage telemetry in the current settings implementation.

🤖

Local AI Privacy

Local AI models run on your machine or LAN. Prompts and code never leave your computer when using Ollama or local OpenAI-compatible servers.

🔒

Local Storage

Local storage keeps conversation artifacts under the project .zblade/ directory.

🔐

Server Storage

Hosted Zaguán models and server storage require sending the relevant prompt, context, and conversation data to Zaguán services.

Technical Docs

Need More Detail?

The user guide above covers day-to-day use. For advanced setup, custom prompts, and the full tool reference, see the technical documentation.

⚙️

Advanced Setup

OpenAI-compatible servers, custom system prompts, the Symbols Index, and building Blade from source.

Read advanced setup →
🤖

Models

Curated list of the models Blade ships with, including provider, context window, capabilities, and our recommendations.

View model list →
📖

Tool Calls Reference

Complete reference for the tool calls available in Zaguán Blade.

View reference →
🐙

GitHub

Source code, issue tracker, and build instructions.

Open GitHub →
Support & Feedback

Active Development

Stable

Zaguán Blade is past the Alpha stage. It is under active development, a few features are still being implemented, and the core editor is already stable enough for daily use.

This website is built and maintained exclusively with Zaguán Blade. v0.8.2 with the Zaguán Coder Daemon is very stable and runs for days without issues.

You may still encounter edge cases. When you do:

🐛 Report Bugs→💡 Feature Requests→

Thank you for being part of the future of coding.