Русский | English

FoxxyCode Agent

Полноценный универсальный агент в одном статическом исполняемом файле на Go.
ReAct, инструменты для файловой системы и командной строки, MCP, навыки, опциональный OpenAI-совместимый API со встроенным интерфейсом, планировщик и долговременная память.
Удобный для IDE форк, который легко адаптировать к выбранному редактору.

Foxxy Agent основан на coddy-agent проекта Coddy (MIT). Этот форк сохраняет архитектуру исходного проекта и совместимость с его обновлениями, но меняет оформление дистрибутива (репозиторий, имя исполняемого файла и релизы) и упрощает адаптацию к IDE.

Что FoxxyCode добавляет к coddy-agent (см. полный список):

• Нативное настольное окно (WebView2) с системными уведомлениями, звуковым сигналом и пошаговым знакомством при первом запуске
• Глубокая интеграция с IDE — контекст открытых файлов (<foxxycode_ide_context>), отслеживание терминала (@terminal), упоминание файлов перетаскиванием, выбор папки проекта, метаданные проекта из .vscode/.idea и нативные встроенные diff в IntelliJ
• Интерактивный браузерный инструмент — управляет настоящим Chrome через chromedp и возвращает модели снимки экрана; входит в полные сборки (тег browser), выключен по умолчанию — включается флагом browser.enabled; подробнее в разделе браузерного инструмента
• Автоматическое сжатие контекста — по умолчанию автоматически суммирует длинные диалоги
• Русская локализация настроек и полный ребрендинг дистрибутива в foxxyCode

FoxxyCode — совместимая с distroless среда выполнения агента: её можно помещать в минимальные образы (scratch, distroless, рабочие каталоги только для чтения), не устанавливая полноценную системную оболочку. Инструменты grep и glob используют системный ripgrep, когда он доступен, и переключаются на встроенные реализации на Go, когда его нет. Уровень среды (ACP RPC, сессии, промпты, провайдеры) не меняется, если ограничить набор инструментов или управлять агентом из автоматизации вместо IDE. Архитектура также рассчитана на контейнерные кластеры — множество экземпляров FoxxyCode в Docker с заданными оркестратором ограничениями, корневой ФС только для чтения и подключённым рабочим каталогом. При этом сохраняется полный контроль над каждым контейнером, как в системах класса agent OS или swarm-агентов, а не в едином общем пуле чатов.

Содержание

• Возможности
• Быстрый старт
  • Установка
  • Другие способы установки
  • Теги сборки
  • Docker
  • Пути (FOXXYCODE_HOME, FOXXYCODE_CWD)
  • Настройка
• Обновление
• Режимы работы
• Интеграция с редакторами и IDE
• Правила
• Навыки
• Интеграция MCP-серверов
• Шлюз мессенджеров
• Справочник по конфигурации
• Архитектура
• Документация
• Примеры (ACP через stdio)
• Постоянные сессии
• Разработка
• Какая сборка кому подходит
• Лицензия

Возможности

