by zap-coding-agent (open source) · Windows, macOS, Linux, Claude API, Anthropic API, локальные модели через Ollama/vLLM/LM Studio

показать оригинал переведено ИИ

⚡ Zap Coding Agent

Сайт · Документация · Roadmap · Changelog · Установка · Демо

ZAP — terminal-first, локальный AI coding-агент на Rust. Использует AST-индексацию кодовой базы и ленивую загрузку skills, чтобы полностью убрать раздувание промпта и минимизировать расход токенов контекста — единый бинарник, без рантайма.

  ╭────────────────────────────────────────────────────────────────────╮
  │                                                                    │
  │   _____     _     ___                                              │
  │    ___/    /_\   | _ \   fast AI coding agent  v0.15.19           │
  │   /       / _ \  |  _/                                            │
  │  /_____  /_/ \_\ |_|                                              │
  │                                                                    │
  ├──────────────────────────────────────┬─────────────────────────────┤
  │  model     claude-sonnet-4-6         │  Tips for getting started   │
  │  backend   Anthropic API             │    Tab  ↑↓  autocomplete    │
  │  mode      ask                       │    /          commands      │
  │                                      │    /provider  switch LLM    │
  │  ~/my-project                        │    /help      all commands  │
  ╰──────────────────────────────────────┴─────────────────────────────╯

📺 В обзорах: "I Found a Better AI Coding Agent (ZAP)" — видеообзор от The Curious Guy (@dhanushnehru).

Искоренение раздувания промпта в AI coding-агентах

Откройте любой популярный AI coding-агент и изучите сырой запрос, который он отправляет LLM. Вы найдёте сотни — иногда тысячи — строк системного промпта, отправляемого на каждый ход, независимо от того, чем вы на самом деле занимаетесь.

Мы это измерили. Вот что отправляют Gemini CLI и OpenCode, когда вы просите их написать Spring Boot сервис против React-компонента — два совершенно разных языка, фреймворка и конвенции:

Матрица токен-эффективности LLM (задачи Spring Boot vs. React)

AI Coding Agent	Запрос Spring Boot	Запрос React	Идентичный базовый промпт?	Внедрён языковой контекст?
Gemini CLI	4096 токенов	4096 токенов	✅ Да	❌ Нет (0 упоминаний Java/React)
OpenCode	2003 токена	2003 токена	✅ Да	❌ Нет (`baseAnthropicCoderPrompt`)
ZAP (Rust)	1889 токенов	1661 токен	❌ Нет	✅ Да (+650 Java / +422 React токенов)

Gemini CLI отправляет одинаковый промпт на 4096 токенов в обоих случаях. Слово "java" не встречается нигде в его файле промпта на 68 410 символов. Как и "react", "kotlin" или любой другой язык. LLM, пишущая ваш Spring Boot сервис, и LLM, пишущая ваш React-компонент, получают идентичные инструкции. (источник)

OpenCode использует единую статическую строковую константу — baseAnthropicCoderPrompt — отправляемую дословно на каждом ходу, для каждого типа задачи. Ноль упоминаний Java, TypeScript, Rust, Python, React или любого конкретного языка. (источник)

Это не просто трата ресурсов. Именно поэтому эти агенты дают непоследовательный вывод — у модели нет языко-специфичных указаний, поэтому она изобретает собственные конвенции от хода к ходу.

zap отправляет разный промпт для разных задач — Java-skill срабатывает для Spring Boot, React-skill срабатывает для компонентов — а приветствие стоит 12 токенов, а не 2000–4000.

Полная методология, сырые подсчёты токенов и ссылки на источники: content/evidence/system-prompt-comparison.md Серия на Medium: Introducing ZAP — The Open-Source AI Coding Agent That Doesn't Bloat Your LLM Context

Качество контекста превыше всего

Каждое дизайн-решение в zap следует одному принципу: каждый токен в окне контекста LLM должен заслужить своё место. Контекст, не улучшающий качество вывода — трата ресурсов: он разбавляет внимание, сжигает бюджет и даёт непоследовательные результаты.

Этот принцип управляет всем:

Механизм	Что обеспечивает
Внедрение skill	Отправляется только языко- и задаче-специфичное руководство, а не монолит "один размер для всех"
AST-индекс кода	Агент знает, что существует, прежде чем решить, что создавать — без слепых записей
Команда `/init`	Автоматически генерирует специфичные для проекта файлы контекста, так что каждая сессия начинается информированной
Файлы контекста	`ZAP.md`, `.zap/understanding.md`, `.zap/context.md`, `.zap/session_log.md` — поддерживаются автоматически, загружаются по требованию
Обнаружение бытовых реплик	Приветствия стоят ~31 токен, а не 2000–4000
Ленивый MCP	Схемы инструментов сервера остаются вне контекста, пока модель явно их не подключит
Отображение стоимости в токенах	Каждый ход показывает, что именно вошло в контекст — skills, сообщение, система и оценочная $

Что обновляется и когда

zap поддерживает четыре файла проектного контекста, каждый обновляется в конкретный момент, чтобы держать агента в курсе, не загрязняя окно контекста:

Файл	Обновляется когда	Что содержит	Загружается когда
`ZAP.md`	`/init` (вручную, один раз)	Обзор проекта, команды сборки, архитектура, список "не трогать"	Каждая сессия (по требованию)
`.zap/understanding.md`	`/init` + `/understand`	Карта навигации + карта бизнес-доменов	Каждая сессия (по требованию)
`.zap/context.md`	Конец каждой сессии (авто)	Последняя сессия: цель, затронутые файлы, что дальше	Начало сессии (по требованию)
`.zap/session_log.md`	Каждая сессия (авто)	История всех прошлых сессий, индексированная по дате	По запросу (по требованию)

Эти файлы никогда не предзагружаются в окно контекста — модель читает их только когда актуально, используя read_file. Это значит, что сессия по исправлению опечатки не платит за загрузку всей архитектуры проекта.

Результат

Первая сессия: /init анализирует ваш репозиторий и загружает все знания о проекте за ~30 секунд
Запустите /understand: один вызов LLM отображает каждый бизнес-домен на файлы, которые им владеют — агент сразу переходит к нужному модулю без гадания
Возвращающиеся сессии: агент уже знает, над чем вы работали, какие файлы изменились и что осталось незавершённым
Каждый ход: skills внедряют только релевантное, индекс сообщает агенту, что существует, а бытовые сообщения полностью пропускают накладные расходы

Реальный вывод: запуск `/understand` на самом репозитории zap

You: /understand
zap: ⚡ Extracting business domain map (one LLM call)…

  ↳ code_map '.'     → 2000 symbols  (6ms)
  ↳ code_map 'src'   → 1356 symbols  (3ms)
  ↳ edit_file '.zap/understanding.md'  ← domain map written

Что было записано в .zap/understanding.md:

## Domain Map

### Business Domains

