NekoFree

Терминальный AI-агент для работы с кодом. Форк Claude Code с поддержкой локальных моделей через OmniRoute, вырезанной телеметрией и экономией токенов. Pre-configured для работы с localhost:20128, поддерживает nekocode.app и любой Claude-совместимый API.

---

Что это

Полнофункциональный AI-агент в терминале: пишет код, читает файлы, запускает команды, работает с git, ставит плагины. Всё через диалог на естественном языке.

Ключевые отличия от оригинала (Claude Code):

• Локальные модели через OmniRoute — работает с локальным Claude-совместимым API (localhost:20128)
• Нет телеметрии — вычищены OpenTelemetry, Datadog, Sentry, event logging, session tracing
• Нет guardrails — снят CYBER_RISK_INSTRUCTION и ManagedSettingsSecurityDialog
• Экономия токенов — read-once кеш, diff mode, output cap 16k вместо 64k
• Pre-configured для локальной работы — gateway localhost:20128 из коробки, поддержка nekocode.app/OpenRouter
• Quality toolkit — gstack skills + Boucle hooks из коробки
• Маскот-кот — пиксель-арт 16x16 с реактивными эмоциями в статуслайне

Запустил ./nekofree, настроил OmniRoute — и работаешь с локальными моделями.

---

Возможности

Модели и API

• Локальные модели — OmniRoute localhost:20128 из коробки (kr/claude-sonnet-4.5 default)
• Альтернативы — nekocode.app gateway, OpenRouter, любой Claude-совместимый endpoint
• Нет телеметрии — все analytics-модули заменены на заглушки, ноль данных наружу
• Нет prompt-guardrails — модель отвечает как модель, без навешанных ограничений

Экономия токенов

• Read-once hooks — кеширует прочитанные файлы, при повторном чтении экономит тысячи токенов
• Diff mode — при изменении файла отдаёт только дельту вместо полного перечитывания
• Output cap 16k — вместо 64k по умолчанию, auto-escalate при необходимости
• Контекст 200k — 1M отключён для экономии квоты

Quality Toolkit (из коробки)

• gstack skills — /review, /qa, /cso, /investigate, /design-review и др.
• Boucle hooks — git-safe, read-once guard для безопасности и оптимизации
• GSD integration — инструкция установки get-shit-done workflow system

UX

• Маскот — пиксель-арт кот 16x16, меняет эмоции в реальном времени
• Статуслайн — ctx%, стоимость сессии, текущая директория, модель
• 185 spinner verbs — кото-мемные фразы при обдумывании
• CCH signing — xxHash64 integrity hash для запросов к gateway

Экспериментальные фичи

• 54 feature flags — разблокированы в dev-full билде
• Инструменты, плагины, скиллы, MCP, plan mode, voice mode, IDE bridge

---

Требования

• Bun >= 1.3.11
• Linux или macOS (Windows через WSL)

curl -fsSL https://bun.sh/install | bash

---

Установка

git clone https://github.com/Ap3x0s/NekoFree.git
cd NekoFree
bun install
bun run build
./nekofree

Бинарник готов. Можно добавить алиас:

echo 'alias nekofree="/путь/до/NekoFree/nekofree"' >> ~/.zshrc
source ~/.zshrc

---

Сборка

Команда	Бинарник	Описание
bun run build	./nekofree	Стандартная сборка
bun run build:dev	./nekofree-dev	Dev-версия с меткой
bun run build:dev:full	./nekofree-dev	Все 54 экспериментальных флага
bun run compile	./dist/nekofree	Альтернативный путь

Конкретные флаги:

bun run ./scripts/build.ts --feature=ULTRAPLAN --feature=ULTRATHINK

---

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

Быстрый старт с локальными моделями

1. Скопируй шаблон конфига:

cp config.example.json ~/.nekofree/config.json

2. Отредактируй ~/.nekofree/config.json:

{
  "baseUrl": "http://localhost:20128/v1",
  "apiKey": "sk-your-api-key-here",
  "model": "kr/claude-sonnet-4.5"
}

3. Настрой hooks (опционально):

cp settings.example.json ~/.claude/settings.json

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

Переменная	Назначение
ANTHROPIC_API_KEY	API-ключ (приоритет над конфигом)
ANTHROPIC_BASE_URL	Свой endpoint (localhost:20128, nekocode.app, OpenRouter)
ANTHROPIC_MODEL	Модель по умолчанию
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Лимит output-токенов (по умолчанию 16000)
CLAUDE_CODE_DISABLE_1M_CONTEXT	Отключить 1M контекст (по умолчанию включено)
READ_ONCE_DISABLED	Отключить read-once кеш
READ_ONCE_DIFF	Включить diff mode для кеша

Quality System

Включено из коробки:

• gstack skills в .claude/skills/gstack/ — используй через /review, /qa, /cso
• Boucle hooks в .claude/hooks/ — git-safe, read-once guard
• Quality checklists в .claude/quality/ — code review, security, QA

Опционально (рекомендуется):

npx get-shit-done-cc@latest

Добавляет workflow guards, context monitoring, security validation.

---

Экономия токенов

nekofree экономит токены на трёх уровнях:

Read-once кеш — при повторном чтении неизменённого файла агент получает уведомление, что содержимое уже в контексте. Экономия ~2000+ токенов за каждый хит. При включённом diff mode изменённые файлы показывают только дельту — экономия 80-95%.

Output cap — дефолтный лимит output-токенов снижен с 64k до 16k. 99% ответов укладываются в этот лимит. Если ответ реально упирается — автоматический escalate до 64k на следующей попытке.

Контекст 200k — 1M контекст отключён по умолчанию. Меньше контекст — меньше расход квоты на каждый запрос.

---

Маскот

Пиксельный кот в статуслайне реагирует на происходящее в реальном времени:

• idle — спокойный, нейтральные глаза
• thinking — синий пиксель, агент генерирует текст
• tool_running — глаза ー ー, синее свечение, выполняется инструмент
• done — зелёные искорки +, задача завершена

Под котом — статистика: заполненность контекста, стоимость сессии, рабочая директория, модель.

---

Основано на

• free-code — форк с вырезанной телеметрией и снятыми guardrails, отправная точка nekofree
• Boucle Framework — фреймворк автономных агентов с хуками безопасности
• claude-code-mascot-statusline — идея маскота в статусной строке

---

Лицензия

Исходный код основан на публично доступном снимке npm-дистрибуции. Используйте на свой страх и риск.