• Среда выполнения — прежде всего — ACP-сервер, жизненный цикл сессий, промпты, LLM-бэкенды, объединение MCP и готовый для distroless исполняемый файл
• Цикл ReAct — LLM чередует рассуждение, действие (вызов инструментов) и наблюдение за результатами; профиль кодинг-агента доступен из коробки
• Пять режимов работы — agent (полный доступ к инструментам), plan (планирование без реализации), docs (защищённое редактирование Markdown-документации), ask (ответы и исследование без изменений) и debug (системная диагностика первопричины до исправления)
• Правила — автоматически находит .cursor/rules/, .foxxycode/rules/, .claude/rules/ и .codex/rules/ в рабочем каталоге сессии, а вложенные AGENTS.md (соглашение agents.md) читает по требованию — для тех каталогов, куда зашёл инструмент; подробнее в разделе Правила
• Навыки — slash-команды и пакеты SKILL.md из skills.dirs (по умолчанию: ~/.agents/skills, ~/.foxxycode/skills, ${CWD}/.foxxycode/skills; более поздний каталог имеет приоритет); ставятся из любого репозитория или маркетплейса (skills.sources, /plugin, Настройки → Навыки) с учётом версий; подробнее в разделе Навыки
• Фоновые задачи — run_command умеет работать отдельно от хода (background: true плюс собственная оценка модели expected_seconds); background_list / background_output / background_wait / background_stop забирают результат позже, панель Фоновые задачи в UI показывает, что ещё выполняется, а диалог разрешений умеет расширить грант до целой программы (curl, git status), чтобы серия похожих вызовов спрашивала один раз; подробнее в разделе Фоновые задачи
• Субагенты — модель делегирует ограниченную самодостаточную задачу дочернему агенту со своим контекстным окном и сессией (spawn_agent, в foreground или отсоединённо); определения — markdown-файлы с YAML-frontmatter в ~/.foxxycode/agents и .foxxycode/agents (файлы Claude Code из .claude/agents тоже загружаются), два встроенных (general, explore) вшиты в бинарь, проектные файлы требуют разового одобрения (foxxycode agents trust <name>), инструменты и режим разрешений можно только сужать, а каждый запуск — фоновая задача с read-only транскриптом ребёнка, доступным из панели Задачи — см. Субагенты
• Хуки — ваши собственные команды в точках жизненного цикла сессии: хук PreToolUse может запретить вызов инструмента при любом режиме разрешений, одобрить его в обход диалога, переписать аргументы или добавить контекст; PostToolUse / PostToolUseFailure видят результат; UserPromptSubmit, Stop, SessionStart, PreCompact / PostCompact, SubagentStart / SubagentStop и Notification покрывают остальной ход. Определения — JSON-файлы формата Claude Code (~/.foxxycode/hooks.json, .foxxycode/hooks.json и .claude/settings*.json в рабочей папке); файл, найденный внутри рабочей папки, ничего не запускает, пока не одобрен там (foxxycode hooks trust <файл>) — см. Хуки
• Экспорт сессии — встроенная команда /export [md|html|json|jsonl|pdf|docx] [путь] пишет беседу в файл рабочей папки, а кнопка скачивания в панели отдаёт тот же документ; --no-tools / --no-thinking его подрезают (панель по умолчанию выгружает только диалог, команда сохраняет вызовы инструментов) — см. Экспорт сессии
• Интеграция MCP-серверов — подключение любого MCP-сервера для доступа к дополнительным инструментам
• Несколько LLM-провайдеров — OpenAI, Anthropic, Ollama и любой OpenAI-совместимый API
• Мультимодальность и вложения — изображения и файлы можно прикреплять через поле ввода (📎), если в настройках модели указано multimodal: true; файлы сохраняются в ~/.foxxycode/sessions/<id>/assets/, передаются в контекст агента и отображаются в сообщении пользователя
• Экспорт диалога — любую сессию можно выгрузить в PDF, DOCX, HTML или JSON. Markdown в сообщениях отрисовывается по-настоящему: таблицы, подсветка синтаксиса, вложенные списки и чек-листы, цитаты, ссылки с рабочими аннотациями и картинки из assets/ сессии; удалённые http(s)-картинки при экспорте намеренно не загружаются. Панелям IDE, которые не умеют принимать загрузку, служит отдельный маршрут, записывающий документ на диск и подсвечивающий его в файловом менеджере; подробнее в HTTP API
• Уровень рассуждения — для моделей с рассуждением (gpt-5, серия o, gpt-oss, qwen3, модели Claude с thinking) выпадающий список в поле ввода задаёт уровень (minimal/low/medium/high), который преобразуется в OpenAI reasoning_effort или Anthropic extended-thinking budget_tokens; поддержка определяется автоматически по идентификатору модели и настраивается для каждой модели — см. Настройку
• Самонастройка агента — агент умеет менять собственную конфигурацию по вашей просьбе, но не втихую: config_get читает значение по точечному пути (секреты возвращаются как <redacted>), config_set накапливает команды в стиле uci из OpenWrt (set, add_list, del_list, delete) без записи в файл, config_changes показывает накопленное, config_commit применяет пакет одной транзакцией — с проверкой по схеме, снимком в config.yaml.prev, горячей перезагрузкой навыков, правил, инструментов и MCP-серверов и обязательным диалогом разрешения, а config_revert и config_rollback откатывают накопленное или уже применённое. Синтаксису учит встроенный навык /configure-foxxycode; подробнее в Справочнике по конфигурации
• Улучшение промпта — кнопка с волшебной палочкой в строке контекста поля ввода переписывает черновик через модель (POST /foxxycode/enhance-prompt); Ctrl+Z возвращает исходный текст, а неудача оставляет черновик нетронутым — см. Встроенный интерфейс
• Протокол ACP — FoxxyCode работает как ACP-сервер (foxxycode acp); его можно подключить к редактору или скрипту с ACP-клиентом (см. Интеграцию с редакторами и IDE)
• Удалённое выполнение по SSH — встроенный инструмент ssh_run_command выполняет команды на удалённых узлах через реализацию SSH на чистом Go, без внешнего исполняемого файла; аутентификация использует SSH-агент (SSH_AUTH_SOCK) или ключи из ~/.ssh — см. Настройку
• Поддержка Subversion наравне с git — когда в рабочей папке найдена рабочая копия SVN, рядом с чипом git появляется чип SVN (ветка trunk / branches/<имя> и ревизия): ветку можно переключить на месте (svn switch) или выгрузить в отдельную папку-ветку. Агент работает через отдельные инструменты svn_info, svn_status, svn_diff, svn_log, svn_list, svn_add, svn_revert, svn_resolve, svn_update, svn_commit, svn_switch, svn_merge, svn_checkout — изменяющие спрашивают разрешение. Определение git и svn независимо, поэтому папка-ветка SVN с git-репозиторием внутри работает с обеими системами. Отключается в настройках (vcs.svn.enabled); без установленного клиента svn всё просто скрыто — см. Настройку
• Шлюз мессенджеров — опциональный адаптер Telegram-бота (-tags gateway.telegram), отдельные сессии пользователей, режимы изоляции групп и ACL администраторов; архитектуру можно расширить для Discord, Slack и других сервисов — см. Шлюз мессенджеров

Интеграция с редакторами и IDE

FoxxyCode работает как ACP-сервер (foxxycode acp). Obsidian, VS Code, Zed, скрипты и встроенный интерфейс foxxycode http выступают клиентами и используют одни и те же сессии в FOXXYCODE_HOME, если настроены на общий домашний каталог.

Указывайте в клиентах абсолютный путь к исполняемому файлу, не полагаясь на PATH: некоторые среды запускают агента через cmd /c или sh -c без пользовательского PATH (в Windows: %LOCALAPPDATA%\Programs\foxxycode\foxxycode.exe; см. docs/install.md).

Описание протокола: docs/acp-protocol.md. Примеры среды: examples/acp/.

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

Установка

Сборка из исходников (рекомендуется; требования перечислены в разделе «Другие способы установки»):

git clone https://github.com/hijera/foxxy-agent
cd foxxy-agent
make build TAGS="http ui scheduler memory cli browser gateway swarm"
make install   # копирует build/foxxycode в ~/.local/bin или /usr/local/bin

В Windows (или без GNU Make) используйте интерактивный мастер: python scripts/build.py — русскоязычное консольное меню для сборки CLI, плагина IntelliJ, VS Code VSIX, выбора тегов и целевых платформ. Подробнее в docs/build.md.

Linux — каждый релиз публикует .deb и .rpm для x86_64 и arm64, так что FoxxyCode ставится и удаляется как остальная система, вместе со страницей man и дополнением командной строки:

curl -fsSLO https://github.com/hijera/foxxy-agent/releases/latest/download/foxxycode_0.2.63_linux_amd64.deb
sudo apt-get install ./foxxycode_0.2.63_linux_amd64.deb   # или: sudo dnf install ./...rpm

macOS — Homebrew-каск из того же релиза:

brew install --cask https://github.com/hijera/foxxy-agent/releases/latest/download/foxxycode.rb

Можно также скачать архив для своей платформы из GitHub Releases и добавить исполняемый файл foxxycode в PATH. Подробнее обо всех способах — docs/install.md.

