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.

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.

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.

Code Indexing

Zap builds an AST-level symbol index of your project using tree-sitter and stores it in a local SQLite database at .zap/code.db. The model can query it to find what already exists before deciding what to create.

Takes 10–30 seconds for medium projects. The index is gitignored by default — it's a local cache, not a committed artifact.

The model queries the index directly with SQLite. No fuzzy search, no hallucination — it either finds the symbol or it doesn't.

Without an index, an agent must grep through files to find where a symbol lives — that's multiple tool calls before it can even start. With the index built, zap resolves it in one SQL query.

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.

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.

Commands Reference

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