| Domain                   | Owns                                     | Key entry points                    |
|--------------------------|------------------------------------------|-------------------------------------|
| Agent runtime            | agent_core, cli, main, lib               | authenticate, Session::new          |
| LLM provider integration | llm_client/*, http                       | send, stream                        |
| Tool execution + safety  | tools/*, permission_manager, shell_runner| ToolRegistry::execute               |
| Project context + prompt | context_manager, project, plan_execution | build_system_prompt, handle_user_turn|
| Code intelligence        | code_index/*                             | index_dir, global_callers_of        |
| MCP integration          | mcp                                      | mcp_connect, list_tools             |
| Persistence + memory     | persistence, project                     | init, save_session_context          |
| Skills + workflow        | skill_manager, default_skills/*          | detect_domain_scope                 |
| Remote session sharing   | remote, remote_channel                   | spawn_tunnel, broadcast             |

### Cross-Cutting Concerns
- Error handling: `anyhow::Result` everywhere; tool errors surfaced as text responses
- Logging: `crate::log::write` (file-only, never stdout)
- Config: `Config` struct in src/config.rs, loaded once at startup
- Security: `permission_manager`, `secret_scanner`, `audit` enforce approval and logging

### Dependency Direction
tools → session → agent_core; llm_client ← session only; nothing imports session from tools

Два вызова code_map, ноль чтений исходных файлов, один edit_file. Карта доменов автоматически внедряется в каждую будущую сессию.

code indexing demo

Чем zap отличается

1. Skill-First подход — контекст, заслуживающий своё место

Большинство AI coding-агентов загружают огромный системный промпт в каждый запрос — языковые конвенции, архитектурные заметки, командные правила, паттерны API, всё это, релевантно или нет. zap заменяет эту стену системой skills: markdown-файлами, внедряемыми хирургически, только когда ваше сообщение их запускает.

Два вида skills:

Вид	Когда внедряется	Пример
Always-on	Каждый ход, встроен в базовый системный промпт	`karpathy-guidelines` — 4 принципа кодинга Андрея Карпатого
Triggered	Только когда ваше сообщение совпадает с ключевыми словами	`rust` срабатывает на "cargo", "fn ", "trait "; `git` срабатывает на "commit", "push"

Встроенные skills (скомпилированы в бинарник, без конфигурации):

Skill	Тип	Срабатывает на
`karpathy-guidelines`	always-on	каждый ход
`rust`	triggered	rust, cargo, crate, async fn, clippy…
`python`	triggered	python, pip, pytest, dataclass…
`typescript`	triggered	typescript, tsx, interface, npm…
`react`	triggered	react, component, jsx, hook, useState…
`go`	triggered	go, goroutine, chan, go.mod…
`git`	triggered	commit, branch, merge, pull request…
`code-review`	triggered	review, pr review, lgtm, critique…
`debugging`	triggered	debug, error, crash, panic, stacktrace…
`security`	triggered	auth, password, token, jwt, xss, sql injection…

Автоопределение стека запускает нужный языковой skill при старте — Rust-проект с Cargo.toml автоматически получает загруженный skill rust.

Пример — Rust-проект, также загружен кастомный skill api-conventions:

Вы вводите	Внедрённые skills	Base + skills
`"refactor this async fn to use channels"`	karpathy + rust	~2.4к токенов
`"commit these changes"`	karpathy + git	~2.0к токенов
`"add a new REST endpoint"`	karpathy + api-conventions	~2.2к токенов
`"explain what this function does"`	только karpathy	~1.8к токенов

Честный базис: always-on skill karpathy-guidelines вместе с базовым системным промптом вместе занимают ~1.8к токенов — гораздо экономнее, чем Claude Code (~10к) или Gemini CLI (~8к), но не та цифра "200 токенов", которую можно увидеть в старой документации.

Кастомные skills переопределяют встроенные с тем же именем. Напишите skill один раз, и zap внедрит его именно тогда, когда нужно:

---
name: api-conventions
description: REST endpoint conventions for this project.
trigger: ["endpoint", "route", "handler", "REST"]
tokens: ~400
---
All endpoints must validate input with ValidateRequest(), return structured
errors as {"error": "...", "code": N}, and use snake_case JSON keys.

Always-on skill (нет поля trigger: — внедряется каждый ход):

---
name: our-principles
description: Team engineering principles.
---
We ship small, reversible changes. Every PR needs a test. No console.log in prod.

Куда их класть:

Путь	Область	Приоритет
`.zap/skills/`	проект — коммитить в git, общие для команды	наивысший
`~/.zap/skills/`	личные — все проекты	средний
бинарник	встроенные значения по умолчанию	наименьший

При первом запуске zap автоматически записывает все встроенные skills в ~/.zap/skills/ — откройте любой файл там, чтобы прочитать или отредактировать. Файлы с тем же именем, которые вы создаёте, переопределяют встроенную версию при следующем запуске.

/skill list              # увидеть все skills с источником и меткой always-on/triggered
/skill show <name>       # превью содержимого + описание + лицензия
/skill export <name>     # переэкспортировать встроенный skill в ~/.zap/skills/ (если удалили)
/skill export --all      # переэкспортировать все встроенные skills
/skill create <name>     # заскаффолдить новый skill в .zap/skills/
/skill capture <name>    # извлечь инструкции из этой сессии в переиспользуемый skill

2. AST-индексация кода против агентного поиска

Большинство агентов навигируют код так же, как shell-скрипт — grep по строке, надежда, что результат — то, что вы имели в виду. zap строит настоящий AST-индекс символов при старте, используя tree-sitter + SQLite, давая модели подлинное структурное понимание вашей кодовой базы.

Проблема: агенты, которые пишут не глядя

Попросите большинство coding-агентов "добавить все API-слои для управления пользователями" в существующем проекте, и вы увидите предсказуемый набор ошибок:

Создаются дублирующие файлы — src/user_repository.rs уже существует, но агент создаёт src/repositories/user_repo.rs рядом, потому что никогда не проверял
Игнорируются существующие паттерны — проект использует трейт Repository<T> с конкретным типом ошибок; агент изобретает свой стиль доступа к БД с нуля
Скаффолдинг поверх существующего кода — src/routes/, src/models/, src/db/ уже существуют с boilerplate'ом; агент воссоздаёт их
Упущенные абстракции — уже существует BaseRepository или общий тип AppError; агент пишет дубликат

Это не сбои модели — это сбои контекста. Агент пишет вслепую, потому что его окно контекста никогда не содержало файлы, которые нужно было проверить.

Как индекс это исправляет

Когда вы задаёте zap тот же вопрос, прежде чем написать хоть одну строку, он запрашивает индекс:

-- Does a user repository already exist?
SELECT path, line, kind FROM symbols WHERE name LIKE '%UserRepo%' OR name LIKE '%UserStore%';

-- What repository pattern does this project use?
SELECT name, path, line, signature FROM symbols WHERE kind = 'trait' AND name LIKE '%Repository%';

-- What's already in the db/ directory?
SELECT name, kind, line FROM symbols WHERE path LIKE '%/db/%' ORDER BY path, line;

Это выполняется за миллисекунды против локального индекса SQLite — без чтения файлов, без grep, без набивки контекста. Модель знает, что существует, прежде чем решить, что создавать. Она добавляет в src/user_repository.rs вместо создания нового. Она реализует существующий трейт Repository<T> вместо изобретения нового паттерна.

Когда вы просите zap "отрефакторить структуру UserStore", он не ищет строку "UserStore" — он ищет символ в индексе, находит точный файл и номер строки, читает только этот раздел и вносит точную правку. Без ложных совпадений, без чтения целых файлов ради одной функции.

Индекс инкрементальный — при последующих запусках перепарсиваются только файлы, изменившиеся с прошлой сессии. Фоновый индексатор запускается каждые 120с во время интерактивных сессий, так что индекс остаётся свежим по мере редактирования. Холодная индексация репозитория на 50к строк занимает несколько секунд; тёплые старты почти мгновенны.

Всегда актуален во время правок — каждый раз, когда zap пишет файл, он немедленно переиндексирует этот файл перед следующим ходом LLM. Модель никогда не запрашивает устаревший индекс для файлов, которые только что изменила.

Использование индекса логируется на каждом ходу — каждый раз, когда вызов инструмента отвечается индексом (а не откатом на grep), zap логирует это в ~/.zap/zap.log и ~/.zap/audit.jsonl:

[INDEX] hit · find_definition · 'UserRepository' · 3 result(s)
[INDEX] hit · code_map · 'src/db/' · 42 symbol(s)
[INDEX] miss · find_definition · 'legacy_fn' · grep fallback

Это делает процесс аудируемым — вы можете точно увидеть, когда использовался индекс, а когда агенту пришлось откатиться на текстовый поиск.

Поддерживаемые языки: Rust, Python, TypeScript, JavaScript, Go, Java

Инструменты на базе индекса:

Инструмент	Что делает
`code_map`	Структурный обзор любого файла или директории — функции, структуры, классы, перечисления, с номерами строк
`find_definition`	Переход напрямую к месту определения символа — сначала AST-индекс, затем ripgrep
`find_references`	Каждое место вызова символа по всей кодовой базе
`who_calls`	Все вызывающие функции, опционально с фильтром по квалификатору
`file_imports`	Всё, что импортирует файл
`where_imported`	Каждый файл, импортирующий данное имя — радиус поражения для переименований
`find_subtypes` / `find_supertypes`	Обход иерархии типов
`pack_context`	Автоматически выбирает наиболее значимые файлы для задачи и возвращает их в рамках бюджета токенов
`ripple_analysis`	BFS радиус поражения: кто вызывает символ, кто вызывает этих вызывающих и т.д. — мгновенно, без компилятора
`get_diagnostics`	Ошибки/предупреждения компилятора через language server — то же, что `cargo check`, но без запуска
`lsp_definition`	Go-to-definition с разрешением типов для кросс-крейтовых символов (std, зависимости, дженерики)
`lsp_type_at`	Точный выведенный тип любого выражения — та же подсказка, что показывает ваш редактор, только в агенте

Модели предписано всегда использовать code_map или find_definition, прежде чем прибегать к read_file — так что она читает только те строки, которые действительно нужны, а не целые файлы.

Как индекс питает каждый ход LLM:

You: "refactor the UserStore struct"

  zap (tool call)  →  find_definition("UserStore")
  SQLite index     →  src/db/user_store.rs:42  ← instant, no file scan
  zap (tool call)  →  read_file("src/db/user_store.rs", offset=40, limit=60)
  zap (tool call)  →  edit_file(...)            ← precise edit, right lines

Without index: grep entire repo → read 3 wrong files → hallucinate location
With index:    SQLite lookup → read 20 lines → done

Радиус поражения прежде, чем вы что-то тронете:

You: "what breaks if I change the signature of parse_config?"

  zap (tool call)  →  ripple_analysis("parse_config", depth=3)
  call graph BFS   →  Depth 1 — 4 direct callers across 3 files
                       Depth 2 — 11 callers of callers across 6 files
                       Depth 3 — 2 more files indirectly affected
  zap              →  "Here's what's at risk — want me to check each caller?"

Ошибки компилятора без запуска cargo check:

You: "check if my edit to src/lsp/client.rs is correct"

  zap (tool call)  →  get_diagnostics("src/lsp/client.rs")
  rust-analyzer    →  src/lsp/client.rs:47 error[E0308]: mismatched types
  zap              →  "Line 47 has a type mismatch — here's the fix..."

Отчёт о качестве кода — тот же SQLite-индекс питает /index quality, читаемый человеком отчёт о здоровье кода, запускаемый прямо в TUI:

Code Health  ·  27 files  ·  1043 symbols  ·  ⚡ 74/100
────────────────────────────────────────────────────────────

File sizes  (lines)
────────────────────────────────────────────────────────────
  ⚠ 2382  src/session/commands.rs    ████████████████████  37 sym
  ⚠ 2266  src/tui/render.rs          ████████████████████  48 sym
  ⚠ 1789  src/session/mod.rs         █████████████         45 sym
  ⚡ 1177  src/tui/mod.rs             ████████
  ·   527  src/tui/app.rs             ███
  ·   312  src/code_index.rs          ██

  ⚠ >1000 lines   ⚡ 500–1000   · healthy

God objects  (>15 methods — split candidates)
────────────────────────────────────────────────────────────
  Session                        45 methods  (mod.rs)
  ToolRegistry                   18 methods  (tool_registry.rs)

Dead code candidates  (pub fn, ≤1 reference)
────────────────────────────────────────────────────────────
  export_skill                   (skill_manager.rs:599)

Исследуйте индекс сами

Индекс — обычная база SQLite в .zap/code.db — вы можете запрашивать её напрямую в любой момент, сессия zap не требуется.

macOS / Linux — интерактивный скрипт-исследователь:

./scripts/explore-db.sh

Запускает интерактивное меню с 10 готовыми запросами (обзор, топ файлов по числу символов, поиск по имени, сырой SQL и другое). Требует только sqlite3, который поставляется с macOS. На Linux: sudo apt install sqlite3.

Почему zap индексирует, когда Claude Code намеренно этого не делает

У Claude Code (собственного CLI Anthropic) нет встроенной индексации кода. Нет tree-sitter, нет SQLite, нет ctags. Он использует чистый агентный поиск — grep + glob + read, выбираемые моделью во время выполнения. Это было намеренное, протестированное решение.

Борис Черни (создатель Claude Code) публично подтвердил, что Anthropic построила и протестировала подход RAG/векторного индекса на раннем этапе и отказалась от него, потому что агентный поиск выиграл "с большим отрывом". Причины:

Grep находит точные совпадения; эмбеддинги вносят ложные срабатывания
Не нужно строить или поддерживать индекс
Дрейф индекса — код постоянно меняется во время сессий редактирования
Более простая архитектура с меньшим числом режимов отказа

Источники: Claude Code Doesn't Index Your Codebase — vadim.blog · Building Claude Code with Boris Cherny — Pragmatic Engineer · Официальная документация Claude Code

Сообщество заметило этот пробел — существует несколько open-source MCP-серверов, добавляющих индексацию к Claude Code: - colbymchenry/codegraph — tree-sitter + SQLite FTS5 - cocoindex-io/cocoindex-code — поиск на базе AST - zilliztech/claude-context — MCP векторного поиска

И открытые запросы фич с просьбой добавить это в Anthropic нативно: #4556 · #9277

zap делает противоположную ставку. Агентный поиск хорошо решает семантические вопросы ("найди код, связанный с обработкой платежей"). Постоянный AST-индекс лучше решает структурные вопросы — "что уже существует в этом модуле?", "какие файлы реализуют этот паттерн?", "уже есть UserRepository?" Это именно те вопросы, которые важны, когда агент собирается написать новый код. Без индекса агент может искать только то, что знает искать. С индексом он знает, что существует, прежде чем решить, что создавать.

Два подхода решают разные режимы отказа. Агентный поиск избегает дрейфа индекса. AST-индексация избегает слепых записей в кодовую базу, которую агент полностью не прочитал.

Меняет ли индекс качество на скорость?

Нет — он меняет одну стратегию поиска на лучшую, с полным откатом для случаев, которые индекс не покрывает.

Обычно поднимаемое беспокойство: "агентный поиск выиграл с большим отрывом" — так сказал Борис Черни, когда Anthropic отказалась от своего подхода RAG/векторов на раннем этапе. Это правда, и рассуждение обосновано: векторные эмбеддинги вносят ложные срабатывания (семантически похожие, но неверные совпадения), требуют шага сборки и дрейфуют по мере изменения кодовой базы. Но zap не использует векторы или RAG. Он использует AST-индекс символов — принципиально иное. Поиск символа либо возвращает точное определение, либо нет. Без галлюцинированных совпадений, без порога схожести для настройки, без модели эмбеддингов для поддержки.

Индекс покрывает структурные вопросы — там, где агентный поиск платит полную цену:

Каждый раз, когда Claude Code отвечает на "где определён UserRepository?", модель тратит токены на решение, какие файлы читать, делает несколько вызовов grep, читает частичное содержимое файла и синтезирует ответ. Индекс отвечает на тот же вопрос одним запросом SQLite. На репозитории в 50к строк это разница между 1 вызовом инструмента и 5.

Grep обрабатывает то, что не покрывает индекс:

Индекс знает имена символов, виды и местоположения. Он не делает открытый семантический поиск — "найди всё, связанное с потоком оформления заказа" — это вопрос для grep, а не для символов. Модель zap использует search_code (ripgrep) для таких случаев. Индекс и grep — взаимодополняющие слои, а не конкурирующие. Каждый промах find_definition автоматически откатывается на ripgrep — так что zap никогда не работает хуже чистого агентного поиска, только лучше, когда символ проиндексирован.

Вопрос	zap	Чистый агентный поиск
"Уже существует `UserRepository`?"	мгновенный SQL-запрос	скан grep + чтение файлов
"Какому паттерну следуют существующие реализации?"	запрос схемы по всем типам	чтение нескольких файлов
"Найди весь код, связанный с потоком оформления заказа"	ripgrep (то же, что агентный)	ripgrep
Большая кодовая база, холодный старт	индекс предпостроен, без чтения файлов	холодный grep на каждом ходу

Индекс не снижает качество — он снижает число чтений файлов, необходимых для ответа на структурные вопросы, что напрямую снижает стоимость токенов и шанс, что модель запишет поверх уже существующего.

3. Построен на Rust: локальный AI coding-агент в едином бинарнике

zap полностью написан на Rust и поставляется как единый статически слинкованный бинарник.

Без Python venv. Без Node.js. Без Docker. Без ада зависимостей.
Мгновенный старт — холодный старт за миллисекунды, не секунды.
Малый объём памяти — процесс занимает ~20 МБ в простое.
Безопасен по памяти по конструкции — без переполнений буфера, без use-after-free, без гонок данных.
Скомпилируй раз, запускай где угодно — положи бинарник в PATH, и он работает.

cargo build --release
cp target/release/zap ~/.local/bin/zap
# и всё

4. Поддержка MCP — ленивая загрузка, кросс-агентная совместимость

MCP (Model Context Protocol) — открытый стандарт. Любой MCP-сервер, настроенный в zap, работает и в Claude Code, Cursor, Kiro и других агентах — формат конфига общий. zap добавляет два опциональных поля (description, toolsHint), которые другие агенты молча игнорируют, так что ваш конфиг-файл полностью переносим.

Расположение файлов конфигурации

Файл	Область
`~/.zap/mcp.json`	Глобально — применяется к каждой сессии
`.mcp.json` (корень проекта)	Локально для проекта — коммитится в git, имеет приоритет

Как работает ленивая загрузка

Большинство агентов подключаются к каждому настроенному серверу при старте и сбрасывают все схемы инструментов в контекст LLM на каждом ходу. Десять серверов × пять инструментов каждый = 10 000+ потраченных впустую токенов на запрос, используете вы их или нет.

zap держит каждый сервер в состоянии ожидания при старте. Вместо их схем инструментов LLM получает один лёгкий заглушечный stub:

mcp_connect(server)
  - filesystem: Read/write files in /tmp and the project  [tools: read_file, write_file, list_directory…]
  - fetch: Fetch web pages as markdown                    [tools: fetch]
  - memory: Persistent knowledge graph                    [tools: create_entities, search_nodes…]

Когда LLM решает, что ей нужен сервер, она вызывает mcp_connect("filesystem"). zap запускает процесс, выполняет рукопожатие, получает реальный tools/list и регистрирует эти инструменты — всё в рамках того же агентного хода. Самый следующий вызов LLM видит полную схему инструментов и может вызывать их напрямую.

Этап	Другие агенты	zap
Старт	Запускает все процессы серверов	Только читает конфиг — ноль процессов
Список инструментов LLM на ходу	Все схемы инструментов, всегда	Один stub `mcp_connect`, пока не потребуется
Первое использование сервера	Уже подключён	Запускает процесс по требованию, ~200 мс
После первого использования	—	Реальные схемы в контексте, `mcp_connect` исчез

Команды MCP

/mcp list              список всех серверов — подключённые, ожидающие или неудачные
/mcp edit              открыть ~/.zap/mcp.json в $EDITOR
/mcp edit project      открыть .mcp.json (конфиг уровня проекта)
/mcp path              вывести оба пути к файлам конфигурации

5. Безопасность — приоритетная задача

zap работает с вашим исходным кодом, учётными данными и shell — поэтому относится к безопасности как к ключевой функции, а не второстепенной мысли.

Агент не может выполнить ничего деструктивного без вашего явного одобрения

В режиме ask по умолчанию каждая операция записи и shell-команда блокируются до вашего одобрения. Инструменты только для чтения выполняются свободно. Только инструменты, способные причинить ущерб, требуют вашей подписи:

Класс инструментов	Режим ask	Режим auto	Режим deny
`read_file`, `search_code`, `code_map`, `git_status`	✓ всегда разрешено	✓	✗ заблокировано
`edit_file`, `write_file`, `batch_edit`	запрос	✓	✗
`shell`	запрос	✓	✗
`spawn_agent`	запрос	✓	✗

Три режима на выбор:

Режим	Когда использовать
`ask` (по умолчанию)	Любая интерактивная сессия — вы остаётесь под контролем
`auto`	Изолированный CI, скрипты или headless-запуски, где вы контролируете окружение
`deny`	Полностью только для чтения — агент может читать и рассуждать, но не может записать ни байта или выполнить какую-либо команду

Переключайтесь в любой момент: /permissions ask, /permissions auto, /permissions deny.

Sandbox shell — режим workdir ограничивает shell-команды корнем проекта; режим container оборачивает команды через Docker/Podman с --network none для полной изоляции.

Сканер секретов — 25+ паттернов, блокирует перед отправкой

Перед отправкой любого контента в облачную LLM zap сканирует его на секреты:

API-ключи: Anthropic (sk-ant-), OpenAI (sk-proj-), Stripe боевые и тестовые ключи
VCS-токены: GitHub (ghp_, ghs_, github_pat_), GitLab (glpat-)
Облачные учётные данные: AWS access keys (AKIA), поля AWS secret key, GCP service account JSON
Криптографический материал: блоки PEM приватных ключей (-----BEGIN), JWT-токены
Обобщённые поля учётных данных: password=, api_key=, secret=, access_token= в конфигурационных файлах

Совпадения блокируются, и вас предупреждают с номером строки и редактированным превью — контент никогда не пересылается молча.

Полный аудиторский след

Каждый вызов инструмента добавляется в ~/.zap/audit.jsonl как структурированная JSON-запись с временной меткой, именем инструмента и результатом.

/audit 20       # показать последние 20 записей аудита в TUI

Undo для каждой правки

Перед изменением любого файла zap снимает снапшот предыдущего содержимого в памяти.

/undo src/main.rs      # восстановить файл к состоянию до правки

6. `/init` — от нуля до осведомлённости о контексте за 30 секунд

Большинство агентов начинают каждую сессию вслепую. Они не знают структуру вашего проекта, ваши команды сборки, вашу архитектуру или над чем вы работали в прошлый раз.

/init исправляет это раз и навсегда.

/init

Автоопределяет ваш стек — определяет язык/фреймворк из вашего репозитория
Индексирует кодовую базу — строит AST-индекс символов, чтобы агент мог структурно навигировать с первого хода
Создаёт ZAP.md — обзор проекта, команды сборки/тестов, разметку архитектуры, ключевые файлы и список "не трогать"
Создаёт .zap/understanding.md — более глубокое техническое резюме: карту модулей, потоки данных, неочевидные паттерны, ограничения
Записывает .zap/project.json — сохраняемый конфиг проекта (язык, состояние индекса)

Общее время: ~30 секунд. С этого момента каждая сессия начинается информированной — агент знает ваш проект.

7. Автоматизированная непрерывность сессий — никогда не теряйте нить

У Claude Code и большинства других агентов нет постоянной памяти о том, над чем вы работали в прошлый раз. Каждую сессию вы начинаете заново, повторно объясняя цель, вставляя ошибку, которую отлаживали, и перезагружая контекст, который уже установили.

zap полностью автоматизирует передачу между сессиями — вы продолжаете точно с того места, где остановились, ничего не делая.

Что происходит в конце сессии

Когда вы закрываете zap (/exit, Ctrl+C или закрытие терминала), он автоматически:

Резюмирует, что дальше — делает небольшой вызов LLM по последним 10 сообщениям, генерируя 1-3 пункта с конкретными следующими шагами: имена файлов, имена функций, фичи в процессе
Записывает .zap/context.md — структурированный файл передачи: цель, затронутые файлы и сгенерированное LLM резюме "Что дальше"
Дополняет .zap/session_log.md — датированную историю каждой сессии: цель + изменённые файлы

Что происходит в начале сессии

Когда вы снова открываете zap:

Строка "Над чем велась работа" появляется в баннере старта — вы видите её прежде, чем что-то напечатать
Полный context.md внедряется в системный промпт как ## Last Session Handoff — агент уже знает контекст до вашего первого сообщения

  ◌ Last: Refactoring session/mod.rs into submodules
  ◌ Files: src/session/commands/code.rs, src/session/turn.rs

Память агента между проектами

/memory set key value сохраняет факты (паттерны API, командные конвенции, предпочитаемые подходы), внедряемые в каждую сессию, во всех проектах:

/memory set error-style  always use anyhow::Context for wrapping errors
/memory set test-db      never mock the database — always use a test container
/memory list             show all saved facts
/memory del error-style  remove a fact

8. Поддержка SLM — локальные модели как полноценные исполнители

zap — единственный coding-агент, запускающий локальные малые языковые модели как полноценных исполнителей механической массовой части работы с кодом — пока топовые модели занимаются мышлением.

Запуск локальных моделей через LM Studio, Ollama или любой OpenAI-совместимый эндпоинт — без API-ключа, данные не покидают вашу машину
Структурированное выполнение плана — топовая модель проектирует план, ваша локальная SLM выполняет его шаг за шагом (100% успеха на заранее написанных планах в исследовании)
Предварительная индексация — zap --index-only строит AST-индекс, чтобы SLM навигировали по коду через code_map/find_definition вместо медленных ручных чтений
Streaming watchdog — терпит долгие prefill'ы локальной модели (минуты) с уведомлениями о прогрессе и определением простоя
Профиль core-инструментов — AGENT_TOOL_PROFILE=core отправляет только 6 схем инструментов, делая вызов инструментов посильным для малых моделей

Полная документация по поддержке SLM → · Результаты исследований →

Возможности вкратце


TUI	Терминальный UI на Ratatui — потоковый вывод, боковая панель со счётчиками токенов, просмотрщик diff (Ctrl+G), файловый браузер (Ctrl+F), подсветка синтаксиса
Провайдеры	LM Studio, Ollama, Anthropic, OpenAI, Gemini, DeepSeek, Groq, Mistral, xAI, Together AI, Perplexity, Cohere, OpenRouter + любой OpenAI-совместимый эндпоинт; настройки по провайдерам сохраняются в `~/.agent.toml`
Инструменты	15 встроенных — read, edit, write, batch-edit, undo, shell, search, glob, code-map, find-def, find-refs, web-fetch, web-search, spawn-agent
Языки	AST-индекс: Rust, Python, TypeScript, JavaScript, Go, Java
Качество кода	`/index quality` — god-объекты, связность, кандидаты на мёртвый код, оценка качества (0–100); подсчёт ссылок за один проход O(размер-исходника)
Логирование использования индекса	Каждый вызов инструмента, отвеченный AST-индексом, логируется в `~/.zap/zap.log` и `audit.jsonl` — hit/miss на ход, аудируемо
Режимы прав	`ask` (сгруппированный запрос на деструктивную операцию), `auto` (одобрить всё), `deny` (полностью только чтение); grant "always" авто-одобряет класс инструментов на сессию
Skills	23 встроенных; always-on + запускаемые по ключевым словам; пользовательские skills в `~/.zap/skills/` или `.zap/skills/`; стандарт SKILL.md совместим с Claude Code и Cursor
Трейс skill	`/skill log` — увидеть, какие skills сработали (или почему нет) для каждого хода этой сессии
Захват skill	`/skill capture <name>` — извлечь правила сессии в переиспользуемый файл skill
Область skill	`/skill scope` — закрепить или ограничить, какие доменные skills активны для сессии, без редактирования файлов
Деплой	`/deploy` — собирает и устанавливает zap с живым потоковым выводом; без таймаута shell
Управление контекстом	Внедрение skill, оптимизация бытовых ходов (~20 токенов на приветствия), скользящее окно истории, обрезка результатов инструментов, суммаризация на месте `/compact`, кеширование промптов Anthropic
Инициализация проекта	`/init` — автоопределяет стек, индексирует кодовую базу и генерирует `ZAP.md` + `.zap/understanding.md`, заполненные специфичной для проекта архитектурой, командами сборки и ограничениями; ~30 секунд до полной осведомлённости о контексте
Интеллект проекта	Передача сессии `.zap/context.md` (последняя цель, затронутые файлы, что дальше); знания проекта, поддерживаемые LLM `.zap/understanding.md`; история сессий `.zap/session_log.md` — читается по требованию, не предзагружается
Сессии	Каждый разговор сохраняется; `/sessions` fuzzy-выбор для возобновления любого
Ветвление	`/branch` форкает разговор как git-ветку; `/switch` для перемещения между ними
Субагенты	`spawn_agent` запускает параллельных субагентов со своим циклом инструментов; несколько запусков в одном ходу выполняются параллельно
Автономный цикл	`/goal <condition>` запускает ходы автоматически, пока модель не сигнализирует о завершении или не достигнут лимит ходов
Расширенное мышление	`/think [on\\|off\\|N]` — расширенное мышление Anthropic с настраиваемым бюджетом токенов
MCP (ленивая загрузка)	Стандартный формат `.mcp.json` — работает в Claude Code, Cursor, Kiro; серверы подключаются по требованию, ноль затрат до первого использования
Воркфлоу	Декларативные многошаговые YAML-пайплайны в `.zap/workflows/` — версионируются вместе с вашим репозиторием
Хуки	`PreToolUse` / `PostToolUse` / `SessionStart` / `SessionEnd` / `UserPromptSubmit` — shell-команды, запускаемые на события агента
Изображения	`/attach <path>` или буфер обмена `/paste` — мультимодальность на поддерживаемых моделях
Лог аудита	Каждый вызов инструмента записывается в `~/.zap/audit.jsonl`
Сканер секретов	25+ паттернов — ключи Anthropic/OpenAI/Stripe, токены GitHub/GitLab, учётные данные AWS/GCP, приватные ключи, JWT, обобщённые поля password/api_key/secret — блокируются перед отправкой в любую облачную LLM
Отображение стоимости	Разбивка токенов по ходу — skills, сообщение, контекст, оценочная $

Токен-эффективность — умное определение контекста

Чистые приветствия и социальные сообщения используют минимальный промпт на 31 токен без инструментов, даже в середине разговора. Всё остальное получает полное внедрение контекста:

Сообщение	После вопроса модели?	Результат
"hi", "hello", "hey"	да	~31 токен (бытовое)
"thanks", "thank you", "ty"	да	~31 токен (бытовое)
"good morning", "how are you"	да	~31 токен (бытовое)
"yes"	да	полный контекст
"go ahead"	да	полный контекст
"ok", "cool", "sounds good"	да	полный контекст
любой технический вопрос	—	полный контекст

После того как модель задаёт уточняющий вопрос, короткие ответы вроде "yes", "ok", "go ahead" трактуются как ответы и получают полный контекст. Чисто социальные сообщения всегда остаются бытовыми.

Установка

macOS / Linux — однострочник

curl -fsSL https://raw.githubusercontent.com/zap-coding-agent/zap-coding-agent/main/install.sh | bash

Скрипт определяет вашу ОС и архитектуру, скачивает последний релиз, устанавливает в ~/.local/bin и правит конфиг вашего shell при необходимости. На macOS также автоматически запускает codesign --sign - (требуется на macOS 26 Tahoe).

Платформа	Бинарник
macOS Apple Silicon (ARM64)	`zap-macos-arm64.tar.gz`
macOS Intel (x86_64)	`zap-macos-x86_64.tar.gz`
Linux x86_64	`zap-linux-x86_64.tar.gz`
Linux ARM64 (aarch64)	`zap-linux-arm64.tar.gz`

Windows x86_64

Скачайте zap-windows-x86_64.zip со страницы последнего релиза, распакуйте и переместите zap.exe куда-нибудь в PATH:

Expand-Archive zap-windows-x86_64.zip .
Move-Item pkg\zap.exe "$env:USERPROFILE\.local\bin\zap.exe"

Сборка из исходников

Требуется Rust 1.75+.

git clone https://github.com/zap-coding-agent/zap-coding-agent
cd zap-coding-agent
cargo build --release
cp target/release/zap ~/.local/bin/zap

Быстрый старт

zap                                        # интерактивный TUI
zap --goal "add tests for src/lib.rs"      # одноразовый запуск
zap --goal "..." --output-format json      # JSON-вывод (для пайпов)
zap --auto --goal "..."                    # пропустить все запросы прав (CI)
zap --sdk                                  # удалённое управление через JSON-lines (stdin/stdout)

Первый запуск запросит API-ключ и модель. Используйте /provider, чтобы переключить позже.

Поддерживаемые провайдеры

Провайдер	Примеры моделей	Аутентификация
Anthropic	claude-sonnet-4-6, claude-opus-4-8	API-ключ
OpenAI	gpt-4o, gpt-4-turbo	API-ключ
Google Gemini	gemini-2.0-flash, gemini-2.5-pro	API-ключ или gcloud ADC (без ключа)
LM Studio	gemma-4-e4b-it, qwen3-coder-30b	Нет (локально)
Ollama	llama3, deepseek-coder	Нет (локально)
Groq	llama-3.3-70b-versatile	API-ключ
OpenRouter	(разные)	API-ключ
DeepSeek	deepseek-chat	API-ключ
xAI	grok-beta	API-ключ
Любой OpenAI-совместимый	—	API-ключ или без него

Конфигурация

Все настройки живут в ~/.agent.toml. Переменные окружения всегда имеют приоритет.

Используйте /provider внутри zap для интерактивного переключения — настройки сохраняются автоматически по провайдеру, так что переключение обратно восстанавливает ваш предыдущий ключ и модель.

# ~/.agent.toml — managed by zap /provider

provider        = "anthropic"   # active provider slug
permission_mode = "ask"         # ask | auto | deny

# Optional: import skills from other tools or shared libraries.
# Loaded after ~/.zap/skills/ but before .zap/skills/ — higher entry wins on name collision.
skill_paths = [
    ".kiro/skills",       # Amazon Kiro skills
    ".claude/skills",     # Claude Code skills
]

# Optional: always-on context from steering docs, project wikis, etc.
# All .md files in these dirs are appended to the system prompt every turn.
context_paths = [
    ".kiro/steering",
]

[providers.anthropic]
kind     = "anthropic"
model    = "claude-sonnet-4-6"
api_key  = "sk-ant-..."

[providers.lm_studio]
kind     = "openai"
model    = "gemma-4-e4b-it"
base_url = "http://localhost:1234/v1/chat/completions"

[providers.groq]
kind     = "openai"
model    = "llama-3.3-70b-versatile"
base_url = "https://api.groq.com/openai/v1/chat/completions"
api_key  = "gsk_..."

Каждый блок [providers.<slug>] хранит настройки независимо — переключение провайдеров никогда не перезаписывает ключ другого провайдера.

Роутинг моделей по задачам

Можно держать одну модель по умолчанию для обычной работы, а затем направлять конкретные типы задач на другую модель для одного хода. Это полезно, когда вы хотите, например:

Codex для правок кода
Claude Opus для код-ревью
Claude Sonnet для объяснений
более дешёвую/локальную модель для поисковых запросов

# ~/.agent.toml
model = "claude-sonnet-4-6"   # default model

[model_routes]
coding = "codex/gpt-5.5"
review = "claude-opus-4-8"
explain = "claude-sonnet-4-6"
search = "gemma-4-e4b-it"

Как это работает:

zap классифицирует промпт по типу задачи (coding, review, explain, search)
если найден подходящий маршрут, используется эта модель только для этого хода
после завершения хода zap восстанавливает вашу модель сессии по умолчанию
в режиме TUI zap показывает запрос подтверждения перед переключением

Пример:

"Отрефактори эту Rust-функцию и обнови тесты" → маршрутизируется на codex/gpt-5.5
"Проверь этот diff на баги и упущенные edge-кейсы" → маршрутизируется на claude-opus-4-8

Переопределение переменными окружения

AGENT_PROVIDER=anthropic \
AGENT_API_KEY=sk-ant-... \
AGENT_MODEL=claude-sonnet-4-6 \
zap

ANTHROPIC_API_KEY и OPENAI_API_KEY также читаются автоматически.

Google Gemini — без ключа через gcloud ADC

zap поддерживает аутентификацию без ключа для Google Gemini, используя gcloud Application Default Credentials. API-ключ не нужен — zap автоматически получает короткоживущие OAuth2-токены от gcloud.

gcloud auth login
gcloud auth application-default login
zap
# /provider  →  выберите "Google Gemini"
# Автоопределённые учётные данные показывают значок "✓ ready" — без запроса API-ключа.

Или настройте вручную в ~/.agent.toml:

provider = "gemini"

[providers.gemini]
kind = "openai"
model = "gemini-2.0-flash"
base_url = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions"
credential_method = "gcloud_adc"

Задайте GOOGLE_API_KEY в окружении, чтобы вместо этого использовать API-ключ.

Slash-команды

Команда	Описание
`/help`	Показать все команды
`/config`	Показать активного провайдера, модель, URL, глубину субагентов
`/cost`	Использование токенов и оценочная стоимость этой сессии
`/history`	Показать число сообщений
`/clear`	Очистить историю разговора
`/compact`	Модель суммаризирует историю на месте, чтобы освободить контекст
`/sessions [N]`	Просмотреть и возобновить старые сессии (fuzzy-выбор)
`/model <id>`	Переключить модель в середине сессии
`/models`	Список моделей на вашем сервере LM Studio / Ollama
`/provider`	Интерактивно переключить провайдера
`/permissions ask\\|auto\\|deny`	Изменить режим прав для этой сессии
`/index [path\\|stats]`	Переиндексировать AST-символы кода
`/index quality`	Отчёт о качестве кода: god-объекты, связность, мёртвый код, оценка качества
`/deploy [--check]`	Собрать и установить zap с живым потоковым выводом, без таймаута
`/undo [file]`	Отменить последнюю правку файла
`/init`	Проанализировать проект и создать `ZAP.md` + `.zap/understanding.md` (автозаполняются агентом)
`/run <workflow>`	Запустить пайплайн `.zap/workflows/<name>.yaml`
`/workflow new <name>`	Заскаффолдить новый файл workflow
`/tasks`	Просмотреть и выполнить структурированные task-сессии из `.zap/tasks/`
`/attach <path>`	Прикрепить изображение к следующему сообщению
`/paste`	Вставить изображение из буфера обмена
`/memory list\\|get\\|set\\|del`	Управление постоянной памятью ключ-значение
`/skill list\\|show\\|create\\|log`	Управление skills; `log` показывает, какие skills сработали за ход
`/skill scope`	Показать или изменить, какие доменные skills активны для этой сессии
`/hooks`	Список всех настроенных хуков и их событий-триггеров
`/branch <name>`	Форкнуть текущий разговор
`/branches`	Список всех веток разговора
`/switch <name>`	Переключиться на другую ветку
`/audit [N]`	Показать последние N строк лога аудита
`/exit`	Выйти

Инструменты

Инструмент	Что делает
`read_file`	Чтение с опциональным offset/limit, вывод с префиксом номеров строк
`edit_file`	Хирургический find-and-replace (отклоняет неоднозначные совпадения)
`batch_edit`	Несколько правок одного файла за один валидированный вызов
`write_file`	Запись или перезапись файла
`undo_edit`	Восстановить файл к снапшоту до правки
`shell`	Выполнить shell-команду (требует одобрения в режиме `ask`)
`git_status`	Git status + недавний лог
`search_code`	Ripgrep (откат на grep) с фильтром по типу файла и строками контекста
`list_directory`	`ls -la`
`glob_read`	Список/превью файлов, совпадающих с glob-паттерном
`code_map`	Структурный обзор на базе AST — функции, структуры, классы, номера строк
`find_definition`	Переход к месту определения символа (AST-индекс → откат на ripgrep)
`find_references`	Все места вызова символа по кодовой базе
`who_calls`	Все вызывающие функцию, с опциональным фильтром по квалификатору
`file_imports`	Все импорты в файле
`where_imported`	Каждый файл, импортирующий данное имя
`find_subtypes`	Все типы, расширяющие или реализующие данный тип
`find_supertypes`	Все типы, которые данный тип расширяет или реализует
`pack_context`	Автоматически выбирает наиболее релевантные файлы для задачи в рамках бюджета токенов
`ripple_analysis`	BFS-обход графа вызовов — кто транзитивно вызывает символ (радиус поражения)
`get_diagnostics`	Живые ошибки/предупреждения компилятора через language server (rust-analyzer, pylsp, gopls…)
`lsp_definition`	Go-to-definition с разрешением типов — разрешает кросс-крейтовые, дженерик и трейт-символы
`lsp_type_at`	Выведенный тип или сигнатура любого выражения в заданной позиции
`web_fetch`	Получить URL, убрать HTML, вернуть читаемый текст
`web_search`	Поиск DuckDuckGo — API-ключ не требуется
`spawn_agent`	Запустить параллельного субагента со своим циклом инструментов

CI / Headless-режим

zap работает полностью неинтерактивно. Добавьте --auto (или AGENT_PERMISSION_MODE=auto), чтобы пропустить все запросы прав:

# одноразовый запуск — чисто для скриптов
zap --auto --goal "review staged changes and write a summary to REVIEW.md"

# альтернатива через переменную окружения
AGENT_PERMISSION_MODE=auto zap --goal "run cargo test and fix any failures"

Пример GitLab CI

# .gitlab-ci.yml
ai-review:
  image: ubuntu:24.04
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY   # задать в CI/CD → Variables
  before_script:
    - curl -L https://github.com/zap-coding-agent/zap-coding-agent/releases/download/latest/zap-linux-x86_64
        -o /usr/local/bin/zap && chmod +x /usr/local/bin/zap
  script:
    - zap --auto --goal "review the diff since origin/main, identify bugs or missing tests,
        and write a report to ai-review.md"
  artifacts:
    paths: [ai-review.md]
    expire_in: 1 week

Пример GitHub Actions

- name: AI code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    zap --auto --goal "read the changed files, add docstrings where missing, and commit"

Режим SDK / удалённого управления

--sdk превращает zap в JSON-lines сервер — stdin несёт промпты, stdout несёт ответы. Состояние сессии сохраняется между ходами, так что контекст накапливается.

zap --sdk          # stdin → stdout, --auto подразумевается, без баннера

Протокол

stdin (один JSON-объект на строку):

{"type":"user","text":"refactor the auth module to use JWT"}
{"type":"user","text":"now write tests for the new auth module"}
{"type":"quit"}

stdout (один JSON-объект на строку):

{"type":"assistant","text":"I've refactored the auth module...","turn":1,"ctx_pct":12,"usage":{"input_tokens":1842,"output_tokens":487}}
{"type":"assistant","text":"I've written tests for...","turn":2,"ctx_pct":24,"usage":{"input_tokens":3210,"output_tokens":612}}

Весь терминальный шум (блоки вызовов инструментов, спиннеры) идёт в stderr — stdout остаётся чистым JSON для машинного потребления.

Пример Python-скрипта

import subprocess, json, os

proc = subprocess.Popen(
    ["zap", "--sdk"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    env={**os.environ, "ANTHROPIC_API_KEY": "sk-ant-..."},
)

def ask(prompt: str) -> dict:
    proc.stdin.write(json.dumps({"type": "user", "text": prompt}).encode() + b"\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

reply = ask("add input validation to src/api.rs")
print(reply["text"])

proc.stdin.write(b'{"type":"quit"}\n')
proc.stdin.flush()
proc.wait()

Поддержка CLAUDE.md

Поместите CLAUDE.md в корень вашего проекта — или в любую родительскую директорию вплоть до $HOME — для постоянного контекста проекта. Также загружается глобальный ~/.claude/CLAUDE.md. Все совпадающие файлы складываются стеком; самая внутренняя директория побеждает.

Запустите /init, чтобы создать шаблон, который агент заполняет автоматически, читая ваш репозиторий.

Skills

Skills — markdown-файлы (.md) с YAML frontmatter. Следуют стандарту SKILL.md — совместимому с Claude Code, Cursor и другими агентами.

Triggered skill — внедряется только при совпадении ключевых слов:

---
name: conventional-commits
description: Enforce Conventional Commits format on all git operations.
trigger: ["commit", "git log", "stage", "push"]
tokens: ~400
---
Always use Conventional Commits format: <type>(<scope>): <description>
Types: feat, fix, docs, style, refactor, perf, test, chore

Always-on skill — без поля trigger:, внедряется каждую сессию:

---
name: team-principles
description: Engineering principles applied to every task.
---
Ship small. Write tests first. No magic numbers. Document the why, not the what.

Куда помещать skills:

~/.zap/skills/          личные, применяются ко всем проектам  ← записываются сюда при первом запуске
.zap/skills/            локальные для проекта, коммитить в git для командного шаринга

При первом запуске zap записывает все встроенные skills в ~/.zap/skills/. Откройте любой файл там, отредактируйте, и ваша версия вступит в силу при следующем запуске. Файлы никогда не перезаписываются — только новые добавляются при обновлении zap.

/skill list                      список всех skills (сгруппированы: always-on / triggered)
/skill show <name>               превью содержимого, описание, лицензия
/skill log                       какие skills сработали (или почему нет) за ход этой сессии
/skill scope                     какие доменные skills активны в этой сессии
/skill export <name>             переэкспортировать встроенный в ~/.zap/skills/
/skill export --all              переэкспортировать все встроенные skills
/skill create <name>             заскаффолдить новый skill в .zap/skills/
/skill create <name> --global    заскаффолдить в ~/.zap/skills/
/skill capture <name>            извлечь правила из этой сессии в файл skill

Источники skills из нескольких инструментов — Kiro, Claude Code и кастомные директории

Если в вашем проекте уже есть skills, написанные для Amazon Kiro (.kiro/skills/) или Claude Code (.claude/skills/), можно подтянуть их в zap без копирования файлов. Добавьте skill_paths в ~/.agent.toml:

# ~/.agent.toml
skill_paths = [
    ".kiro/skills",          # Amazon Kiro skills (по проекту)
    ".claude/skills",        # Claude Code skills (по проекту)
    "~/shared-skills",       # своя кросс-проектная библиотека
]

Полный приоритет (от низшего к высшему, при коллизии имени побеждает более поздний):

Источник	Расположение	Значок в `/skill list`
Встроенный	скомпилирован в бинарник	`◆`
Глобальный	`~/.zap/skills/`	`●`
Внешний	записи `skill_paths`, слева → направо	`◉`
Проектный	`.zap/skills/`	`▶`

Always-on контекст из других инструментов — Kiro steering, контекст Claude

Steering-документы (.kiro/steering/) и файлы контекста проекта Claude — не skills, у них нет триггера и frontmatter. Используйте context_paths, чтобы загрузить их как always-on системный контекст:

# ~/.agent.toml
context_paths = [
    ".kiro/steering",     # steering-документы Kiro — загружаются каждую сессию
    ".claude/context",    # контекст-документы Claude
]

Все файлы .md, найденные в директориях context_paths, добавляются к системному промпту на каждом ходу. Frontmatter (блоки ---) удаляется автоматически.

Совет: skill_paths и context_paths дополняют друг друга. Используйте skill_paths для указаний, запускаемых по ключевым словам, и context_paths для always-on контекста, применяемого независимо от того, о чём вы спрашиваете.

Workflows

Декларативные многошаговые пайплайны в .zap/workflows/<name>.yaml. Запуск через /run <name>.

name: ship-feature
description: Review → test → commit → changelog
steps:
  - prompt: "Review all staged changes and flag anything blocking"
    requires_approval: true
  - skill: test-runner
    prompt: "Run the test suite, fix any failures"
  - prompt: "Commit with a conventional commit message"
  - prompt: "Append a one-line entry to CHANGELOG.md"

Индекс кода

См. AST-индекс кода — понимает ваш код, не только текст выше для полного объяснения.

Команда	Что показывает
`/index`	Переиндексировать вручную
`/index stats`	Число файлов, число символов по видам, топ файлов по плотности
`/index quality`	God-объекты, крупные файлы, высокая связность, кандидаты на мёртвый код, оценка качества

Управление сессиями

Каждый разговор сохраняется локально. Используйте /sessions, чтобы просмотреть и возобновить любую предыдущую сессию через интерактивный fuzzy-выбор.

Субагенты

Когда agent_depth > 0 (по умолчанию: 3), модель может вызвать spawn_agent, чтобы делегировать независимые задачи. Несколько запусков в рамках одного хода LLM выполняются параллельно, каждый со своей историей сообщений и доступом к инструментам.

Пути разработчика

Реальные сценарии — что на самом деле происходит на каждом этапе.

Путь 1 — Первое открытие проекта

Сценарий: Вы только что клонировали Java-микросервис, который никогда раньше не видели. Двенадцать сервисов, Spring Boot, Maven, без документации.

cd order-service
zap

zap запускается менее чем за секунду. Запустите /init, чтобы загрузить полные знания о проекте:

◌ Detected project type: java

  Indexing src/ ...
  ✓ tree-sitter · java · 847 symbols across 63 files

✓ .zap/project.json written.
✓ Created ZAP.md for java project.
⚡ Asking the agent to analyse the repo and fill in ZAP.md…

Агент читает исходные файлы и заполняет ZAP.md:

## Overview
Order service — handles order lifecycle (create, fulfil, cancel).

## Build & Test
mvn clean install
mvn test
mvn spring-boot:run

## Architecture
- OrderController  → REST handlers (controller/)
- OrderService     → business logic, calls OrderRepository
- OrderRepository  → JPA, Postgres via spring-data

## Important Files
- OrderService.java     — core domain logic, start here
- application.yml       — all config including Kafka brokers

## Do Not Touch
- LegacyOrderMapper.java — deprecated, backwards compat only

Общее время: ~30 секунд. От нуля до полностью осведомлённого о контексте агента.

Путь 2 — Возвращение к проекту

Сценарий: Вы работали над order service на прошлой неделе. Открываете zap сегодня, чтобы продолжить.

cd order-service
zap

Ещё до вашего первого сообщения zap уже загрузил ZAP.md, .zap/understanding.md, .zap/context.md и .zap/session_log.md. Агент уже знает, над чем вы работали, какие файлы изменились и что осталось незавершённым:

you:  "what were we working on last time?"

zap:  Last session you were adding pagination to GET /orders.
      You updated OrderController.java and OrderService.java.
      The service method was done but the controller test was still failing
      — that was left as the next step.

Без повторного чтения файлов. Без повторного объяснения стека. Передача сессии автоматическая.

Путь 3 — Понимание незнакомого кода

Сценарий: Коллега написал FulfilmentService шесть месяцев назад. Вам нужно понять его перед тем, как трогать.

"explain how FulfilmentService works — what it does, what it calls, what could go wrong"

→ java skill fires (class keyword matched)
→ find_definition looks up FulfilmentService in the index — found at
  src/main/java/.../service/FulfilmentService.java:34
→ code_map outlines all methods: fulfil(), rollback(), notifyWarehouse()
→ reads only the relevant sections, not the whole file
→ traces the call chain: fulfil() → OrderRepository.save() → KafkaProducer.publish()
→ flags: rollback() has no test coverage, notifyWarehouse() blocks on HTTP with no timeout

Вы получаете структурное объяснение за секунды — включая неочевидные риски — не читая 400 строк Java самостоятельно.

Путь 4 — Добавление фичи в существующую кодовую базу

Сценарий: Нужно добавить эндпоинт GET /orders/{id}/history в существующий order service.

Без zap (что делает большинство агентов): агент создаёт новые файлы контроллера, сервиса и репозитория — дублируя уже существующую структуру, игнорируя уже используемые паттерны.

С zap:

"add a GET /orders/{id}/history endpoint that returns the state change log"

→ java skill fires
→ index query finds: OrderHistory entity — already exists!
→ index query finds: OrderRepository extends JpaRepository<Order, Long> — this is the pattern
→ index query finds: all existing controllers extend BaseController, use @RestController

zap:  OrderHistory entity already exists at OrderHistory.java:12.
      I'll add a findByOrderId() method to OrderRepository, a getHistory() method
      to OrderService, and a new endpoint to OrderController — no new files needed.
      Shall I proceed?

Один файл затронут в OrderController, один метод добавлен в OrderRepository, один — в OrderService. Без дублирующих классов. Следует существующему паттерну JpaRepository.

Это ключевое отличие. Агент знал, что существует, прежде чем решить, что создавать.

Путь 5 — Исправление бага

Сценарий: Заказы иногда помечаются как выполненные, даже когда уведомление склада не удалось.

"orders are being fulfilled even when notifyWarehouse() throws — trace why"

→ debugging skill fires
→ find_definition locates fulfil() at FulfilmentService.java:67
→ reads the method — sees notifyWarehouse() is called AFTER OrderRepository.save()
→ the save() commits to DB before the warehouse call — if warehouse throws, order
  is already marked fulfilled in the DB with no rollback
→ finds: @Transactional annotation is present but notifyWarehouse() is an HTTP call
  outside the transaction boundary — @Transactional won't roll it back

zap:  Root cause: the DB commit happens before the warehouse HTTP call.
      @Transactional covers the DB write but not the external HTTP call.
      Fix: move notifyWarehouse() before the save(), or wrap it in a try/catch
      that explicitly rolls back via OrderRepository.updateStatus().
      Which approach do you prefer?

Вы выбираете подход, zap делает хирургическую правку, показывает diff, запрашивает одобрение перед записью.

Путь 6 — Проверка и улучшение качества кода

/index quality

◎ code quality — 63 files · 847 symbols                          score: 61/100

⚠ god objects  (impl with >15 methods — split recommended)
  OrderService          34 methods  src/.../service/OrderService.java
  FulfilmentService     18 methods  src/.../service/FulfilmentService.java

✦ high coupling  (referenced in many places — risky to change)
  OrderService.fulfil()     29×
  OrderRepository.save()    24×

◌ dead code candidates  (public method, 0 external references)
  LegacyOrderMapper.toDto()    LegacyOrderMapper.java:44
  OrderUtils.formatId()        OrderUtils.java:18

Теперь у вас есть конкретные данные для спринт-обсуждения. OrderService — самый рискованный файл для изменения — fulfil() вызывается в 29 местах.

Путь 7 — Завершение и передача

В конце любой сессии zap автоматически записывает .zap/context.md:

## Last updated
2026-05-25 — Session #42

## What was being worked on
Added cursor-based pagination to GET /orders endpoint.
Fixed race condition in FulfilmentService.

## Files touched
- OrderController.java
- OrderService.java
- FulfilmentService.java

## What's next
- Pagination test for edge case: empty cursor on last page
- Consider splitting OrderService (34 methods — see /index quality output)

Завтрашняя сессия подхватывает это автоматически. Без повторных объяснений. Без потерянного контекста.

Roadmap — публичный roadmap

У zap должен быть roadmap, который люди могут увидеть, не копаясь в чатах или коммитах. Публичная модель такая:

Roadmap: этот раздел в README.md для общего направления
Трекер выполнения: GitHub Issues (один issue на пункт roadmap, связанный отсюда)
Changelog отгруженного: FEATURES.md для выпущенных фич/фиксов и где они находятся
Версионированные релизы: GitHub Releases для скачиваемых вех

Это сохраняет единый источник истины для отгруженной работы (FEATURES.md), в то время как GitHub Issues остаются местом, где люди могут обсуждать, подписываться на и отслеживать пункты roadmap до их выпуска.

Тема	Статус	Как должно отслеживаться
Мульти-задачная оркестрация с отдельными субагентами	планируется	Issue #4
Живой мониторинг субагентов в TUI / веб	планируется	Issue #5
`/skill install github:user/repo/path`	планируется	GitHub issue: установка community-skill
Расширение/композиция skill	планируется	GitHub issue: составные слои skill
Семантическая маршрутизация skill	планируется	GitHub issue: маршрутизация skill на основе намерения
Публичная директория skill	планируется	GitHub issue: каталог/обнаружение skills
Расширение автоопределения стека	планируется	GitHub issue: определение Ruby/Swift/Kotlin/C++
Кросс-агентная совместимость	в процессе	Отслеживать через issues с тегом `interop`

Как должны работать пункты roadmap

Для каждого пункта roadmap:

Откройте GitHub issue с пользовательской проблемой, а не просто названием фичи
Добавьте теги вроде roadmap, enhancement и тег области (tui, agent, docs и т.д.)
Свяжите issue из этого раздела, когда он появится
Когда фича выпущена, перенесите детали реализации в FEATURES.md
Укажите выпущенную версию в FEATURES.md и GitHub Releases

Changelog

Проект уже регулярно обновляет FEATURES.md, и это должно оставаться каноничным публичным changelog'ом на данный момент. Он полезнее, чем обычный написанный вручную changelog, потому что фиксирует:

что было отгружено
затронутые файлы
номера версий для многих записей
заметки по реализации, полезные контрибьюторам и продвинутым пользователям

Публичные ссылки:

Долгосрочная ставка zap по-прежнему на skills как платформу, а не просто на то, чтобы быть лучшим терминальным агентом. Цель: превратить командные знания в код, сделать их шарибельными, составными и кросс-совместимыми с другими агентами.

Контрибьютинг

Контрибьюции приветствуются — исправления багов, новые провайдеры, поддержка языков, улучшения skills или что угодно, делающее zap полезнее.

Сообщение о багах Откройте issue на github.com/zap-coding-agent/zap-coding-agent/issues. Укажите вашу ОС, модель/провайдера, выполненную команду и что ожидали vs что произошло. Приложите релевантные строки из ~/.zap/audit.jsonl, если проблема связана с инструментами.

Запросы фич Откройте issue с тегом enhancement. Опишите сценарий использования, не только фичу — это помогает приоритизировать.

Pull request'ы 1. Сделайте форк репозитория и создайте ветку от main 2. Держите изменения сфокусированными — один PR на фикс или фичу 3. Запустите cargo check и cargo clippy перед отправкой — ожидается ноль предупреждений 4. Обновите README, если добавляете видимую фичу

Добавление встроенного skill Встроенные skills живут в src/default_skills/. Каждый — markdown-файл с YAML frontmatter (имя, ключевые слова триггера, оценка токенов). Если у вас есть хорошие конвенции для языка или фреймворка, ещё не покрытого, PR со skill — один из самых простых вкладов.

Добавление провайдера Все провайдеры говорят на формате протокола OpenAI — добавление обычно сводится к новой записи в селекторе с base_url и моделью по умолчанию.

Лицензия

MIT

ZAP