Создайте начальную конфигурацию: mkdir -p ~/.foxxycode && cp config.example.yaml ~/.foxxycode/config.yaml.

Windows. Поместите исполняемый файл в %LOCALAPPDATA%\Programs\foxxycode\foxxycode.exe; конфигурация и сессии хранятся в %USERPROFILE%\.foxxycode\ (используйте $env:USERPROFILE, а не $HOME). Команды агента выполняются через pwsh, затем Windows PowerShell, затем cmd.exe; на Unix — через bash, затем sh. Терминал, открытый во время установки, не увидит обновлённый PATH — откройте новый или обновите переменную в текущем. Подробнее: docs/install.md.

Затем укажите ключ провайдера в ~/.foxxycode/config.yaml (или переменную среды OPENAI_API_KEY) и запустите foxxycode http для веб-интерфейса либо foxxycode acp для клиента редактора.

Docker — тот же полный исполняемый файл доступен в образе ghcr.io/hijera/foxxy-agent: выполните docker compose up -d (см. Docker).

В дальнейшем обновляйтесь командой foxxycode update -y (см. Обновление).

Другие способы установки (сборка из исходников, Go install, ручная сборка)

Требования для сборки

• Go — та же минорная версия, что указана в go.mod (сейчас 1.25).
• Git — Makefile использует его для встраивания номера версии.
• Node.js / npm — нужны только при сборке с тегами http и ui (Makefile запускает ui-build для встраиваемых ресурсов).

Установка через Go (минимальный модуль без тегов http / ui)

go install github.com/hijera/foxxycode-agent/cmd/foxxycode@latest

Примечание: go install называет исполняемый файл по каталогу пакета (foxxycode). Чтобы получить foxxycode http, встроенный SPA, планировщик и память, используйте архив релиза или соберите проект из исходников (см. Установку).

Ручной вызов go build

Если TAGS содержит http и ui, сначала выполните make ui-build.

make ui-build
VERSION="$(make -s print-version)"
go build -tags=http,ui,scheduler,memory,cli \
  -ldflags "-X github.com/hijera/foxxycode-agent/internal/version.Version=${VERSION}" \
  -o build/foxxycode \
  ./cmd/foxxycode/

Минимальный исполняемый файл только с ACP: make build (без тегов http, UI, планировщика и памяти).

Настольное приложение Windows (GUI на WebView2; запускается двойным щелчком по foxxycode-desktop.exe):

make build-desktop

Настольное приложение открывает проекты как папки: кнопка проекта в заголовке чата открывает нативный диалог выбора каталога Windows, новые чаты запускаются в выбранной папке, а недавние проекты сохраняются в ~/.foxxycode/projects.json (GET/PUT /foxxycode/project, GET /foxxycode/projects/recent). Если -cwd не указан явно, при запуске восстанавливается последний открытый проект.

Справочник по сборке: docs/build.md.

foxxycode -v выводит встроенную версию. foxxycode acp --help показывает параметры ACP (--home, --cwd, --config и другие).

Теги сборки

В переменной TAGS для Makefile используйте пробелы (make build TAGS="http ui scheduler memory cli browser gateway swarm"), а в go build — запятые (-tags=http,ui,scheduler,memory).

