FoxxyCode Agent

Русский | 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), упоминание файлов перетаскиванием, выбор папки проекта и нативные встроенные diff в IntelliJ
Интерактивный браузерный инструмент — управляет настоящим Chrome через chromedp и возвращает модели снимки экрана (-tags=browser); подробнее в разделе браузерного инструмента
Автоматическое сжатие контекста — по умолчанию автоматически суммирует длинные диалоги
Русская локализация настроек и полный ребрендинг дистрибутива в foxxyCode

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

Содержание

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

Возможности

Среда выполнения — прежде всего — ACP-сервер, жизненный цикл сессий, промпты, LLM-бэкенды, объединение MCP и готовый для distroless исполняемый файл
Цикл ReAct — LLM чередует рассуждение, действие (вызов инструментов) и наблюдение за результатами; профиль кодинг-агента доступен из коробки
Четыре режима работы — agent (полный доступ к инструментам), plan (планирование без реализации), docs (защищённое редактирование Markdown-документации) и ask (ответы и исследование без изменений)
Правила — автоматически находит .cursor/rules/, .foxxycode/rules/, .claude/rules/, .codex/rules/ и вложенные **/AGENTS.md (соглашение agents.md) в рабочем каталоге сессии; подробнее в разделе Правила
Навыки — slash-команды и пакеты SKILL.md из skills.dirs (по умолчанию: ~/.agents/skills, ~/.foxxycode/skills, ${CWD}/.foxxycode/skills; более поздний каталог имеет приоритет); подробнее в разделе Навыки
Фоновые задачи — run_command умеет работать отдельно от хода (background: true плюс собственная оценка модели expected_seconds); background_list / background_output / background_wait / background_stop забирают результат позже, панель Фоновые задачи в UI показывает, что ещё выполняется, а диалог разрешений умеет расширить грант до целой программы (curl, git status), чтобы серия похожих вызовов спрашивала один раз; подробнее в разделе Фоновые задачи
Интеграция MCP-серверов — подключение любого MCP-сервера для доступа к дополнительным инструментам
Несколько LLM-провайдеров — OpenAI, Anthropic, Ollama и любой OpenAI-совместимый API
Мультимодальность и вложения — изображения и файлы можно прикреплять через поле ввода (📎), если в настройках модели указано multimodal: true; файлы сохраняются в ~/.foxxycode/sessions/<id>/assets/, передаются в контекст агента и отображаются в сообщении пользователя
Уровень рассуждения — для моделей с рассуждением (gpt-5, серия o, gpt-oss, qwen3, модели Claude с thinking) выпадающий список в поле ввода задаёт уровень (minimal/low/medium/high), который преобразуется в OpenAI reasoning_effort или Anthropic extended-thinking budget_tokens; поддержка определяется автоматически по идентификатору модели и настраивается для каждой модели — см. Настройку
Протокол 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/foxxycode-agent
cd foxxycode-agent
make build TAGS="http ui scheduler memory cli"
make install   # копирует build/foxxycode в ~/.local/bin или /usr/local/bin

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

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

