Документ фиксирует цели, архитектуру и принципы репозитория Claw Code — публичной Rust-реализации CLI-агента claw и сопутствующих инструментов. Источник правды по кодовой базе: workspace в каталоге rust/; операционные сценарии — USAGE.md, how_to_run.md (claw-analog), бэклог идеи — futute.md.

Отдельная продуктовая линия «из CLI → в личного помощника» (каналы/память/инструменты/проактивность/сессии) описана в docs/personal-assistant-roadmap.md.

Claw Code — это:

1. Основной CLI claw (rusty-claude-cli): полнофункциональный агент с REPL, OAuth, расширенным набором инструментов (включая bash, MCP, плагины и др.), стримингом и интеграцией с провайдерами Anthropic, OpenAI-совместимыми API и xAI.
2. claw-analog — облегчённая оболочка на том же слое API (api crate): узкий, предсказуемый набор инструментов только для работы с файловой системой воркспейса, явные режимы прав, пригодность для CI, скриптов и внешних агентов (NDJSON).
3. claw-rag-service — отдельный процесс: индексация репозитория (чанки + эмбеддинги в SQLite), HTTP API для семантического поиска и минимальный веб-UI для ручной проверки индекса.

Общая идея: дать безопасный, аудируемый и воспроизводимый способ вызова LLM над кодом и документацией, с путём эволюции от минимального harness до полного claw.

                    ┌─────────────────────────────────────┐
                    │  Провайдеры (Anthropic / OpenAI / …) │
                    └─────────────────┬───────────────────┘
                                      │
       ┌──────────────────────────────┼──────────────────────────────┐
       │                              │                              │
       ▼                              ▼                              ▼
┌──────────────┐              ┌──────────────┐              ┌──────────────────┐
│  rusty-      │              │  claw-analog │              │ claw-rag-service │
│  claude-cli  │              │  (lean loop) │              │ HTTP + SQLite    │
│  («claw»)    │              │              │              │ ingest / query   │
└──────┬───────┘              └──────┬───────┘              └────────┬─────────┘
       │                              │                               │
       │          crates/api          │         retrieve_context      │
       │    runtime, tools, …         │         (POST /v1/query)      │
       └──────────────┬───────────────┴───────────────────────────────┘
                      │
                      ▼
               Файловая система / workspace (-w)

Принцип разделения: тяжёлая индексация и хранение эмбеддингов не зашиваются в claw-analog, а живут в claw-rag-service. Агент только вызывает retrieval по HTTP — проще масштабировать, менять векторное хранилище и секреты эмбеддингов.

1. Безопасность по умолчанию — относительные пути, запрет .., проверка выхода за canonical workspace; режимы PermissionMode согласованы с полным CLI; в неинтерактивном режиме опасные режимы блокируются без явного флага.
2. Явные лимиты — размер чтения, число ходов, glob/grep caps, таймауты RAG; сбои предсказуемы, а не «OOM или вечный цикл».
3. Наблюдаемость для агентов — NDJSON с schema и format_version на run_start, структурированные tool_result.
4. Модульность — общий api для провайдеров; claw-analog не дублирует стек ключей RAG, только HTTP-клиент к сервису.
5. Паритет и тесты — mock Anthropic, сценарии harness, отдельные job’ы CI для критичных crate’ов.
6. Документация рядом с кодом — how_to_run.md, docs/rag-web-ui.md, docs/container.md и т.д.

• rusty-claude-cli — основной бинарь claw: пользовательский продукт полной мощности.
• api — клиенты провайдеров, стриминг, типы запросов/ответов.
• runtime — сессии, конфиг, PermissionPolicy / PermissionEnforcer, промпты, MCP и др.
• tools — встроенные инструменты полного CLI.
• claw-analog — минимальный цикл: инструменты чтения/поиска/записи (по режиму), стриминг и JSON, TOML-конфиг, сессии, doctor, config validate, retrieve_context при наличии RAG_BASE_URL / rag_base_url.
• claw-rag-service — ingest, serve, маршруты /, /health, /v1/stats, /v1/query; SQLite + OpenAI-совместимые эмбеддинги (или mock для тестов).
• mock-anthropic-service, compat-harness и др. — воспроизводимость и миграция.

Подробная раскладка: rust/README.md.

Задача: дать «агента с инструментами» без разрастания поверхности атаки (нет произвольного shell в базовом сценарии).

Инструменты (концептуально): чтение и обход дерева (read_file, list_dir, glob_workspace), литеральный поиск (grep_workspace / grep_search), опционально write_file, опционально retrieve_context к RAG-сервису.

Не входит в минимальный дизайн: MCP, плагины, bash — это зона полного claw.

Сейчас (MVP): полный переиндекс при ingest, векторы в SQLite, поиск — линейный косинус по всем чанкам; подходит для умеренных объёмов кода.

Направления роста (концепция): инкрементальная индексация, ANN (sqlite-vec, Qdrant/Chroma в Docker), rate limits на эмбеддинги. Веб-UI на GET / — вспомогательный; продвинутый UI и авторизация — по мере необходимости.

Детали: docs/rag-web-ui.md.

• src/, tests/ (Python и прочее) — вспомогательные/экспериментальные артефакты; канонический runtime — rust/.
• Документы PHILOSOPHY.md, ROADMAP.md, PARITY.md дополняют концепцию процессом и намерениями сообщества/мейнтейнеров.

В docs/ могут находиться переносимые заметки для других продуктов (например локальный vision для NestJS-приложений) — они не определяют обязательное поведение claw, но отражают смежный интерес contributors.

Claw Code — это экосистема Rust вокруг агента claw: полный CLI для разработчиков, claw-analog как управляемый минимальный агент для автоматизации и отдельный RAG-сервис для семантического поиска по коду. Проект опирается на явные права, лимиты, тестируемость и чёткие HTTP-границы между агентом и тяжёлой индексацией.

Обновляйте этот файл при смене ключевых продуктовых решений; детальный чеклист фич и backlog — в futute.md.