Тег	Что включает	Документация
memory	Компонент долговременной памяти (memory.enabled в YAML); вместе с http — REST для памяти сессии в /foxxycode/sessions/{id}/memory/*	external/memory/README.md
http	foxxycode http, REST-шлюз, /docs, /openapi.yaml	docs/http-api.md
ui	Встроенный SPA на / (требует http)	docs/ui.md, DESIGN.md
scheduler	Демон планировщика и инструменты foxxycode_scheduler_*; вместе с http — REST /foxxycode/scheduler	docs/scheduler.md, external/scheduler/README.md
browser	Интерактивные браузерные инструменты (foxxycode_browser_*: navigate/click/fill/hover/scroll/screenshot/evaluate), управляющие локальным Chrome/Chromium через chromedp; модель видит снимки страницы (browser.enabled в YAML)	docs/browser-tool.md
cli	Интерактивная консоль-TUI — голый foxxycode в терминале (или foxxycode cli): чат с потоковым выводом, карточки инструментов, диалоги разрешений, !!<команда> выполняет команду локально, и агент её не видит; foxxycode -c продолжает последнюю сессию, foxxycode -p "..." выполняет один промпт неинтерактивно, **`--remote <имя	host:port
gateway.telegram	Адаптер Telegram-бота — подкоманда foxxycode gateway, отдельные сессии пользователей и контроль доступа	docs/gateway.md
gateway	Все адаптеры мессенджеров (надмножество gateway.telegram; позволяет добавлять Discord и Slack без изменений ядра)	docs/gateway.md
swarm	Реле роя: узлы регистрируются в нём, а сами реле сцепляются друг с другом. Поднимается командой foxxycode serve при swarm.enabled: true; список swarm.join работает в любой сборке и делает обычного агента достижимым через реле	docs/swarm.md
desktop	Настольное приложение Windows на WebView2 (foxxycode desktop / foxxycode-desktop.exe; требует http, ui и Windows)	docs/build.md

Расширенное описание и соответствие Docker-сборке: docs/build.md.

Docker

Образы релизов публикуются в GitHub Container Registry под именем ghcr.io/hijera/foxxy-agent (теги latest, X.Y.Z и другие; платформы linux/amd64 и linux/arm64). Для каждого SemVer-тега также создаются архивы GitHub Release для Linux, Windows, macOS Intel и Apple Silicon; подробнее в docs/build.md. Публикуемый образ собирается с тем же набором, что и make build TAGS="http ui scheduler memory cli browser gateway swarm" — включая gateway и swarm, так что команда по умолчанию (serve) поднимает те подсистемы, которые включены в примонтированном config.yaml, см. docs/docker.md.

1. Конфигурация и рабочий каталог (из корня репозитория или другого каталога, в котором хранится config.yaml):

cp config.example.yaml config.yaml
mkdir -p workspace foxxycode_home
# Отредактируйте config.yaml: нужен как минимум api_key одного провайдера
# (либо передайте OPENAI_API_KEY и другие переменные через Compose)

2. Запуск через Compose (загрузка опубликованного образа без локальной сборки):

docker compose pull
docker compose up -d

Чтобы собрать образ локально, используйте docker-compose.dev.yml: docker compose -f docker-compose.dev.yml up -d --build.

3. Откройте встроенный интерфейс в браузере на хосте:

http://127.0.0.1:12345/

SPA доступен по GET / после запуска foxxycode http. Выберите модель в поле ввода (YAML-бэкенды из GET /v1/models), режим agent, plan, docs, ask или debug, затем отправьте сообщение. Интерфейс создаст сессию и начнёт потоковую передачу ответа через POST /v1/responses. Файловые и консольные инструменты агента работают в подключённом каталоге (./workspace → /workspace внутри контейнера). Редактор YAML в реальном времени: http://127.0.0.1:12345/#/settings.

Проверка без браузера: curl -sS http://127.0.0.1:12345/v1/models | head.

HTTP-интерфейс не защищён авторизацией — открывайте порт 12345 только в доверенных сетях. Все параметры Compose, тома и теги CI-образов описаны в docs/docker.md. Скрипт быстрой проверки: examples/httpserver/docker.sh.

Пути (FOXXYCODE_HOME, FOXXYCODE_CWD)

• FOXXYCODE_HOME (или foxxycode acp --home) — каталог состояния агента. По умолчанию ~/.foxxycode. Процесс создаёт в нём sessions/ и skills/. Стандартный путь к конфигурации — $FOXXYCODE_HOME/config.yaml.
• FOXXYCODE_CWD (или foxxycode acp --cwd) — стандартный рабочий каталог сессии, когда session/new передаёт пустое значение cwd. По умолчанию это текущий каталог процесса при запуске. Если редактор передаёт путь в session/new, используется именно он.

Настройка

По умолчанию FOXXYCODE_HOME указывает на ~/.foxxycode. Если не задана переменная FOXXYCODE_CONFIG и не передан параметр --config, основным файлом конфигурации будет config.yaml в $FOXXYCODE_HOME/config.yaml.

Скопируйте пример и отредактируйте его:

mkdir -p ~/.foxxycode && cp config.example.yaml ~/.foxxycode/config.yaml

Если $FOXXYCODE_HOME/config.yaml отсутствует, загрузчик может использовать config.yaml из текущего рабочего каталога процесса — это удобно при запуске из клона репозитория. Подробнее в docs/config.md.

Провайдеры и модели

• providers — именованные бэкенды (type: openai для OpenAI и OpenAI-совместимых HTTP API, anthropic для Anthropic, neuraldeep для NeuralDeep на любом из двух официальных эндпоинтов (выбирается через api_base), codex для ChatGPT OAuth через официальный Codex backend). Поле name должно состоять из ASCII-букв, цифр, дефиса или подчёркивания и начинаться с буквы: оно становится префиксом идентификатора модели. Провайдеры с API-ключом принимают api_key (строка, выражение ${ENV} или пустое значение для чтения NAME_API_KEY) и опциональный api_base. Для codex войдите через Sign In with ChatGPT во встроенном UI или выполните foxxycode providers login codex в терминале (старая форма foxxycode codex login осталась псевдонимом и печатает предупреждение); api_key и api_base игнорируются, а токены хранятся в $FOXXYCODE_HOME/providers/<name>/. Вход из терминала также добавляет провайдера, модели подписки и agent.model в config.yaml, если их там нет (--no-config это пропускает). Codex используется только как модельный backend: системный prompt, инструменты и разрешения остаются FoxxyCode. При отсутствии управляемого токена поддерживается fallback на ~/.codex/auth.json от Codex CLI. Для neuraldeep вместо вставки ключа войдите под учёткой хаба: foxxycode providers login neuraldeep печатает короткий код и страницу хаба для подтверждения (device flow, RFC 8628: браузер может быть на любой машине — именно это нужно серверу по SSH; --browser просит loopback-callback, который завершается только в браузере на этой машине; --api-base выбирает эндпоинт и переносит на него существующую строку), сохраняет выданный хабом ключ в $FOXXYCODE_HOME/providers/<name>/neuraldeep-auth.json и добавляет модели тарифа в config.yaml (--no-config это пропускает); во встроенном UI на строке провайдера есть кнопка Войти через NeuralDeep. Явные api_key / api_key_command / NEURALDEEP_API_KEY имеют приоритет над сохранённым входом. foxxycode providers list показывает провайдеров вместе с источником учётных данных, а foxxycode providers logout <name> отзывает ключ на хабе (best-effort) и забывает его локально.
• models — доступные для выбора модели. Строка model имеет вид <provider_name>/<api_model_id>, где provider_name совпадает с providers[].name. Доступные параметры: max_tokens, temperature и опциональный max_context_tokens.
• agent — поле model выбирает стандартную модель ReAct и должно совпадать с одной из записей models[].model. Параметры max_turns и max_tokens_per_turn ограничивают один пользовательский запрос. Поверх этих ограничений работает защита от зацикливания loop_guard (по умолчанию true): поток ответа, выродившийся в повтор одного и того же фрагмента, обрывается (loop_stream_repeat_cycles), инструмент, который запрашивают снова и снова с теми же аргументами, перестаёт выполняться (loop_tool_repeat_limit), а целая последовательность вызовов, которую модель крутит по кругу, — тоже (loop_tool_cycle_repeats: именно это ловит ротацию вроде «читаю A, читаю B, читаю A…», которую счётчик подряд идущих повторов не видит). Сначала модель подталкивают вернуться к задаче; что делать с циклом, пережившим loop_nudge_max подсказок, решает loop_stuck_action: по умолчанию quarantine — зациклившиеся вызовы перестают исполняться до конца хода, а сам ход продолжается и доходит до ответа (если кроме цикла ничего не осталось, у модели забирают инструменты и просят ответить тем, что уже собрано); stop возвращает прежнее поведение и завершает ход уведомлением.

Пример с провайдером openai и моделью gpt-5.4-mini; храните секреты в переменных среды, а не в Git:

providers:
  - name: openai
    type: openai
    api_key: "${OPENAI_API_KEY}"

models:
  - model: "openai/gpt-5.4-mini"
    max_tokens: 400000
    temperature: 0.2

agent:
  model: "openai/gpt-5.4-mini"
  max_turns: 35
  max_tokens_per_turn: 128000

Экспортируйте переменную, на которую ссылается YAML:

export OPENAI_API_KEY="sk-..."

Другие варианты (Anthropic, Ollama, нестандартное значение api_base и значения из переменных среды по умолчанию) описаны в config.example.yaml и docs/config.md.

Обновление

Официальные CLI-сборки публикуются в GitHub Releases (например, foxxycode_0.9.3_linux_amd64.tar.gz). Каждый релиз содержит полный набор функций сборки make build TAGS="http ui scheduler memory cli browser gateway swarm".

Команда foxxycode update загружает архив для текущей ОС и архитектуры и заменяет запущенный исполняемый файл с разрешением символических ссылок. Обычно так обновляют установку после make install (~/.local/bin/foxxycode) или локальный артефакт командой ./build/foxxycode update.

1. Посмотрите, какая версия запущена

which foxxycode
foxxycode -v

2. Проверьте наличие нового релиза

foxxycode update --check

Код завершения 0 означает, что установлена последняя опубликованная версия X.Y.Z или новее. Код 1 означает, что доступен новый релиз.

3. Установите обновление

foxxycode update          # спрашивает [y/N]
foxxycode update -y       # без подтверждения

4. Проверьте результат

foxxycode -v
foxxycode http --help     # только если сборка содержит -tags=http (как официальные релизы)

Основные параметры

Параметр	Назначение
--check	Только проверить наличие обновления, ничего не загружая.
-y / --yes	Установить без подтверждения.
--version X.Y.Z	Установить конкретный релиз, а не только последний.
--repo owner/name	Использовать другой GitHub-репозиторий (по умолчанию hijera/foxxy-agent).

Примечания

• Обновляйте именно тот файл, который собираетесь использовать. Если which foxxycode указывает на ~/.local/bin/foxxycode, запускайте foxxycode update из этой установки, а не другую копию из PATH.
• $FOXXYCODE_HOME с конфигурацией, сессиями и навыками не изменяется; заменяется только исполняемый файл.
• Для сборки из исходников или изменения тегов используйте make build. Для контейнеров — docker compose pull. Таблицы платформ, ограничения и другие способы обновления приведены в docs/update.md.

Режимы работы

Режим Agent (по умолчанию)

Режим полноценного выполнения задач. Агенту доступны все инструменты:

• чтение и запись файлов;
• выполнение команд оболочки с запросом разрешения;
• поиск по кодовой базе;
• вызов инструментов MCP-сервера.

Лучше всего подходит для генерации кода, рефакторинга, отладки и реализации новых функций.

Режим Plan

Режим планирования и документирования с ограниченным набором инструментов:

• чтение и поиск в рабочем каталоге;
• использование оболочки и настроенных MCP-инструментов для исследования;
• сохранение и загрузка проектных планов специальными инструментами.

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

Лучше всего подходит для архитектурного планирования, спецификаций, проектной документации и ревью кода.

Режим Docs

Режим сопровождения документации с закрытым набором инструментов:

• запрос на ревью ничего не изменяет, если пользователь явно не попросил обновить файлы;
• можно читать и искать в рабочем каталоге, а затем сверять утверждения с реализацией и наблюдаемыми результатами тестов;
• файлы .md внутри рабочего каталога сессии можно создавать и редактировать защищёнными инструментами docs_write и docs_edit;
• недоступны оболочка, MCP, общие операции изменения файлов, инструменты планов и списков задач.

Markdown-инструменты запрещают выход за пределы рабочего каталога и переход по символическим ссылкам, защищают internal/prompts/, требуют явного согласия перед перезаписью существующего файла и принимают только непустое уникальное точное совпадение при точечном редактировании, кроме случаев намеренной замены всех совпадений. Для изменения исходного кода или конфигурации переключитесь в режим agent.

Лучше всего подходит для синхронизации README и docs/ с кодом, обновления руководств оператора и описания API.

Режим Ask

Режим ответов на вопросы и исследования без изменения проекта:

• модели доступны только read, keep_result, glob, grep, print_tree, websearch, webfetch, question и load_skill;
• нет оболочки, инструментов планов/задач/конфигурации, MCP-инструментов, записи файлов и документации, планировщика, SSH, управления браузером и изменения памяти (память работает в режиме recall-only);
• вызов инструмента вне этого списка (например, повтор из истории, записанной в режиме agent) отклоняется на этапе выполнения с пометкой о read-only режиме, а не запускается;
• запуск сохранённого плана через metadata.runPlanSlug или Run plan в режиме ask отклоняется с кодом 409 — переключитесь в agent.

Лучше всего подходит для ответов по репозиторию, ревью кода и проверки фактов без изменения состояния проекта.

Режим Debug

Режим системной диагностики. Набор инструментов такой же, как у agent — исправление куда-то должно попасть, — но промпт меняет порядок работы:

• сначала зафиксировать саму ошибку: воспроизвести её или точно записать команду, входные данные, текст ошибки и версии;
• перебрать 5–7 различных возможных источников проблемы на разных уровнях, затем свести к 1–2 наиболее вероятным и объяснить, почему остальные отброшены;
• проверить ведущую гипотезу логированием, диагностическим выводом или точечным падающим тестом до изменения поведения;
• подтвердить диагноз у вас через инструмент question, прежде чем применять исправление;
• исправлять минимально, проверить, что исходная ошибка ушла, и убрать временную диагностику.

Портировано из режима debug в kilocode, где агент точно так же получает полные права, а дисциплина задаётся промптом.

Лучше всего подходит для поиска первопричины, регрессий, плавающих ошибок и любых багов, где угаданное исправление хуже его отсутствия.

Выберите режим в настройках сессии редактора или через session/set_config_option.

Правила

Если rules.auto_discover включён, правила проекта, передаваемые через {{.Rules}}, автоматически находятся внутри рабочего каталога сессии в .foxxycode/rules, в общем для всех агентов .agents/rules (сосед .agents/skills), .cursor/rules, .claude/rules и .codex/rules. Вложенные AGENTS.md (соглашение agents.md) никто не ищет обходом дерева: они читаются в тот момент, когда файловый инструмент заходит в их каталог (корневой AGENTS.md передаётся отдельно как вводная документация проекта). Подробнее в docs/rules.md.

Диалект выбирается по расширению файла, поэтому в одной папке могут лежать оба вида. Файл .mdc — это правило Cursor (description, globs через запятую, alwaysApply; без них — только по @упоминанию); файл .md — правило Claude Code (paths, а без них правило загружается безусловно):

---
description: Стандарты кода Go
globs: **/*.go
alwaysApply: false
---