Создайте начальную конфигурацию: 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/foxxycode-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"), а в 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`
`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/foxxycode-agent (теги latest, X.Y.Z и другие; платформы linux/amd64 и linux/arm64). Для каждого SemVer-тега также создаются архивы GitHub Release для Linux, Windows, macOS Intel и Apple Silicon; подробнее в docs/build.md. Стандартный образ включает http, ui, scheduler и memory — тот же набор функций, что и make build TAGS="http ui scheduler memory cli".

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, затем отправьте сообщение. Интерфейс создаст сессию и начнёт потоковую передачу ответа через 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, codex для ChatGPT OAuth через официальный Codex backend). Поле name должно состоять из ASCII-букв, цифр, дефиса или подчёркивания и начинаться с буквы: оно становится префиксом идентификатора модели. Провайдеры с API-ключом принимают api_key (строка, выражение ${ENV} или пустое значение для чтения NAME_API_KEY) и опциональный api_base. Для codex войдите через Sign In with ChatGPT во встроенном UI или выполните foxxycode codex login в терминале; api_key и api_base игнорируются, а токены хранятся в $FOXXYCODE_HOME/providers/<name>/. Codex используется только как модельный backend: системный prompt, инструменты и разрешения остаются FoxxyCode. При отсутствии управляемого токена поддерживается fallback на ~/.codex/auth.json от Codex CLI.
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_nudge_max подсказок, завершается уведомлением.

Пример с провайдером 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".

Команда 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/foxxycode-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-only команды оболочки, web-поиск и чтение страниц, просмотр планировщика и MCP-инструменты с аннотацией readOnlyHint: true;
цепочки команд, перенаправление вывода, подстановка команд и команды вне read-only списка отклоняются до выполнения;
недоступны изменения планов и задач, мутации планировщика, SSH, управление браузером и изменение памяти.

Галочка Disable extended Ask tools в Settings → Tools управляет параметром tools.ask_disable_extended_tools и по умолчанию выключена. Если её включить, Ask скрывает shell, MCP, web и планировщик, оставляя чтение, поиск и дерево репозитория, вопросы и навыки.

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

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

Правила

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

Файлы правил часто используют frontmatter в стиле Cursor, например:

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

Пишите все комментарии на английском языке.
Для оборачивания ошибок используйте 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 http) — просмотр и установка из реестра skillsbd прямо в браузере

CLI:

foxxycode skills list              # список установленных навыков и их состояние
foxxycode skills enable <name>     # включить навык
foxxycode skills disable <name>    # выключить навык без удаления

Полное описание см. в 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" }
  }
}

Локальный ./.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.

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

Соберите проект с -tags gateway.telegram (только Telegram) или -tags gateway (все адаптеры), чтобы включить команду foxxycode 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).

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

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
Фоновые задачи — отсоединённые команды, пул задач, таймауты и грант на целую программу
Интеграция MCP — руководство по MCP-серверам
Шлюз мессенджеров — адаптер 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-списка. Встроенные шаблоны или файлы из prompts.dir используют настраиваемые имена agent.md, plan.md и docs.md, а для Ask — ask.md; для Ask также встроены варианты ask.openai.md и ask.gpt-oss.md. Вставка выполняется через {{if .TodoList}} … {{end}} и пропускается, когда список пуст. Перед каждым вызовом LLM в рамках одного запроса session/prompt FoxxyCode обновляет системное сообщение, поэтому созданный или изменённый ранее в том же эпизоде ReAct список сразу остаётся видимым.

Разработка

# Запуск тестов
go test ./...
make test

# Примеры среды (см. 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"

./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

Лицензия

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

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex		.codex
.cursor/rules		.cursor/rules
.githooks		.githooks
.github/workflows		.github/workflows
.opencode		.opencode
.zcode		.zcode
cmd/foxxycode		cmd/foxxycode
docs		docs
editors		editors
examples		examples
external		external
features		features
internal		internal
scripts		scripts
.dockerignore		.dockerignore
.env.examples		.env.examples
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DESIGN.md		DESIGN.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.en.md		README.en.md
README.md		README.md
ROADMAP.en.md		ROADMAP.en.md
ROADMAP.md		ROADMAP.md
UPSTREAM_SYNC.md		UPSTREAM_SYNC.md
config.example.yaml		config.example.yaml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Navigation Menu

Repository files navigation

FoxxyCode Agent

Содержание

Возможности

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

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

Установка

Теги сборки

Docker

Пути (`FOXXYCODE_HOME`, `FOXXYCODE_CWD`)

Настройка

Обновление

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

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

Режим Plan

Режим Docs

Режим Ask

Правила

Навыки

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

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

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

Архитектура

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

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

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

Разработка

Лицензия

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FoxxyCode Agent

Содержание

Возможности

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

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

Установка

Теги сборки

Docker

Пути (FOXXYCODE_HOME, FOXXYCODE_CWD)

Настройка

Обновление

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

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

Режим Plan

Режим Docs

Режим Ask

Правила

Навыки

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

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

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

Архитектура

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

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

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

Разработка

Лицензия

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Пути (`FOXXYCODE_HOME`, `FOXXYCODE_CWD`)