User Guide

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

Core Principle

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

1

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.

Local AI Cloud AI Hybrid
2

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.

3

Choose Storage Mode

When opening a project for the first time, select your preferred storage mode for conversation history.

Local Storage Server Storage

Interface Overview

📁

Activity Bar

  • Files - Project file explorer
  • Git - Stage, commit, push
  • History - Browse file history
  • Settings - Preferences & account
💻

Center Stage

Editor

High-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

Terminal

Integrated terminal for running commands. The AI can see and interact with this terminal when executing commands.

Keyboard Shortcuts

Global Shortcuts

F11Toggle fullscreen mode
Ctrl+WClose current tab
Ctrl+TabCycle to next tab
Ctrl+Shift+TabCycle to previous tab
EscapeClose modals/popups

File Operations

Ctrl+NNew File
Ctrl+OOpen Folder
Ctrl+SSave current file
Ctrl+Shift+SSave As
Alt+F4Exit application

Editor Shortcuts

Ctrl+ZUndo
Ctrl+Shift+ZRedo
Ctrl+FFind in file
F2Rename symbol
Ctrl+EToggle Edit/View mode (Markdown)

Chat Input

EnterSend message
Shift+EnterNew line (without sending)
Arrow Up/DownNavigate command suggestions
Tab or EnterSelect command from autocomplete
EscapeClose command autocomplete

Special Commands

Type @ in the chat input to access these special commands:

@web <url>

Fetches content from a URL and uses it as context for the AI. Great for referencing documentation or articles.

@research <topic>

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 @path in 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.

  1. The AI will indicate it is writing code.
  2. You will see Green (added) and Red (removed) lines appear directly in your editor.
  3. Review the changes carefully.
  4. 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:

Code Mode

The default mode for implementing and executing. The AI can read files, edit code, run terminal commands, and make changes to your project.

Planning Mode

Investigate and build a plan before coding. The AI explores your codebase, researches approaches, and proposes architecture — no edits or commands are executed.

Implement Action

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.

.zblade/instructions.md markdown
# 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)

Cut / Copy / Paste Undo / Redo Find Rename Symbol Show Call Graph

File Explorer Context Menu

New File / Folder Rename Delete Cut / Copy / Paste Open in Terminal

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 picom or compton, 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.

Linux: ~/.config/zblade/prompts/[model-name].md
Windows: %APPDATA%\zblade\prompts\[model-name].md
macOS: ~/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.

~/.config/zblade/prompts/glm-4.7-flash:Q4_K_M.md markdown
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

Alpha

We 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.