Пишите все комментарии на английском языке.
Для оборачивания ошибок используйте fmt.Errorf("context: %w", err).

---
description: Стандарты кода Go
paths:
  - "**/*.go"
---

Пишите все комментарии на английском языке.
Для оборачивания ошибок используйте fmt.Errorf("context: %w", err).

Навыки

Slash-команды и пакеты SKILL.md, передаваемые через {{.Skills}}, расширяют агента предметными знаниями и специализированными процессами.

Стандартные каталоги (от низшего к высшему приоритету):

Приоритет	Путь	Назначение
низший	~/.agents/skills/	Общие навыки, установленные через npx skills или npx skillsbd и доступные всем агентам
↑	~/.foxxycode/skills/	Навыки FoxxyCode; могут содержать символические ссылки на ~/.agents/skills/
высший	${CWD}/.foxxycode/skills/	Навыки проекта, переопределяющие одноимённые навыки из предыдущих каталогов

Если навык с одним именем встречается в нескольких местах, более поздний каталог имеет приоритет.

Поиск и установка навыков:

• skills.sh — реестр сообщества; установка: npx skills add <owner/repo@skill>
• neuraldeep.ru/skills — реестр skillsbd, отобранный для FoxxyCode; установка: npx skillsbd install <name>
• Маркетплейсы — FoxxyCode сам ставит навыки из GitHub-репозитория (owner/repo[@ref]), git URL или marketplace.json по стандарту agents (подходят и маркетплейсы плагинов Claude Code), без Node.js. Источники перечисляются в skills.sources, устанавливаются по запросу: в Настройки → Навыки (веб-интерфейс и панели IntelliJ и VS Code), командой /plugin в чате или foxxycode plugin …; версии и обновления отслеживаются

