Documentation Get Started
How to use Blade, from zero setup to advanced workflows. This guide covers the interface, AI collaboration, and configuration.
AI-Native Editor
Zaguán Blade is not just a text editor with a chat sidebar. It is designed from the ground up to allow an AI agent to "live" inside your editor.
It supports Local AI through Ollama and any OpenAI-compatible connection, so you can run models on your own machine or point to self-hosted gateways without changing your workflow.
It reads your context
The AI knows your active file, cursor position, open tabs, project structure, and recent diagnostics — no copy-paste needed.
It edits files directly
No pasting code blocks into your editor. The AI writes inline diff blocks you can review, accept, or reject before they touch your code.
It runs what it needs
Terminal commands, file searches, web research — the AI can execute tools in your workspace, but you approve every command.
Quick Start Guide
Choose Your AI Path
Zaguán Blade supports both Local AI (private, no API key) and Cloud AI (faster hosted models). You can use either or both.
Set Up Your AI Provider
For Local AI: Open Settings > Local AI and enable Ollama or an OpenAI-compatible server. No API key required.
For Cloud AI: Go to Settings > Account and add your Zaguán API key for hosted models.
Choose Storage Mode
When opening a project for the first time, select your preferred storage mode for conversation history.
Interface Overview
Activity Bar
- Files - Project file explorer
- Git - Stage, commit, push
- History - Browse file history
- Settings - Preferences & account
Center Stage
EditorHigh-performance CodeMirror 6 editor with syntax highlighting. Diff Blocks appear inline when the AI proposes changes.
Right Panel
AI Assistant- Chat - Main communication channel
- Model Selector - Choose AI model
- Command Center - Type
@for special commands
Bottom Panel
TerminalIntegrated terminal for running commands. The AI can see and interact with this terminal when executing commands.
Keyboard Shortcuts
Global Shortcuts
| F11 | Toggle fullscreen mode |
| Ctrl+W | Close current tab |
| Ctrl+Tab | Cycle to next tab |
| Ctrl+Shift+Tab | Cycle to previous tab |
| Escape | Close modals/popups |
File Operations
| Ctrl+N | New File |
| Ctrl+O | Open Folder |
| Ctrl+S | Save current file |
| Ctrl+Shift+S | Save As |
| Alt+F4 | Exit application |
Editor Shortcuts
| Ctrl+Z | Undo |
| Ctrl+Shift+Z | Redo |
| Ctrl+F | Find in file |
| F2 | Rename symbol |
| Ctrl+E | Toggle Edit/View mode (Markdown) |
Chat Input
| Enter | Send message |
| Shift+Enter | New line (without sending) |
| Arrow Up/Down | Navigate command suggestions |
| Tab or Enter | Select command from autocomplete |
| Escape | Close command autocomplete |
Special Commands
Type @ in the chat input to access these special commands:
Fetches content from a URL and uses it as context for the AI. Great for referencing documentation or articles.
Performs deep research on a topic and displays results in a new tab. AI-powered web research at your fingertips.
AI Collaboration
What the AI knows about your project
The AI doesn't need you to describe your codebase. It reads it directly from the editor.
- Active file - The file you are currently viewing
- Open files - All open tabs in the editor
- Cursor & selection - Your cursor position and any selected text
- Mentioned paths - Files referenced via
@pathin chat - Diagnostics - Recent build errors and compiler warnings
- Project structure - File tree and symbol index when needed
Reviewing Changes
When the AI writes code, it doesn't just overwrite your work. It proposes Edits.
- The AI will indicate it is writing code.
- You will see Green (added) and Red (removed) lines appear directly in your editor.
- Review the changes carefully.
- Accept/Reject: Click Accept (✓) to apply, or Reject (✗) to discard. Use "Accept All" or "Reject All" for multiple changes.
Chat Modes
Zaguán Blade supports two chat modes accessible from the Command Center:
The default mode for implementing and executing. The AI can read files, edit code, run terminal commands, and make changes to your project.
Investigate and build a plan before coding. The AI explores your codebase, researches approaches, and proposes architecture — no edits or commands are executed.
After reviewing a plan in Planning mode, use Implement to convert the plan into a code-mode request and start building.
Configuration
Configuration
- Theme - Zaguán Dark, Blade Coder, Blade Cream, Blade Robot
- Language - UI language preference
- Markdown View - Toggle edit/view mode for markdown files
Account Tab
- API Key - Your Zaguán subscription key for cloud AI models
- Manage Subscription - Link to your account dashboard
Local AI Tab
- Ollama - Connect to a local Ollama instance
- Ollama Cloud - Connect to Ollama via ngrok/remote
- OpenAI-compatible - Any OpenAI-compatible server endpoint
- Test Connection - Verify your local AI setup
- Refresh Models - Reload available models from providers
Storage Tab
- Storage Mode - Local (.zblade/ folder) or Server storage
- Sync Metadata - Sync conversation titles to server (no code)
- Enable Cache - Cache recent context for faster access
- Max Cache Size - Configure cache (10-500 MB)
Context Tab
Per-project- Max Context Tokens - Control context sent to AI (2K-32K)
- Enable Compression - Remote (cloud) or Local compression
- Allow .gitignored Files - Include gitignored files in AI context
About Tab
- Version - Current Zaguán Blade version
- Runtime - Tauri runtime information
- Engine - WebView engine details
- Local-First - Privacy and data control details
Teach the AI About Your Project
Zaguán Blade creates a .zblade/ folder in your project with an instructions.md file. Edit this file to provide project-specific instructions to the AI.
# Project Instructions
## Project Overview
<!-- Describe your project briefly -->
## Coding Guidelines
<!-- Add any specific coding conventions or patterns to follow -->
## Important Files
<!-- List key files the AI should be aware of --> The AI reads this file to understand your project's conventions and requirements.
Additional Features
Context Menu (Right-Click)
File Explorer Context Menu
Markdown Support
Markdown files automatically enable line wrapping. Use Ctrl+E to toggle between Edit and View modes.
PDF Viewing
Open PDF files directly in the editor. Zaguán Blade uses PDF.js to render PDFs natively — no external viewer required. PDFs are displayed in read-only mode, so you can review documents alongside your code without leaving the editor.
Screenshot Capture
Attach screenshots to your chat messages to give the AI visual context. Access capture options from the Feature Menu (grid icon) in the Command Center.
Capture Window
Select a window from the picker and attach a full screenshot of it.
Capture Region
Select a window, then drag to crop a specific region from it.
Upload Image
Attach an existing image file to the chat conversation for visual context.
Platform Notes (Linux / X11)
On X11-based desktops (e.g., Openbox, i3, Fluxbox), window capture has the following limitations:
- Current workspace only - The window picker only shows windows on your active workspace. Windows on other virtual desktops cannot be captured because X11 does not render off-screen windows.
- Window must be visible - The target window must be visible and not fully obscured by another window. If a window is covered, the capture may return a black image. Click the window to bring it to the front before capturing.
- Compositors help - If you run a compositor such as
picomorcompton, these limitations are largely eliminated - compositors maintain off-screen buffers for all windows, enabling capture of obscured or unfocused windows.
These limitations do not apply to Wayland desktops (GNOME, KDE Plasma 6) or macOS, which use compositing by default.
Privacy
No Telemetry
Zaguán Blade does not collect usage telemetry.
Local AI Privacy
Local AI models run entirely on your machine. Prompts and code never leave your computer when using Ollama or local OpenAI-compatible servers.
Local Storage Mode
When using local storage, your code and conversations never leave your machine.
Server Storage Mode
Conversations are encrypted on Zaguán servers. Cloud AI requests are processed on Zaguán infrastructure.
Custom System Prompts
When using Local AI models (Ollama or OpenAI-compatible), you can customize the system prompt for each model by creating a file with the model name or a compatible fallback name.
~/.config/zblade/prompts/[model-name].md %APPDATA%\zblade\prompts\[model-name].md ~/Library/Application Support/zblade/prompts/[model-name].md Blade tries provider-qualified, stripped, lowercased, and base-model prompt filenames, so exact case and format is no longer required.
You are an AI coding assistant in Zaguán Blade. Help users write, understand, and improve code efficiently.
# Core Rules
- When asked who and what you are, you are "glm-4.7-flash, an AI coding assistant in Zaguán Blade."
- Understand context before acting
- Match existing code style and conventions
- Verify libraries exist before using them (check imports, package.json, etc.)
- Use absolute file paths
- Read files before editing them
- Prefer symbol_search -> symbol_resolve -> read_file_range for code understanding
- Use grep_search when you need text-pattern search rather than symbol lookup
- Add comments sparingly - focus on "why" not "what"
- If unclear, ask for clarification
# Communication
- Be concise and direct
- Use markdown for code blocks
- No preamble ("Great!", "Certainly!")
- Jump straight to the task
# Available Tools
**get_editor_state** - Get active file, cursor position, and open files
**symbol_search** - Find functions, classes, methods, and types by name
**symbol_resolve** - Resolve a symbol to its exact file and line range
**symbol_references** - Find where a symbol is used
**read_file_range** - Read targeted line ranges from a file
**read_file** - Read full file contents when broader context is needed
**get_workspace_structure** - Get the project directory tree
**grep_search** - Search for text or regex patterns across files
**apply_patch** - Make precise edits to existing files
**write_file** - Create or overwrite a file
**run_command** - Execute shell commands
**todo_write** - Track multi-step work and show progress We encourage you to try Local AI and report any bugs or issues you encounter!
Tool Calls Reference
When creating custom system prompts for Local AI models, you'll need to include definitions for the tool calls Zaguán Blade supports. This reference document describes all available tools with their parameters and usage examples.
Known Issues
As an alpha release, there are some known limitations and bugs we're actively working on:
Local AI Support
Local AI support may not work consistently in all scenarios. We're actively improving reliability.
Search Functionality
Global search across project files is not yet implemented. The search icon has been hidden until this feature is ready.
Diff/Patch View
The Diff/Patch view may not be 100% complete. Edge cases in code review might behave unexpectedly.
Local Storage Mode
Local Storage Mode hasn't been extensively tested. Use with caution and report any issues.
Found a bug not listed here? Please report it on GitHub.
Alpha Release
AlphaWe define "Alpha" as "Feature incomplete, but good enough to be useful."
You will encounter bugs. When you do:
Thank you for being part of the future of coding.