Getting Started

Zap is a single Rust binary — no Python venv, no Node, no Docker. Install it and run it from any directory.

Configuration

All settings live in ~/.agent.toml. Create the file if it doesn't exist — zap reads it on every startup.

[model_routes]
coding = "codex/gpt-5.5"
review = "claude-opus-4-8"

Project Init

Run /init once in a new project and zap goes from blank-slate to fully context-aware in about 30 seconds. It builds the code index, reads your source files, and writes persistent knowledge files the agent loads on every future session.

Domain Map /understand

Run /understand after /init to extract a structured business-domain map — which modules own auth, billing, storage, and so on. One LLM call, pure code_map output, no source-file reads needed.

Two code_map calls, zero source-file reads, one edit_file write. Total: ~80 seconds including LLM round-trip.

Zap records how many source modules existed when /understand last ran. If the count drifts more than 10% (new modules added, old ones removed), the system prompt shows a nudge — "project structure has changed — run /understand to update the domain map" — so the map stays accurate without any manual bookkeeping.

Skill-First Context

Skills are plain markdown files that zap injects into the context window before the model sees your message. The key insight: only relevant skills fire. A greeting costs 31 tokens. A Rust question gets the Rust skill injected automatically.

Skills are markdown files with an optional YAML frontmatter block. Files without frontmatter are always-on Core skills.

Skills created for Claude Code or Gemini work in zap. Point skill_paths at ~/.claude/skills to share them automatically. This means you can keep the prompts and workflows you like while gaining Zap's code index, memory, context controls, and multi-provider runtime.

Code Graph

Most AI agents grep their way around your codebase. zap builds a structural map — what exists, what calls what, what imports what, and which files everything depends on — so the model answers questions in one query instead of guessing across ten.

Think of your project as a building.

Running /init (and every file change after) walks your source with tree-sitter and writes four kinds of facts to .zap/code.db:

Indexes the zap codebase in under 5 seconds: 264 files, 4,294 symbols, 20,272 call sites, 2,064 imports.

Every example below is a task you'd give an AI agent. The left column is what happens without a graph (most agents). The right column is what zap does in one query.

The hard kind of task — there's no symbol literally named "retry." The logic is scattered across handlers, configs, and helpers.

You don't have to think about any of this. The agent picks the right tool for each question automatically:

The database is plain SQLite. If you want to poke at it directly:

zap resolves names, not types. That means foo.bar() matches any bar with that name — not the one a full type-checker would resolve to. The win: queries finish in microseconds, in-process, with zero external dependencies. The cost: when several symbols share a name, the agent gets all matches and disambiguates with a qualifier filter (who_calls). In practice this is rarely the bottleneck — agents read the file anyway to confirm.

For queries that need full type resolution — cross-crate symbols, generic instantiations, trait impls — zap now ships three LSP tools that query a running language server: get_diagnostics (instant compiler errors), lsp_definition (type-resolved go-to-definition), and lsp_type_at (inferred type of any expression). AST tools answer structural questions in microseconds; LSP tools answer semantic questions when precision matters. Both layers work together.

Context Visibility

Zap shows you exactly what's in the context window — token counts per message, which skills fired, and total usage. You can inspect, manage, and trim the context without starting a new session.

Casual Messages

Not every message is a coding task. When you greet zap or ask something unrelated to your project, it skips skill injection entirely — saving the tokens for when they count.

The classifier runs locally and adds zero latency — it's a keyword heuristic, not a model call. It errs on the side of injecting skills when uncertain.

Dynamic MCP Loading

Zap supports the Model Context Protocol. MCP servers start pending — their tool schemas don't enter the context until explicitly needed. No 10,000-token schema dump on every turn.

Zap reads MCP config from ~/.zap/mcp.json (global) and .mcp.json (project-local). Both use the same Claude Code-compatible format.

Multi-Provider

Zap works with every major AI provider — and local models. Switch mid-session without restarting. The important part is that the surrounding agent stays the same: memory, tooling, indexing, permissions, and workflows do not disappear just because you changed models.

Security Boundary

Zap is explicit about what it touches. Every shell command and file write is shown before it runs. You confirm — or deny — each action.

Zap is open source under the MIT License. Read the code, fork it, audit it. The binary you run is built from the public source.

Session Memory

Zap keeps a running log of what was worked on and which files were touched. When you start a new session, the model has context from previous ones — without bloating the live context window.

You can also create a CLAUDE.md (or .zap/PROJECT.md) with permanent project-level context that fires on every message as a Core skill.

Autonomous Mode

/goal <condition> runs turns automatically until the model signals it's done or a turn limit is reached. Use it for multi-step tasks you'd otherwise have to shepherd turn-by-turn.

The model runs tool calls autonomously each turn. When it's finished it ends its response with ✓ DONE and the loop stops. The sidebar shows the goal condition, current turn, and elapsed time while it runs. Ctrl+C cancels at any point.

Scheduler

Zap can run recurring goals on a schedule inside the TUI. Use it for background maintenance tasks like dependency checks, inbox triage, changelog drafting, or periodic repo health scans. It's one of the clearest examples of Zap being powerful in day-to-day use, not just in one-shot prompts.

Commands Reference

Type any command at the zap prompt. Tab-completion is available for all slash commands.