CLI:

foxxycode skills list                              # список установленных навыков и их состояние
foxxycode skills enable <name>                     # включить навык
foxxycode skills disable <name>                    # выключить навык без удаления
foxxycode plugin marketplace add <owner/repo>      # добавить маркетплейс и установить его навыки
foxxycode plugin marketplace list                  # маркетплейсы и их состояние
foxxycode plugin install <owner/repo>              # установить или обновить навыки источника

Полное описание см. в docs/skills.md.

Интеграция MCP-серверов

Подключайте внешние инструменты через MCP по stdio (локальная команда), http (Streamable HTTP с автоматическим откатом на legacy SSE) или sse. Серверы можно задать глобально в config.yaml (mcp_servers) либо в совместимом с Cursor файле ~/.foxxycode/mcp.json, локально для проекта в ./.foxxycode/mcp.json (более поздний уровень переопределяет сервер по имени) или передать для конкретной сессии через ACP-клиент. Серверы целиком и отдельные инструменты можно отключать в конфигурации, через REST API /foxxycode/mcp* или в веб-интерфейсе Настройки → MCP-серверы.

Пример добавления GitHub MCP-сервера в конфигурацию:

mcp_servers:
  - name: "github"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      - name: "GITHUB_PERSONAL_ACCESS_TOKEN"
        value: "${GITHUB_TOKEN}"

Тот же сервер в .foxxycode/mcp.json вместе с удалённым:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "remote-tools": { "url": "https://mcp.example.com/mcp" }
  }
}

Удалённый сервер за самоподписанным или просроченным сертификатом раньше нельзя было подключить вовсе. Для таких случаев у записи есть insecure_skip_verify (insecureSkipVerify в mcp.json) — флажок «Игнорировать ошибки SSL-сертификата» в строке сервера в разделе «Настройки → Серверы MCP». Он выключен по умолчанию, показан только у серверов с url и снимает защиту от подмены сервера — включайте лишь в доверенной сети. Флаг входит в одобряемое объявление, поэтому его включение заставит проектный сервер спросить разрешение заново.

Локальный ./.foxxycode/mcp.json приходит вместе с чекаутом, то есть команду, которую запустит сессия, выбирает репозиторий, а не вы. Поэтому такие записи не запускаются до одобрения для конкретной рабочей папки (mcp.project_trust: ask, значение по умолчанию):

foxxycode mcp list

foxxycode mcp trust <name>

То же решение доступно через POST /foxxycode/mcp/{name}/trust и по кнопке-щиту в разделе «Настройки → Серверы MCP». Одобрение привязано к рабочей папке и к дайджесту объявления, поэтому правка записи спрашивает заново. Серверы из config.yaml и ~/.foxxycode/mcp.json принадлежат вам и через гейт не проходят.

Для рабочей папки, которой вы уже доверяете (или для CI), поставьте mcp.project_trust: allow в config.yaml либо передайте --mcp-project-trust allow в foxxycode acp / foxxycode http — тогда это подействует только на один процесс; deny не загружает серверы проекта вовсе.

Подробнее в руководстве по интеграции MCP.

Шлюз мессенджеров

Релизные архивы CLI и настольное приложение собраны с тегом gateway, так что команда foxxycode gateway работает из коробки. Для своей сборки используйте -tags gateway.telegram (только Telegram) или -tags gateway (все адаптеры).

make build TAGS="gateway.telegram"
./build/foxxycode gateway --config ~/.foxxycode/config.yaml

Минимальное дополнение к config.yaml:

gateways:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    admins: [YOUR_USER_ID]
    default_access: "admins"   # all | admins | group:<name>
    default_isolation: "admin" # individual | shared | admin
    rich_messages: true        # Bot API 10.1 Rich Messages (нативный Markdown и блоки инструментов)

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

