How Zaguán Bladeworks with you.
Zaguán Blade is an open source desktop code editor for AI-assisted engineering work. It investigates your project by structure, writes changes you review before accepting, and runs commands only when you approve. Run it with local AI (Ollama or any OpenAI-compatible server), or connect a Zaguán account for the hosted workflow.
What Blade Does
Blade is built around an inspect, change, and validate loop:
Inspect
It gives the assistant controlled access to editor state, open files, cursor position, selected paths, project structure, symbol relationships, terminal output, Git state, and uncommitted changes.
Change
It can investigate a workspace, propose or apply file edits, run approved commands, and help validate the result. Code and Plan modes let you choose between implementation and read-only investigation.
Validate
AI edits are written to disk with history snapshots and stay reviewable until you accept or reject them.
Two Meanings of "Local"
Blade is local-first, but the word covers two separate settings that you can use independently:
- Local AI controls where model inference runs.
- Local Storage controls where conversation history is stored.
Set Up Blade
Open a Project
Choose File → Open Project, or use the open-project action on the welcome screen.
Blade restores project state such as open files and prepares its local code-intelligence index in the background.
The status bar reports whether code intelligence is checking, indexing, finalizing, ready, partial, or unavailable. You can start working while indexing continues — symbol-aware results simply improve once it is ready.
Set Up Local AI
Use Blade without a Zaguán subscription by enabling a local provider.
- Open Settings → Local AI.
- 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
- Ollama (Local) at
- Use Test Connection.
- Use Refresh Models.
- In the Models list, choose which discovered models appear in the chat model picker.
- Save the settings and select a model in chat.
The Models list also shows whether each model uses Blade's built-in system prompt or a custom prompt saved for that model. Local model quality and tool-calling reliability depend on the model and server. Local providers have no built-in web fetch or deep research, and image attachments are unavailable when Blade only has local models.
Connect a Zaguán Account
Sign in through your browser to connect Blade to the hosted Zaguán Coder Daemon. No copy-pasting keys.
- Open Settings → Account.
- Select Sign in.
- Complete the browser flow. If needed, use the displayed device code and verification-page link.
- Return to Blade once the account is approved.
The Account page shows the connected account and plan, and links to subscription, device, usage, and credit management. You can reconnect or sign out from the same page, and manual API-key entry remains available for existing keys and local development. Hosted models appear in the model picker after authentication, and hosted workflows can use stronger models, managed orchestration, richer context handling, and web-backed research where available.
Choose Conversation Storage
When you open a project for the first time, Blade asks where to store conversation history:
Local Storage keeps conversations and local artifacts under .zblade/ in the project. Server Storage keeps them on Zaguán servers for faster retrieval and cross-device sync. Blade also stores project settings, indexes, cache files, and history artifacts under .zblade/, and ensures it is ignored by the workspace Git repository.
Interface Overview
App Bar and Tabs
The app bar holds the File menu, editor tabs, project title, fullscreen handling, and window controls.
- Tabs show unsaved files, AI-edited files, pending review state, unread AI edits, and files deleted on disk.
- Drag tabs to reorder them.
- The tab context menu can copy the filename or full path, move a tab to the beginning or end, close other tabs, or close all tabs.
- Quitting with unsaved editor changes asks whether to save them.
Activity Bar and Sidebar
- Explorer — Browse and manage files. The lower Outline section shows symbols for the active file.
- Git — Inspect changes, view diffs, stage or unstage, commit, push or publish a branch, and browse the Git graph.
- File History — View snapshots for the active file and revert to an earlier version.
- Settings — Account, local AI, storage, context, remote control, appearance, language, and app details.
Clicking the active sidebar icon closes that sidebar. Clicking outside an open sidebar also closes it.
Editor
CodeMirror 6Syntax highlighting for Rust, TypeScript, JavaScript, Python, Go, C/C++, HTML, CSS, JSON, YAML, PHP, Markdown, and related formats.
- Depending on language support, the editor shows diagnostics and symbol information on hover.
- The active file's Outline navigates to classes, functions, methods, headings, and other indexed structures.
- Markdown switches between edit and rendered view with Ctrl+E.
- PDFs open in a built-in viewer with page navigation, zoom, and fit-to-width.
Chat and History
AIThe right panel has two tabs:
- Chat — The current conversation, model and mode controls, active task status, tool progress, queued requests, and the composer.
- History — Saved conversations grouped by date. Select one to resume it, or use New Conversation to start fresh.
Terminal
IntegratedIntegrated terminal tabs. Create and close terminals, copy or paste, search output, clear the terminal, and send selected terminal content to chat.
AI-triggered commands appear in the terminal and require approval unless project YOLO mode is enabled. Approved long-running commands may continue as background sessions while the assistant checks output, writes to standard input, or stops the process.
Working With Files and Code
Explorer Actions
Right-click a file or folder to see the actions available for that item:
- New files and folders
- Rename and delete
- Cut, copy, paste, and duplicate
- Drag-and-drop moves
- Copy full or workspace-relative paths
- Reveal in the system file manager
- Open a folder in the integrated terminal
- Manual refresh
Outline and Local Symbol Graph
The Outline below the Explorer shows the active file's parsed structure. Select an entry to navigate to it.
To investigate a symbol visually:
- Put the cursor on an indexed symbol.
- Right-click and choose Show Symbol Graph.
- Filter by incoming or outgoing relationships, relationship type, and minimum confidence.
- Select a related symbol to open it, or expand it to keep exploring its neighborhood.
The graph can show calls, dependencies, type relationships, handlers, and structural relationships. Results come from the local index; supported relationships and confidence vary by language.
Code-Intelligence Index
Blade maintains a local, workspace-wide symbol and semantic index. The assistant can use it to:
- Find definitions, references, callers, implementations, and related symbols
- Read file outlines and exact symbol ranges
- Trace relationships across multiple steps
- Estimate the impact and likely tests for a proposed edit
- Map modules and architecture
- Find semantic anchors such as routes, configuration keys, environment access, translation keys, CSS selectors, and design references
Coverage includes full or partial indexing for Rust, TypeScript/JavaScript, Python, Go, C/C++, Java, C#, Kotlin, Ruby, PHP, Vue and Svelte scripts, shell, SQL, Dockerfiles, Make/CMake, Markdown, and common web and configuration formats. Coverage is not identical for every language.
The status bar reports index progress and health. A partial index is still useful, but empty results are less conclusive until the relevant files are indexed.
Working With AI
Code and Plan Modes
Use Plan mode when you want read-only investigation and a concrete implementation plan. Plan mode tells the assistant not to edit files or run commands. Once a plan is produced, use Implement to send it into a Code-mode request.
Use Code mode when you want the assistant to implement changes, use tools, run approved commands, and validate its work.
Useful Request Patterns
- “Explain the active file.”
- “Find where this symbol is used.”
- “Show the impact of changing this public function.”
- “Plan the safest way to refactor this component.”
- “Run the relevant tests and fix the failure.”
- “Use
@src/path/to/file.tsas context.” - “Use the deployment skill for this task.”
Add Explicit Context
Type @ in the composer to open suggestions:
- Select a workspace file or folder to attach it as an explicit reference.
- Use
@webwith a URL to fetch web content in supported hosted workflows. - Use
@researchto start hosted deep research and open the completed result in a new editor tab.
The assistant also receives relevant live state such as the active file, cursor or selection, open files, project instructions, and Git changes. It can request more context through the local index and file tools.
Composer and Queue
Press Enter to send and Shift+Enter for a newline. While the assistant is responding, additional requests are queued instead of being lost, and each queued request can be edited or deleted before it runs.
Use the stop control to cancel the active response. The chat shows task progress, reasoning summaries where provided, tool activity, result counts, and command approval state. A floating approval indicator helps you return to a pending command when it is outside the visible chat area.
The composer has its own undo and redo history. At the start or end of the input, the Up and Down arrow keys revisit previously sent prompts.
Conversation Actions
Right-click a message to copy it. Right-click one of your own editable messages and choose Edit Message to revise the request; the conversation continues again from that point.
Use the History tab to resume older local or server-stored conversations.
Cloud Error Recovery
If a hosted request fails because credits or account access need attention, chat provides direct account or credit links and a Use Local AI action.
Repository Instructions
and Agent Skills
AGENTS.md
Blade automatically loads workspace instructions from AGENTS.md:
- The root
AGENTS.mdapplies across the workspace. - Nested
AGENTS.mdfiles apply to work under their directory. - Instructions can include local Markdown files such as
@workflow.mdor@docs/workflow.md.
Use these files for repository-specific commands, conventions, safety rules, validation expectations, and documentation requirements.
Skills
Skills are reusable workflows the assistant discovers and loads only when relevant. Blade supports them for hosted models and direct local providers.
Blade discovers SKILL.md files under:
.agents/skills/in the current workspace~/.agents/skills/for user-wide skills- Blade's legacy global skills directory, for existing installations
A minimal workspace skill looks like this:
---
name: release-check
description: Validate a release candidate and prepare release notes.
---
Follow the repository release checklist.
Read `references/release-policy.md` before changing version files.Put it at .agents/skills/release-check/SKILL.md. Referenced files and scripts can live beside it. Keep the catalog description clear enough for the assistant to decide when the skill applies, or name the skill explicitly in your request.
Blade advertises the available skill catalog without loading every instruction file into every prompt. The assistant searches the catalog, loads the selected skill in bounded chunks, and then reads only the referenced resources it needs.
Reviewing AI Actions
File Changes
AI file changes are written to disk with a history snapshot and tracked as pending Blade changes:
- Accept keeps the current file contents and clears its pending review state.
- Reject restores the snapshot captured before the AI change.
- Accept All and Reject All operate on the current pending change set.
- File tabs and editor controls show pending and unread AI edits.
- Repeated AI edits preserve the combined review diff.
Tool cards can also expose an Undo action for supported file changes. The Git panel remains the source of truth for repository staging and commits.
Command and Tool Approvals
When the assistant requests a command, Blade shows the command and lets you run or skip it. Some other sensitive tool actions can also show an approval card.
YOLO mode auto-approves run_command requests for the current project. It does not silently approve every kind of tool action, and the model is not told that YOLO mode is enabled.
Remote control approvals follow the same run-or-reject model.
Git Workflow
The Git sidebar shows the current branch, ahead/behind state, staged files, unstaged files, untracked files, and conflicts.
What You Can Do
- Expand a file to inspect its diff
- Stage or unstage one file
- Stage all or unstage all
- Enter a commit message and commit
- Generate a commit message with the selected AI model
- Push commits, or publish a branch that has no upstream yet
- Expand the Git graph to browse commits
- Copy a commit hash, or open a compatible commit on GitHub
Safety Behavior
- Blade warns about detached HEAD.
- Commits with unresolved conflicts are blocked.
- Committing with unstaged changes stages them as part of the commit.
- Pushing accepts the current pending Blade AI-change set, because those files are being published to Git.
Screenshots, Images,
and Documents
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 one directly into the composer.
Annotate
Select, arrow, text, outlined or filled shapes, pencil, colour and size controls, undo, redo, delete, and clear.
Image Support
Image attachments require a supported hosted model. They are disabled when only local models are available, and for known unsupported models such as GLM.
On X11 desktops, capture is limited to windows visible on the current workspace. Covered windows can capture as black unless a compositor such as picom is running — bring the target window forward before capture. Wayland, macOS, and composited desktops generally avoid these limitations. See the advanced docs for details.
PDFs. Open a PDF from the Explorer to use the built-in viewer. Its toolbar provides previous/next page, zoom in and out, and fit-to-width. Scrolling updates the current-page indicator.
Settings Reference
Configuration
- Theme — Built-in dark and light themes.
- Text Size — Editor and chat text size. Ctrl+mouse wheel over the editor or chat adjusts and saves that surface's size.
- Language — English or Spanish (Spain).
- YOLO Mode — Project-scoped auto-approval for
run_command.
Account
- Sign in — Browser-based Zaguán sign-in, with Reconnect to refresh an existing connection and Cancel while a sign-in is in progress.
- Connected account and plan.
- Subscription, device, usage, and credit links into your Zaguán dashboard.
- Sign out — Clears the stored credentials from this machine.
- Manual API-key entry — Still available for an existing key or local development.
Local AI
- Ollama local URL — Default:
http://localhost:11434. - Ollama Cloud API key.
- OpenAI-compatible server URL — Default:
http://localhost:8080. - Connection testing and model refresh.
- Per-model visibility in the chat model picker.
- Built-in versus custom-prompt status for each model.
Storage
- Local or server conversation storage.
- Metadata sync for local storage.
- Context cache toggle and cache size.
Context
Per-project- Maximum context tokens — 2K to 32K.
- Context compression toggle, with a remote or local compression model.
- Allow .gitignored files in AI context (default: off).
- Warmup Context Prefetch — On by default.
Warmup Context Prefetch sends the active editor file and applicable repository instructions to supported providers during connection warmup, which can cut first-response latency and repeated prompt-cache cost. Disable it if you prefer the assistant to read those resources only on demand. Allowing .gitignored files can expose secrets, generated output, or large artifacts — leave it off unless the task genuinely requires them.
Remote
Remote control pairs Blade with your own Telegram bot. Once paired you can send terminal commands, approve or reject AI command execution, and view command output and exit codes from your phone.
Blade must remain running on your computer.
About
- Version, Runtime, Engine, Mode.
- Website — zblade.dev.
- GitHub — ZaguanLabs/ZaguanBlade.
Keyboard Shortcuts
App and Tabs
| F11 | Toggle fullscreen |
| Ctrl+W | Close current tab |
| Ctrl+Tab | Cycle to next tab |
| Ctrl+Shift+Tab | Cycle to previous tab |
| Escape | Close the active modal, picker, or menu |
Files and Editor
| Ctrl+N | New file in the Explorer |
| Ctrl+Shift+N | New folder in the Explorer |
| Ctrl+S | Save the active file |
| Ctrl+Z | Undo |
| Ctrl+Shift+Z | Redo |
| Ctrl+F | Find in file |
| Ctrl+X / Ctrl+C / Ctrl+V | Cut, copy, and paste |
| Ctrl+E | Toggle Markdown edit/view mode |
Chat Composer
| Enter | Send message |
| Shift+Enter | Insert newline |
| Ctrl+Z / Ctrl+Shift+Z | Undo or redo composer edits |
| @ | Open command and workspace-path suggestions |
| Tab or Enter | Accept the active suggestion |
| Escape | Close suggestions |
| Arrow Up / Arrow Down | Navigate message history at the start/end of the composer |
Screenshot Annotation
| Ctrl+Z | Undo annotation |
| Ctrl+Y or Ctrl+Shift+Z | Redo annotation |
| Delete or Backspace | Delete selected annotation |
| Ctrl+Enter | Finish and attach |
| Escape | Cancel |
Terminal
| Ctrl+Shift+C | Copy terminal selection |
| Ctrl+Shift+V | Paste into terminal |
| Ctrl+F | Find in terminal |
Privacy and Data
No Telemetry
Blade does not enable usage telemetry in the current settings implementation.
Local AI Privacy
Local AI keeps inference on your configured local or LAN provider. Prompts and code never leave your machine when using Ollama or a local OpenAI-compatible server.
Local Storage
Local Storage keeps conversation artifacts under the project .zblade/ directory. .gitignored files are excluded from AI context by default and can be enabled per project in Settings → Context.
Server Storage
Hosted Zaguán models and Server Storage require sending the relevant prompt, context, and conversation data to Zaguán services.
Remote Control
Remote control uses a Telegram bot token you provide, and requires Blade to be running on your computer.
Keyless Local Servers
Keyless OpenAI-compatible servers should be bound to localhost or a trusted private network, not exposed directly to the public internet.
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 →Active Development
StableZaguán Blade is well 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. Blade with the Zaguán Coder Daemon runs for days without issues.
You may still encounter edge cases. When you do:
Thank you for being part of the future of coding.