При rich_messages: true бот использует Rich Messages из Bot API 10.1: весь Markdown агента (заголовки, таблицы, код, списки задач) отображается нативно, активность инструментов транслируется вместо заполнителя «Thinking…», а выполненные инструменты показываются в сворачиваемом блоке. Если сервер Bot API не поддерживает эту возможность, бот возвращается к прежнему форматированию. Подробнее в docs/gateway.md.

Полное руководство по уровням доступа, режимам изоляции групп, настройкам отдельных чатов и созданию новых адаптеров: docs/gateway.md.

Справочник по конфигурации

Полное описание доступно в docs/config.md, таблицы отдельных полей — в docs/config-reference.md. JSON Schema включает автодополнение и проверку в редакторе через заголовок # yaml-language-server: $schema=... (см. config.example.yaml). Та же схема встроена в бинарник: foxxycode -t (а также foxxycode serve -t, foxxycode http -t, foxxycode acp -t) проверяет по ней и по правилам загрузчика тот файл, который загрузил бы запуск, печатает каждую проблему со строкой и способом починки и возвращает 1 при ошибках (см. docs/config.md). foxxycode --dry-run делает ту же проверку и затем пробует то, на что файл указывает: каталоги, модель-серверы и их ключи, MCP-команды, токен Telegram, адреса прослушивания — и заканчивает одной строкой статуса; с --test-config показывает полный отчёт (docs/config.md).

Основные настройки:

providers:
  - name: local
    type: openai
    api_key: "${OPENAI_API_KEY}"
    api_base: "${OPENAI_API_BASE}"

models:
  - model: "local/gpt-4o"
    max_tokens: 8192
    temperature: 0.2

agent:
  model: "local/gpt-4o"
  max_turns: 30

tools:
  require_permission_for_commands: true

Архитектура

ACP-клиент (редактор / скрипт / CI)      Мессенджер (Telegram и другие)
        |                                        |
    JSON-RPC 2.0 через stdio             Шлюз Hub (горутина адаптера)
        |                                        |
    Уровень ACP-сервера                  session.Manager (общий)
        |                                        |
    Менеджер сессий ─────────────────────────────┘
        |
    Цикл ReAct-агента
 /      |       |      \
LLM  Инструменты Навыки  MCP

Полное описание см. в документации по архитектуре.

Документация

• Отличия FoxxyCode от coddy-agent — функции форка в сравнении с исходным проектом
• Дорожная карта — планы по версиям 0.3.x, 0.4.x и 0.5.x
• Сборка из исходников — требования, make build, отличие TAGS от go build -tags, каталог build/foxxycode
• Обновление FoxxyCode — foxxycode update, артефакты релизов, PATH и make install
• Docker — образ GHCR, docker compose, встроенный интерфейс по адресу http://127.0.0.1:12345/
• Архитектура — устройство системы и обзор компонентов
• Протокол ACP — справочник по протоколу и форматы сообщений
• Агент ReAct — устройство цикла ReAct и спецификации инструментов
• Конфигурация — полное описание файла конфигурации, таблицы полей и JSON Schema для проверки в редакторе
• HTTP API — REST-шлюз (-tags=http) и встроенный интерфейс (-tags=http,ui), включая /foxxycode/config для редактирования YAML в SPA (#/settings)
• Встроенный интерфейс — функциональная спецификация, разработка через Vite и теги сборки
• DESIGN.md — токены и компоновка интерфейса (на английском языке)
• AGENTS.md — карта репозитория и памятка для автоматизированных участников
• Правила — правила проекта (.cursor/rules, .foxxycode/rules и другие)
• Хуки Codex — как .cursor/rules/*.mdc попадают в сессию Codex CLI, работающую с этим репозиторием
• Хуки OpenCode — детерминированная доставка .cursor/rules/*.mdc в сессии OpenCode, работающие с этим репозиторием
• Хуки ZCode — то же самое для сессий ZCode
• Навыки — slash-команды и skills.dirs
• Фоновые задачи — отсоединённые команды, пул задач, таймауты и грант на целую программу
• Субагенты — файлы определений, receipts доверия проекта, инструмент spawn_agent, сужение возможностей, дочерние сессии
• Хуки — таблица событий, JSON-контракт на stdin и stdout, receipts доверия проекта, а также поверхности одобрения в CLI и HTTP
• Экспорт сессии — команда /export, её двойник foxxycode sessions export, форматы и содержимое документа
• Интеграция MCP — руководство по MCP-серверам
• Свои инструменты — как добавить в агента собственный инструмент
• Встраивание в IntelliJ — как плагин размещает у себя SPA и бинарник
• Удалённое управление — работа против удалённого foxxycode http
• Диагностика — включаемый слой debug:: захват сырых LLM-запросов, трассировка хода, GET /foxxycode/sessions/{id}/debug, переключение без перезапуска
• Демон serve — один процесс на все включённые подсистемы: передний план, фоновый диспетчер (--daemon), serve status|stop|restart
• Рой (swarm) — реле, в которое регистрируются узлы: foxxycode serve, сцепление реле, обратный туннель для узла за файрволом и экран топологии в интерфейсе
• Шлюз мессенджеров — адаптер Telegram-бота, изоляция сессий, ACL и создание новых адаптеров

Примеры (ACP через stdio)

examples/acp/acp_e2e_todo.py — построчная JSON-RPC-среда для foxxycode acp ( stdbuf -oL, автоматический ответ на запрос разрешения, ответы с nil-result). Используйте её как основу для минимального клиента, а не объединяйте простые команды echo в конвейер.

examples/acp/acp_e2e_memory.py запускает build/foxxycode с изолированным FOXXYCODE_HOME и RPA_API_KEY, чтобы проверить чтение, сохранение и опциональную очистку Markdown-файлов в $FOXXYCODE_HOME/memory. Параметры описаны в docstring скрипта. Обзор всех примеров: examples/README.md.

Постоянные сессии

По умолчанию foxxycode acp и foxxycode http сохраняют каждую сессию в $FOXXYCODE_HOME/sessions/<sessionId>/ (обычно ~/.foxxycode/sessions/): там находятся session.json, messages.json, каталог assets/, файл todos/active.md и каталог todos/archive/ для заменённых завершённых списков. Корневой каталог можно изменить через foxxycode acp --sessions-dir, foxxycode http --sessions-dir или sessions.dir в config.yaml. Если каталог сессий невозможно создать, запуск завершается ошибкой.

• foxxycode sessions list выводит сохранённые сессии и поддерживает фильтры --sessions-dir и --cwd.
• foxxycode acp --session-id <id> заставляет следующий вызов session/new открыть сохранённое состояние этой папки, если оно существует, либо создать новую сессию с таким именем каталога.
• session/load восстанавливает историю и уведомляет клиента; session/list перечисляет сохранённые сессии для ACP-совместимых клиентов.

Инструменты foxxycode_todo_* синхронизируют активный список с todos/active.md. Полная замена через foxxycode_todo_plan_replace при наличии незавершённых пунктов отклоняется: сначала завершите их или выполните foxxycode_todo_plan_archive. Если все пункты имеют состояние completed, при замене прежний active.md перемещается в todos/archive/ под именем todo-<nanos>.md. Команда foxxycode_todo_plan_archive переводит открытые пункты в состояние completed, записывает todos/archive/plan_<unix_seconds>.md и очищает план сессии, если включено постоянное хранение.

Если сохранённый план не пуст, агент добавляет в шаблон системного промпта заголовок ### Current todo checklist и строки Markdown-списка. Встроенные шаблоны собираются из секций под internal/prompts/sections/, а файлы из prompts.dir сохраняют прежнюю форму с настраиваемыми именами agent.md, plan.md, docs.md плюс фиксированные ask.md и debug.md. Вставка выполняется через {{if .TodoList}} … {{end}} и пропускается, когда список пуст. Перед каждым вызовом LLM в рамках одного запроса session/prompt FoxxyCode обновляет системное сообщение, поэтому созданный или изменённый ранее в том же эпизоде ReAct список сразу остаётся видимым.

Разработка

# Запуск тестов
go test ./...
make test          # экспресс-прогон: SPA + один проход со всеми тегами
make test-matrix   # каждая комбинация тегов по очереди (то же, что гоняет CI)

# Примеры среды (см. examples/README.md):
# ./examples/build_foxxycode.sh && ./examples/test_acp.sh && ./examples/test_httpserver.sh

# Полнофункциональная локальная сборка (HTTP + UI + планировщик), как в Docker
make build TAGS="http ui scheduler memory cli browser gateway swarm"

./build/foxxycode -v    # то же, что --version

# Запуск с отладочными логами в режиме ACP; доступны --log-output, --log-file, --log-format
foxxycode acp --log-level debug

# Только простая однострочная проверка (ответы могут не содержать JSON-RPC "result" при nil;
# для полноценной проверки используйте examples/acp/acp_e2e_todo.py)
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}' | foxxycode acp

Какая сборка кому подходит

У FoxxyCode один исходник и один исполняемый файл, а различаются сборки набором тегов (см. Теги сборки). Таблица — от «просто поставить и работать» к «собрать под себя».

Сборка	Где взять	Что внутри	Кому подходит
Настольное приложение	foxxycode-desktop_<версия>_windows_amd64.zip в Releases	полный набор + desktop (окно WebView2, без консоли)	Тем, кому нужно обычное приложение с окном: чат, настройки, уведомления и звуковой сигнал, пошаговое знакомство при первом запуске. Только Windows x64
Релизный архив CLI	foxxycode_<версия>_<ос>_<арх>.{tar.gz,zip} в Releases	http ui scheduler memory cli browser gateway	Вариант по умолчанию для большинства. Консоль в терминале (foxxycode), веб-интерфейс (foxxycode http → http://127.0.0.1:12345/), планировщик, память, браузерный инструмент, шлюз мессенджеров (foxxycode gateway). Linux, Windows, macOS (Intel и Apple Silicon)
Плагин IDE	zip для IntelliJ и .vsix для VS Code приложены к тому же GitHub Release. Для IntelliJ есть репозиторий плагинов с автообновлением: добавьте https://hijera.github.io/foxxy-agent/updatePlugins.xml в Settings → Plugins → ⚙ → Manage Plugin Repositories	тот же полный набор, без cli и gateway	Тем, кто работает внутри редактора: панель чата, контекст открытых файлов, @terminal, перетаскивание файлов, нативные inline-diff в IntelliJ. Исполняемый файл уже внутри плагина — ставить отдельно не нужно
Docker-образ	ghcr.io/hijera/foxxy-agent (latest, X.Y.Z; linux/amd64 и linux/arm64)	http scheduler ui memory cli browser	Серверу, команде и CI: один общий экземпляр с веб-интерфейсом, рабочий каталог монтируется томом. Chrome в образе нет — для браузерного инструмента соберите производный образ; тега gateway тоже нет
Полная сборка из исходников	make build TAGS="http ui scheduler memory cli browser gateway"	то же, что в релизном архиве	Тем, кто правит код форка или собирает под платформу, которой нет в релизах
Лёгкая сборка, только ACP	make build (без тегов)	ACP-сервер, сессии, промпты, инструменты	Встраиванию в редактор или скрипт по ACP и минимальным контейнерам (scratch, distroless, ФС только для чтения): нет HTTP, SPA, планировщика и памяти — самый маленький исполняемый файл
Шлюз мессенджеров	уже в релизном архиве CLI и настольном приложении; лёгкая своя сборка: make build TAGS="http ui scheduler memory gateway.telegram" либо docker-compose.dev.yml	подкоманда foxxycode gateway	Телеграм-боту с изолированными сессиями пользователей. Тега gateway нет только в публикуемом Docker-образе — для него соберите свой образ
go install	go install github.com/hijera/foxxycode-agent/cmd/foxxycode@latest	без опциональных тегов	Быстрой пробе, когда нужен только ACP. Ни foxxycode http, ни SPA, ни планировщика в такой сборке не будет — для них берите релизный архив

Собрать нестандартный набор помогает мастер python scripts/build.py (русскоязычное меню, пресеты тегов и выбор целевых платформ) — см. docs/build.md.

Лицензия

Проект распространяется по лицензии MIT. Полный текст находится в файле LICENSE в корне репозитория.