Code Shadow

Теневой Наблюдатель Кодовой Базы

Плагин для OpenCode, который видит закономерности там, где человек видит хаос.

Видение
Проблема
Магический момент
Сравнение с Magic Context
Возможности
🚀 Установка
Обзор архитектуры
Автономность
Технологический стек
Статус проекта
Исправленные баги
Участие в разработке
Лицензия

Видение

Золотая рыбка с искусственным интеллектом

Современные AI-ассистенты кода страдают от фундаментального недостатка: у них нет памяти. Каждая сессия — это чистый лист. Вчерашний рефакторинг? Забыт. Позавчерашний баг, который ты починил с кровью и потом? Не существует. Паттерн ошибок, повторяющийся из месяца в месяц в одном и том же модуле? Никто не заметит, пока не станет слишком поздно.

Ты, как разработчик, тоже подвержен recency bias — ты помнишь то, что случилось сегодня или вчера, но не то, что происходило три месяца назад. А между тем, именно там скрываются самые опасные паттерны: файл, который ломается при каждом третьем рефакторинге; модуль, в который никто не рискует заходить; зависимость, которая тайно тянет за собой каскад багов.

Ответ

Code Shadow — это персистентный наблюдатель, который следит за каждым событием в твоём проекте. Он не просто пассивно собирает данные — он анализирует их, находит закономерности, предсказывает проблемы и доставляет инсайты ровно в тот момент, когда они нужны.

Представь, что у тебя есть молчаливый аналитик, который:

Видел всё, что происходило с кодовой базой за последние 6 месяцев
Помнит каждый баг, каждый рефакторинг, каждый проваленный билд
Знает, какие файлы «кусаются», а какие — стабильны как скала
Может сказать: «Осторожно, последние 3 раза, когда трогали этот файл, билд падал»

Code Shadow превращает сырые данные разработки в полезное знание. Не мнения, не догадки, не «мне кажется» — а холодные, измеримые факты.

Проблема

Что мы теряем каждый день

Каждый рабочий день разработчика генерирует терабайты неявной информации:

Событие	Частота	Что теряется
Редактирование файла	50–200 раз/день	Какие модули самые нестабильные
Запуск тестов	5–20 раз/день	Какие тесты падают чаще всего
Сессии с AI-ассистентом	3–10 раз/день	Контекст принятия решений
Ошибки и баги	1–5 раз/день	Где реально живут проблемы
Git-коммиты	2–10 раз/день	Размер и рискованность изменений

Весь этот поток данных исчезает. Никто его не сохраняет, не анализирует, не использует.

Code Shadow перехватывает этот поток и превращает его в:

Тепловую карту проблемных файлов
Предиктивную модель рисков изменений
Граф знаний архитектурных зависимостей
Персональную статистику продуктивности

Магический момент

Сценарии, от которых захватывает дух

Сценарий 1: «Осторожно, этот файл кусается»

Ты вводишь в OpenCode: «Отрефактори UserService.ts, вынеси валидацию в отдельный модуль»

Агент готовится применить изменения. Но прежде чем он это делает, Code Shadow выводит предупреждение:

┌─────────────────────────────────────────────────────┐
│ ⚠️  ПРЕДУПРЕЖДЕНИЕ SHADOW                           │
│                                                     │
│ UserService.ts изменялся 12 раз за последние 3 мес. │
│ В 7 из 12 случаев (58.3%) это приводило к падению   │
│ билда или тестов.                                   │
│                                                     │
│ Самые частые причины:                               │
│  • Нарушение контракта с AuthService (4 раза)       │
│  • Ошибки в DI-конфигурации (3 раза)                │
│                                                     │
│ Рекомендация: начать с тестов на контракт.          │
└─────────────────────────────────────────────────────┘

Сценарий 2: «Где болит?»

Ты спрашиваешь агента: «Покажи мне реально проблемные места в проекте»

Shadow отвечает не мнением, а данными:

┌─────────────────────────────────────────────────────┐
│ 🔥 ТЕПЛОВАЯ КАРТА (последние 30 дней)               │
│                                                     │
│ 1. 🔴 src/legacy/PaymentProcessor.ts                 │
│    • 34 редактирования                              │
│    • 8 баг-фиксов                                   │
│    • 3 регрессии                                    │
│    • Среднее время фикса: 47 мин                     │
│                                                     │
│ 2. 🟠 src/shared/DateUtils.ts                        │
│    • 28 редактирований                              │
│    • 6 баг-фиксов (таймзоны!)                       │
│    • 0 регрессий                                    │
│                                                     │
│ 3. 🟡 src/api/middleware/auth.ts                     │
│    • 15 редактирований                              │
│    • 2 баг-фикса                                    │
│    • 1 регрессия                                    │
└─────────────────────────────────────────────────────┘

Сценарий 3: «Твой Developer Wrapped»

Конец месяца. Shadow собирает статистику и выдаёт:

┌─────────────────────────────────────────────────────┐
│ 🎉 ТВОЙ DEVELOPER WRAPPED — Июнь 2026               │
│                                                     │
│ 🛠️  Всего изменений:           847                  │
│ 📝  Строк кода написано:        4 231               │
│ 🗑️  Строк кода удалено:         1 892               │
│ 🐛  Багов исправлено:           34                  │
│ 💬  AI-сессий проведено:        142                 │
│                                                     │
│ 🏆  Самый стабильный модуль:    src/types/            │
│     (0 багов за всё время)                          │
│                                                     │
│ 💀  Самый проблемный файл:     src/utils/god-object.ts│
│     (ты возвращался к нему 16 раз в этом месяце)    │
│                                                     │
│ 📈  Тренд: качество кода растёт! Багов на 100        │
│     изменений стало на 22% меньше, чем в мае.        │
└─────────────────────────────────────────────────────┘

Сценарий 4: «А что если...?»

Ты раздумываешь над крупным рефакторингом. Спрашиваешь:

«Если я перепишу модуль авторизации, какие файлы заденет изменение?»

Shadow строит граф зависимостей на основе реальной истории изменений:

src/auth/AuthService.ts
├── src/middleware/auth-guard.ts (зависит, менялся вместе 9 раз)
├── src/api/routes/users.ts (зависит, менялся вместе 7 раз)
├── src/services/TokenService.ts (зависит, менялся вместе 6 раз)
└── src/ui/components/LoginForm.tsx (зависит, менялся вместе 4 раза)

⚠️  Исторически, изменения AuthService также затрагивали
    конфигурацию Docker (docker-compose.yml) в 3 из 12 случаев —
    возможно, есть неочевидная связь.

Сравнение с Magic Context

Code Shadow не заменяет Magic Context полностью — он идёт в другом измерении. Там, где Magic Context работает с текстом и заметками, Code Shadow работает со структурированными данными и событиями.

Таблица сравнения

Аспект	Magic Context	Code Shadow
Тип данных	Текстовые заметки и память	Структурированные события
Способ ввода	Ручной (пользователь пишет заметки)	Автоматический (наблюдение)
Хранилище	JSON/файлы	SQLite (bun:sqlite, WAL)
Поиск	Полнотекстовый по заметкам	SQL-запросы + аналитика + граф знаний
Гранулярность	Сессионная (итоги)	Событийная (каждое действие)
Проактивность	Реактивный (ты спрашиваешь)	Проактивный (CRUSH.md + теневые предупреждения)
Аналитика	Отсутствует	Встроенная: тепловые карты, тренды, предикты
Временной охват	Ограничен сессиями	Полная история с первого дня
Контекст решений	Текстовое описание «почему»	Автоматический diff + результат + контекст
Визуализация	Нет	Тепловые карты, графы, отчёты
Обучение	Нет (статическая память)	Есть (паттерны накапливаются)
Порог входа	Нужно вручную писать заметки	Нулевой — просто пользуешься OpenCode
Конфиденциальность	Заметки видны агенту	Данные локальны, SQLite на диске
Авто-детект фактов	Нет	Да (80+ правил)
Автономность	Нет	Да (CRUSH.md заставляет AI вызывать тулзы)

Как они дополняют друг друга

┌──────────────────────────────────────────────────────┐
│                   РАБОЧИЙ ПРОЦЕСС                     │
│                                                      │
│  Magic Context:                                      │
│  "Я помню, что мы решили использовать Zod вместо Yup" │
│  (знание — текстовое, ручное, осмысленное)            │
│                                                      │
│  Code Shadow:                                        │
│  "Но я вижу, что 40% файлов всё ещё используют Yup"   │
│  (реальность — измеримая, автоматическая, честная)    │
│                                                      │
│  Вместе:                                             │
│  "Мы решили перейти на Zod, но миграция выполнена     │
│   только на 60%. Вот список файлов, которые ещё       │
│   используют Yup."                                   │
└──────────────────────────────────────────────────────┘

Что остаётся за Magic Context

Code Shadow не предназначен для:

Человеческого контекста («Ваня сказал, что этот эндпоинт deprecated»)
Субъективных заметок («этот код — костыль, переписать позже»)

Для этого продолжай использовать Magic Context. Code Shadow добавляет объективный, измеримый слой поверх субъективных заметок. При этом архитектурные решения (ADR) теперь записываются через code_shadow_decide в SQLite.

Возможности

🧠 Авто-память (Auto-Memory Engine)

Плагин автоматически детектит и сохраняет факты о проекте без ручных команд «запомни». 80+ правил детекции покрывают язык, фреймворк, БД, CI/CD, структуру проекта и многое другое.

Язык и рантайм: TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, C#, Ruby, PHP, Lua
Фреймворки: React, Next.js, Vue, Svelte, Angular, Express, Fastify, NestJS, Django, Flask, Rails, Gin
Стилизация: Tailwind CSS, styled-components, CSS Modules, Sass, Less, Vanilla Extract, Panda CSS
Базы данных: Prisma, Drizzle, Knex, Sequelize, TypeORM, SQLite, PostgreSQL, MongoDB, Redis
CI/CD: GitHub Actions, GitLab CI, CircleCI, Docker, Kubernetes, Jenkins, Vercel, Netlify
Тестирование: Jest, Vitest, Mocha, Playwright, Cypress, Storybook
Структура проекта: monorepo (Turborepo, Nx, Lerna), компоненты в src/components/, хуки в src/hooks/

Дедупликация: каждый факт сохраняется не чаще раза в 5 минут (Map-based кэш).

Срабатывает на события:

file.edited — анализ пути файла (расширение, директория)
tool.execute.after — анализ прочитанных конфигов (package.json, tsconfig.json, .eslintrc)

📝 Auto-memory (бесконтактный сбор конвенций)

Без команд «запомни» плагин сам извлекает конвенции из файлов проекта:

AGENTS.md — парсит правила, ограничения, naming conventions
package.json — определяет зависимости, скрипты, движок
tsconfig.json — определяет путь к исходникам (baseUrl, paths), strict-режим
biome.json / .eslintrc — определяет стиль кода и линтер
Dockerfile / docker-compose.yml — определяет контейнеризацию

📊 TUI-панель (Sidebar Stats)

Live-статистика в правом сайдбаре OpenCode:

Здоровье проекта (0–100%, цветовой индикатор: зелёный/жёлтый/красный)
Длительность последней сессии (минуты:секунды)
Сетка StatBox 2×2: сессии, правки, ошибки, файлы
Активность: количество файлов и правок в текущей сессии
Обновляется в реальном времени при каждом событии

🔄 Per-project TUI

Сайдбар показывает статистику текущего проекта, а не глобальную. Фильтрация через project_root из таблицы sessions:

Домашний экран (без активной сессии) — глобальная статистика по всем проектам
Внутри сессии — статистика только для текущего проекта
Реактивное обновление: polling каждые 5 секунд через createSignal (SolidJS)

🤖 Автономный AI

CRUSH.md заставляет AI самостоятельно использовать аналитику Code Shadow без команд пользователя. Подробнее — в разделе Автономность.

📁 Мульти-проект

Отдельная статистика для каждого проекта. Данные не смешиваются:

Сессии помечаются project_root при создании
TUI-панель фильтрует метрики по текущему проекту
Hotspots, граф знаний, профиль разработчика — per-project

🛡️ SQL-безопасность

Все запросы к БД защищены:

Параметризованные запросы — никакой конкатенации SQL-строк
WAL-режим — конкурентное чтение и запись без блокировок (server + TUI читают одну БД)
Graceful shutdown — при завершении: финализация сессий, сброс буфера, wal_checkpoint(TRUNCATE), закрытие соединения
Фильтрация секретов — .env, ключи, токены не сохраняются в БД

🔔 Toast-уведомления

Предупреждения при рискованных изменениях прямо в интерфейсе OpenCode:

Pre-edit warnings — перед применением правок к файлам с высокой «температурой»
Breakage prediction — «Это изменение с вероятностью 58% сломает тесты»
Regression alerts — «Файл имеет историю регрессий. Последние 3 изменения создали 2 новых бага»
Настраиваемые пороги срабатывания через конфиг плагина

🔭 Silent Observer (Безмолвный Наблюдатель)

Автоматически записывает все значимые события в проекте. Никаких настроек, никаких триггеров — просто работает.

File Events — каждое редактирование файла, включая:
- Путь к файлу
- Размер diff'а (строк добавлено / удалено)
- Время редактирования
- ID сессии и хеш коммита
Session Events — каждая сессия OpenCode:
- Длительность сессии
- Количество сообщений и вызовов инструментов
- Тематика (извлекается из контекста)
- Результат (успех / ошибка / прервано)
Error Events — каждая ошибка:
- Тип ошибки (синтаксическая, runtime, тестовая)
- Файл и строка
- Трассировка стека
- Связанный коммит
Tool Execution Events — каждый вызов инструмента:
- Название инструмента
- Параметры (без чувствительных данных)
- Результат (успех / ошибка)
- Длительность выполнения
Git Events — каждый коммит, пуш, создание ветки:
- Хеш коммита и сообщение
- Затронутые файлы
- Размер изменений
- Автор

🔥 Hotspot Engine (Двигатель горячих точек)

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

Bugginess Score (0–100): доля изменений файла, связанных с исправлением багов
Edit Frequency (изменений/день): как часто файл редактируется
Regression Rate (%): доля изменений, создавших новые баги
Time-to-Fix (минуты): среднее время, затраченное на починку файла
Frustration Index (0–100): комбинированная метрика «болезненности» на основе:
- Частоты правок
- Доли баг-фиксов
- Среднего времени фикса
- Частоты, с которой разработчик бросает задачу
Co-change Coupling: какие файлы почти всегда меняются вместе (признак скрытых зависимостей)
Тепловая карта по директориям/модулям для быстрого визуального анализа

🔮 Prediction Engine (Двигатель предсказаний)

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

Risk Score (0–100) для каждого планируемого изменения:
- История багов у затрагиваемых файлов
- Размер изменения (чем больше, тем рискованнее)
- День недели / время суток (да, это влияет!)
- Сложность затрагиваемого модуля
Breakage Probability (%): вероятность, что изменение сломает билд или тесты
Similar Changes: поиск похожих изменений в истории и их исходов
Recommended Pre-checks: какие тесты запустить, какие файлы проверить до коммита
«Если бы ты вчера...»: ретроспективный анализ — «если бы ты запустил тесты перед коммитом #a3f2b1, ты бы сэкономил 45 минут»

🕸️ Knowledge Graph (Граф знаний)

Строит семантическую карту кодовой базы на основе реальной истории разработки, а не статического анализа.

Logical Dependencies: связи между файлами, выявленные через историю совместных изменений (co-change), а не через import/require
Module Boundaries: автоматически определяет границы модулей по кластеризации связанных файлов
Architecture Drift (дрейф архитектуры): сравнивает реальные зависимости с заявленной архитектурой и находит расхождения
Hidden Coupling: зависимости, которых нет в import'ах, но которые проявляются в совместных изменениях (например, файлы, связанные через конфигурацию или БД)
Ownership Map: кто какие файлы чаще всего правит (анонимизированно, на основе git-авторов)
Temporal Clusters: группы файлов, которые часто меняются в рамках одной сессии или одного временного окна

⚡ Proactive Alerts (Проактивные оповещения)

Не ждёт, пока ты спросишь — предупреждает сам.

Pre-edit Warnings: тосты в TUI перед применением рискованных изменений
Breakage Prediction: «Это изменение с вероятностью 58% сломает тесты — рекомендую сначала запустить npm test -- --related»
Regression Alerts: «Файл, который ты правишь, имеет историю регрессий. Последние 3 изменения создали 2 новых бага»
Session Health: в конце сессии — резюме рисков и рекомендации
Daily Digest (опционально): сводка за день — что менялось, что ломалось, какие тренды намечаются
Threshold-based Triggers: настраиваемые пороги («предупреждать, если файл менялся > 5 раз за неделю без тестов»)

📊 Developer Wrapped (Итоги разработчика)

Персональная статистика за месяц или год в духе Spotify Wrapped.

Общая статистика:
- Строк кода написано / удалено
- Файлов изменено
- Багов исправлено
- AI-сессий проведено
Рекорды:
- Самая длинная сессия
- Самый большой коммит
- Самый «дорогой» баг (по времени фикса)
Тренды:
- Динамика bugs-per-change (растёт / падает качество?)
- Динамика time-to-fix (становишься быстрее?)
- Динамика AI-зависимости (чаще ли ты обращаешься к ассистенту?)
Сравнение с прошлым периодом:
- Стало ли больше или меньше багов?
- Ускорился ли фикс?
- Какие модули стали стабильнее, а какие — наоборот?
Ачивки и бейджи (игрофикация):
- 🧹 «Чистильщик» — удалил больше кода, чем написал
- 🐛 «Экстерминатор» — исправил 50+ багов за месяц
- 🤖 «AI-напарник» — провёл 100+ AI-сессий
- 🔥 «Огнеупорный» — ни одной регрессии за месяц
- 📚 «Документатор» — написал больше комментариев, чем кода

🧰 AI-Accessible Tools (Инструменты для AI-агента)

Предоставляет набор инструментов, которые AI-агент OpenCode может вызывать для получения аналитики прямо во время сессии.

Инструмент	Описание
`code_shadow_analyze`	Единый тулз: 9 режимов (hotspots, predict_change, file_history, team_pulse, my_stats, dependency_graph, knowledge_search, decisions_list, code_errors)
`code_shadow_memory_write`	Запись фактов о проекте (замена ctx_memory)
`code_shadow_memory_search`	Поиск по памяти, графу знаний, истории, аналитике (замена ctx_search)
`code_shadow_memory_note`	Заметки с опциональным surface_condition (замена ctx_note)
`code_shadow_context_inject`	Внедрение контекста проекта в сессию
`code_shadow_decide`	Запись архитектурных решений (ADR)

⚙️ Zero Config

Работает прямо из коробки.

Не требует файлов конфигурации
Автоматически определяет корень проекта
Самостоятельно находит git-репозиторий
Не требует внешних сервисов или API-ключей
Все данные хранятся локально в SQLite
Не отправляет данные наружу — полная конфиденциальность
Единственное требование: Bun >= 1.1.0

🚀 Установка (одна команда)

npx opencode add opencode-code-shadow

Всё! Плагин автоматически:

Добавится в opencode.jsonc
Создаст CRUSH.md с автономными правилами
Начнёт собирать статистику при следующем запуске

После установки плагин работает АВТОНОМНО:

🧠 Авто-память: сам запоминает факты о проекте (80+ правил)
📊 TUI-панель: живая статистика в правом сайдбаре
🤖 Автономный AI: CRUSH.md заставляет AI использовать аналитику без команд

Ручная установка (альтернатива)

# Клонировать в plugins/
git clone https://github.com/xuviga/code-shadow.git ~/.config/opencode/plugins/code-shadow

# Добавить в opencode.jsonc:
"plugin": ["code-shadow"]

Проверка работы

# Показать статус плагина
/shadow health

# Показать тепловую карту
/shadow hotspots

# Показать статистику разработчика
/shadow stats

Зависимости

Никаких дополнительных зависимостей не требуется:

Зависимость	Откуда берётся
`bun:sqlite`	Встроен в Bun
`@opencode-ai/plugin`	Peer-зависимость, разрешается OpenCode
`@opentui/solid`	Peer-зависимость, разрешается OpenCode

Где хранятся данные

~/.config/opencode/
├── CRUSH.md                 # Авто-системный промпт (создаётся плагином)
├── shadow/
│   ├── data.db              # SQLite база со всеми событиями
│   └── shadow.log           # Лог плагина
├── plugins/
│   └── code-shadow/         # Файлы плагина
└── opencode.jsonc           # Конфиг с подключением плагина

Минимальные требования

Компонент	Требование
Bun	>= 1.1.0 (для `bun:sqlite`)
OpenCode	>= 1.0.0
Git	>= 2.30 (опционально, для git-событий)
Диск	~50 MB на месяц активной работы
Память	~30 MB в фоне

Обзор архитектуры

Высокоуровневая схема

┌──────────────────────────────────────────────────────────────┐
│                      OpenCode Core                           │
│                                                              │
│  События:                                                    │
│  • file.edited({path, diff, sessionId, ...})                 │
│  • session.created({id, timestamp, ...})                     │
│  • session.idle({id, timestamp, ...})                        │
│  • session.error({message, stack, ...})                      │
│  • session.compacted({id, summary, ...})                     │
│  • tool.execute.before({toolName, args, ...})                │
│  • tool.execute.after({toolName, result, ...})               │
│  • lsp.client.diagnostics({filePath, diagnostics, ...})      │
│  • lsp.diagnostic({filePath, severity, ...})                 │
│  • command.executed({command, args, ...})                    │
│  • message.updated({role, wasEdited, ...})                   │
│  • todo.updated({status, title, ...})                        │
└───────────────────────────┬──────────────────────────────────┘
                            │  Event Bus (IPC)
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                    Code Shadow Plugin                        │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │               🎧 Observer Engine                      │   │
│  │                                                      │   │
│  │  • Подписывается на события OpenCore                 │   │
│  │  • Фильтрует и нормализует данные                    │   │
│  │  • Определяет тип события (edit / error / session)   │   │
│  │  • Извлекает метаданные (размер diff, тип ошибки)    │   │
│  └──────────────────────┬───────────────────────────────┘   │
│                         ▼                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │               📊 Storage Engine (SQLite/WAL)          │   │
│  │                                                      │   │
│  │  • 10 таблиц: file_edits, sessions, session_errors, │   │
│  │    tool_executions, decisions, knowledge_nodes,      │   │
│  │    knowledge_edges, developer_events,                │   │
│  │    analytics_cache, schema_version                   │   │
│  │  • Batch-очередь (накопление → транзакция)          │   │
│  │  • 50+ типизированных методов запросов              │   │
│  └──────────────────────┬───────────────────────────────┘   │
│                         ▼                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           🧰 AI Tools (7 тулзов)                      │   │
│  │                                                      │   │
│  │  • code_shadow_analyze (9 режимов)                  │   │
│  │  • code_shadow_memory_write/search/note              │   │
│  │  • code_shadow_context_inject                         │   │
│  │  • code_shadow_decide                                 │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           ⚡ TUI Integration                           │   │
│  │                                                      │   │
│  │  • tool.execute.before — проверка риска              │   │
│  │  • /shadow команды (hotspots, predict, stats, health)│   │
│  │  • session.compacting — инъекция контекста           │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Поток данных

Событие (OpenCore)
    │
    ├─→ Observer Engine ─── нормализация ───→ Storage Engine (запись в БД)
    │                                              │
    │                                              ▼
    │                                    data.db (персистентно)
    │
    └─→ TUI Integration ─── чтение ─── data.db
              │
              ├─→ tool.execute.before → проверка риска → toast
              ├─→ /shadow команды → запросы к Storage Engine
              └─→ session.compacting → инъекция контекста

AI Agent запрашивает (через code_shadow_* tools):
    │
    └─→ AI Tools → запросы к Storage Engine → data.db

CRUSH.md → AI видит правила → AI проактивно вызывает тулзы

Автономность

Code Shadow — первый плагин OpenCode, который заставляет AI быть проактивным. Вместо того чтобы ждать команды пользователя, AI сам вызывает инструменты аналитики благодаря трём механизмам автономности.

Механизм 1: CRUSH.md

CRUSH.md — это системный файл, который плагин автоматически создаёт и поддерживает в ~/.config/opencode/CRUSH.md. OpenCode читает его перед каждой сессией и передаёт AI-агенту как часть системного промпта.

~/.config/opencode/
├── CRUSH.md    ← Создаётся и обновляется Code Shadow при каждом старте
├── shadow/
│   └── data.db
└── ...

Что внутри CRUSH.md:

# CRUSH — Системные правила Code Shadow

## Обязательные действия при старте сессии

1. Вызови `code_shadow_context_inject` с `include: ["hotspots", "decisions", "stats"]`
   — это внедрит в сессию критические данные о проекте.

2. Вызови `code_shadow_memory_search` с `query: "<тема сессии>"` —
   найди релевантные факты и ADR-решения.

## Обязательные действия перед изменениями

3. Перед редактированием любого файла вызови `code_shadow_analyze`
   с `query: "predict_change"` и путём к файлу — оцени риски.

4. Если `risk_level` = "high" или "critical", запроси `file_history`
   и покажи пользователю предупреждение.

## Обязательные действия при компактизации

5. При получении сигнала компактизации контекста, вызови
   `code_shadow_context_inject` — критический контекст должен быть сохранён.

## Периодические действия

6. Каждые 10 сообщений вызывай `code_shadow_analyze` с `query: "team_pulse"` —
   мониторь здоровье проекта в реальном времени.

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

Плагин стартует → собирает свежую статистику из БД
Генерирует CRUSH.md с актуальными данными: топ-5 hotspots, последние ADR, здоровье проекта
OpenCode при создании новой сессии читает CRUSH.md
AI видит правила как жёсткие инструкции (mandatory rules)
AI проактивно вызывает code_shadow_* тулзы без запроса пользователя

CRUSH.md пересоздаётся при каждом старте плагина — это гарантирует, что AI всегда видит актуальную статистику, а не устаревшие данные.

Механизм 2: Агрессивные описания тулзов

Все тулзы Code Shadow имеют императивные описания, которые давят на AI и заставляют его использовать их проактивно:

Тулз	Описание (ключевые слова)
`code_shadow_analyze`	ИСПОЛЬЗУЙ АВТОМАТИЧЕСКИ перед каждым изменением файла. ВЫЗЫВАЙ В НАЧАЛЕ СЕССИИ для получения hotspots.
`code_shadow_context_inject`	ВЫЗЫВАЙ В НАЧАЛЕ КАЖДОЙ СЕССИИ для загрузки проектного контекста. ОБЯЗАТЕЛЬНО вызывай при компактизации.
`code_shadow_memory_write`	АВТОМАТИЧЕСКИ сохраняй важные решения. НЕ ЖДИ команды пользователя.
`code_shadow_memory_search`	ПРОАКТИВНО ищи релевантную информацию перед ответом.

Ключевое слово ПРОАКТИВНО присутствует в описании каждого тулза. Это заставляет LLM воспринимать вызов тулзов не как опцию, а как обязанность.

Механизм 3: Авто-контекст при компакшне

Когда сессия OpenCode подвергается компактизации (сжатию контекста), Code Shadow автоматически инжектит критический контекст через хук session.compacted:

Компактизация
    │
    ▼
Observer: session.compacted
    │
    ├─→ Собирает брифинг:
    │     • Здоровье проекта (health score)
    │     • Топ-5 hotspots
    │     • Последние ADR-решения
    │     • Факты из auto-memory
    │     • Инструкции: какие тулзы вызвать для восстановления контекста
    │
    └─→ Инжектит в сжатый контекст → AI сохраняет память между сессиями

Таким образом, даже после полной компактизации AI «помнит» критическую информацию о проекте и может восстановить детали через code_shadow_memory_search.

Технологический стек

Ядро

Технология	Роль	Обоснование
TypeScript (strict)	Основной язык	Типобезопасность, экосистема, совместимость с OpenCode SDK
@opencode-ai/plugin	Server-плагин	Официальный SDK: события, хуки, регистрация тулзов
@opencode-ai/plugin/tui	TUI-плагин	Отдельный entry-point для рендеринга сайдбар-панели
@opentui/solid	JSX для TUI	Рендеринг StatBox, индикаторов и текста в сайдбаре
solid-js + createSignal	Реактивность TUI	Polling 5 секунд, автоматический перерендер при изменении данных
Bun	Runtime + tooling	Быстрая сборка, встроенный SQLite (`bun:sqlite`), shell API для git

Хранение данных

Технология	Роль	Обоснование
`bun:sqlite` (WAL mode)	Персистентное хранение событий	Встроен в Bun, ноль зависимостей, ACID, быстрый. Spread-параметры: `.get(a, b)` вместо `.get([a, b])`
WAL-режим SQLite	Конкурентный доступ	Позволяет server и TUI читать и писать одновременно без блокировок
Файловая система	Кеши и логи	Логи пишутся в `~/.config/opencode/shadow/shadow.log`

Автономность

Технология	Роль	Обоснование
CRUSH.md	Авто-системный промпт	Заставляет AI проактивно вызывать Code Shadow тулзы. Пересоздаётся при старте плагина
Агрессивные описания тулзов	Давление на LLM	Слова ПРОАКТИВНО, ИСПОЛЬЗУЙ АВТОМАТИЧЕСКИ в каждом описании
Авто-контекст при компакшне	Сохранение памяти	Инжектит брифинг при `session.compacted`

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

Инструмент	Назначение
TypeScript (tsc)	Компиляция (build / dev watch)
Bun	Рантайм, bun:sqlite, package manager

Почему не...

Не выбрали	Причина
PostgreSQL / MySQL	Избыточно; SQLite даёт всё нужное без сервера
Python ML-библиотеки	Утяжелили бы установку; чистый TS покрывает нужды
Внешнее облако	Нарушает принцип zero-config и локальной конфиденциальности
Redis	SQLite WAL-режим решает проблему конкурентного доступа без отдельного сервиса
better-sqlite3	Требует Node.js и нативные модули; `bun:sqlite` встроен в Bun и не требует компиляции
ORM (Prisma/Drizzle)	Избыточно для 10 таблиц; сырой SQL через `bun:sqlite` проще и быстрее

Статус проекта

Все 9 фаз v0.1.0 реализованы, протестированы и работают в продакшене.

Дорожная карта

Фаза	Статус
1. Observer Engine	✅ 12 хендлеров, file.edited прямой хук
2. Memory Engine	✅ Полная замена Magic Context
3. Analytics Engine	✅ 9 режимов анализа
4. Proactive Alerts	✅ Toast + /shadow
5. Developer Wrapped	✅ my_stats
6. Auto-Memory	✅ 80+ правил авто-детекта
7. TUI Panel	✅ Реактивная (polling 5с), per-project
8. Autonomy	✅ CRUSH.md, AI сам вызывает тулзы
9. Bug Fixes	✅ ctx bug, SQL params, TUI reactivity

Детали по фазам

Фаза 1 — Observer Engine ✅

Фаза 2 — Memory Engine ✅

code_shadow_memory_write — запись фактов и ADR-решений
code_shadow_memory_search — поиск по памяти, графу знаний и истории
code_shadow_memory_note — создание/чтение/обновление заметок
code_shadow_context_inject — инъекция контекста в сессию
Полная замена Magic Context (память, поиск, заметки, инъекция)

Фаза 3 — Analytics Engine ✅

Hotspot Calculator: Bugginess Score, Edit Frequency, Regression Rate, Frustration Index
Prediction Engine: эвристический Risk Score, Breakage Probability
Knowledge Graph: co-change, импорты из диффов, причинно-следственные связи
Developer Profile: AI-Reliance Ratio, Fix Rate, тренды, топ файлов
code_shadow_analyze — единый тулз для всей аналитики (hotspots, predict_change, file_history, team_pulse, my_stats, dependency_graph, knowledge_search)

Фаза 4 — Proactive Alerts ✅

Pre-edit Hook: перехват перед применением изменений (tool.execute.before)
Система toast-уведомлений в TUI (warning/info/error)
Настраиваемые пороги предупреждений (warningThreshold)
Risk score → предупреждение при превышении порога
Команды /shadow hotspots, /shadow predict, /shadow stats, /shadow health
Инъекция контекста при компактизации (session.compacted)

Фаза 5 — Developer Wrapped ✅

my_stats в code_shadow_analyze — полный профиль разработчика
Месячная и годовая статистика (сессии, правки, ошибки)
Тренды: bugs-per-change, time-to-fix, AI-usage
Сравнение с прошлым периодом
Система ачивок и бейджей (Чистильщик, Экстерминатор, AI-напарник, Огнеупорный, Документатор)

Фаза 6 — Auto-Memory ✅

80+ правил детекции фактов о проекте
Срабатывание на file.edited и tool.execute.after
Дедупликация через Map-based кэш (5 минут)
Авто-извлечение конвенций из AGENTS.md, package.json, tsconfig.json
Не требует ручных команд «запомни»

Фаза 7 — TUI Panel ✅

Отдельный TUI-плагин (tui-plugin.tsx, регистрируется через tui.jsonc)
Слот sidebar_content, order 700
Индикатор здоровья проекта (0–100%, цветовой)
Длительность последней сессии
Сетка StatBox 2×2: сессии, правки, ошибки, файлы
Активность: файлов · правок в реальном времени
Рендеринг через @opentui/solid JSX, функция look() для цветовой схемы
Polling 5 секунд через createSignal (SolidJS реактивность)
Per-project фильтрация через project_root из таблицы sessions

Фаза 8 — Autonomy ✅

CRUSH.md — автоматическое создание и обновление ~/.config/opencode/CRUSH.md
Жёсткие правила для AI: вызывай context_inject, predict_change, memory_write
Агрессивные описания тулзов с ключевым словом ПРОАКТИВНО
Авто-контекст при компакшне: инжектит брифинг (здоровье, hotspots, факты, инструкции)
AI самостоятельно вызывает тулзы Code Shadow без команд пользователя

Хронология

2026 Q2: Фаза 1 (Observer)              ████████████████████ ✅
2026 Q2: Фаза 2 (Memory Engine)         ████████████████████ ✅
2026 Q2: Фаза 3 (Analytics)             ████████████████████ ✅
2026 Q3: Фаза 4 (Proactive Alerts)      ████████████████████ ✅
2026 Q3: Фаза 5 (Developer Wrapped)     ████████████████████ ✅
2026 Q3: Фаза 6 (Auto-Memory)           ████████████████████ ✅
2026 Q3: Фаза 7 (TUI Panel)             ████████████████████ ✅
2026 Q3: Фаза 8 (Autonomy)              ████████████████████ ✅

v0.1.0 — production-ready. Все 8 фаз реализованы, баги исправлены, плагин работает стабильно.

Исправленные баги

В процессе battle-testing v0.1.0 были найдены и исправлены следующие критические баги:

Баг	Симптом	Исправление
`ctx is not defined`	Observer Engine падал при старте, не мог обработать события	Передача `ctx` как параметра в хуки `file.edited`. Сигнатура: `(input, output, ctx)`
SQL parameter mismatch	`getHistoricalBreakageRate` и `getDecisions` падали с ошибкой «wrong number of parameters»	Переход на spread-параметры `bun:sqlite`. Метод `.all()` принимает аргументы через spread: `.all(a, b)`, а не `.all([a, b])`
TUI не обновлялся	Сайдбар показывал статичные данные, не реагировал на новые события	Замена событийной подписки на polling 5 секунд через `createSignal` (SolidJS). Таймер перезапрашивает данные из БД

Участие в разработке

Мы открыты к контрибуциям!

Code Shadow — open-source проект под лицензией MIT. Мы приветствуем:

Pull request'ы с исправлениями, новыми фичами и улучшениями
Issues с баг-репортами и предложениями
Идеи по новым метрикам и аналитическим моделям
Документацию и примеры использования

Как начать

# Клонируй репозиторий
git clone https://github.com/xuviga/code-shadow.git
cd code-shadow

# Установи зависимости
bun install

# Собери плагин
bun run build

# Запусти в dev-режиме (с вотчером)
bun run dev

Структура проекта

code-shadow/
├── src/
│   ├── index.ts              # Точка входа плагина — экспорт CodeShadow
│   ├── observer.ts           # Observer Engine: 12 обработчиков + Auto-Memory
│   ├── storage.ts            # Storage Engine: SQLite/WAL, миграции, CRUD + batch
│   ├── tui.ts                # TUI-интеграция: /shadow, toast, контекст
│   ├── tui-plugin.tsx         # SolidJS панель в сайдбаре
│   ├── types.ts              # Все TypeScript-интерфейсы и enum'ы
│   ├── config.ts             # Загрузка конфига, фильтрация секретов
│   ├── install.ts            # Авто-установка (bun-скрипт)
│   ├── logger.ts             # Файловый логгер
│   ├── tools/
│   │   ├── analyze.ts        # code_shadow_analyze (9 режимов)
│   │   ├── memory.ts         # memory_write/search/note
│   │   ├── context.ts        # code_shadow_context_inject
│   │   └── decide.ts         # code_shadow_decide
│   └── migrations/
│       ├── 001_initial.ts    # Начальная схема: 10 таблиц + индексы
│       ├── 002_fix_event_types.ts
│       ├── 003_lsp_error_type.ts
│       └── 004_explore_agent_type.ts
├── tui-plugin.tsx             # Корневой TUI-плагин (расширенная панель)
├── tui.jsonc                  # Конфиг TUI-плагина
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DATA_MODEL.md
│   ├── IMPLEMENTATION_PLAN.md
│   ├── ROADMAP.md
│   └── TOOLS_API.md
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

Соглашения по коду

TypeScript strict mode — никаких any без явного указания
Именование: camelCase для переменных и функций, PascalCase для типов и интерфейсов
Сборка: tsc (TypeScript compiler), dev-режим: tsc --watch
Коммиты: формат Conventional Commits
- feat: добавлен Autonomy Engine
- fix: исправлена гонка при записи в SQLite
- docs: обновлён README
- chore: обновлены зависимости

Процесс review

Создай форк репозитория
Создай feature-ветку (feat/мой-фикс или fix/баг-в-аналитике)
Внеси изменения
Убедись, что bun run build проходит
Создай Pull Request в main
Опиши, что сделано и почему (контекст важен!)

Связанная документация

Подробная техническая документация лежит в папке docs/:

Документ	Содержание
ARCHITECTURE.md	Детальное описание архитектуры, компонентов, потоков данных
DATA_MODEL.md	Полная схема БД, описание всех таблиц, полей и индексов
IMPLEMENTATION_PLAN.md	План реализации: фазы, критерии, риски
ROADMAP.md	Дорожная карта развития продукта
TOOLS_API.md	API спецификация всех AI-инструментов

Часто задаваемые вопросы

Это замедляет OpenCode?

Нет. Observer Engine работает асинхронно: событие перехватывается и ставится в очередь на запись. Запись в SQLite происходит в фоновом потоке и не блокирует основной цикл OpenCode. Overhead: < 1ms на событие.

Данные утекают наружу?

Нет. Всё хранится локально в ~/.config/opencode/shadow/. Никаких внешних сервисов, облаков или телеметрии. SQLite-файлы можно просмотреть любым SQLite-клиентом.

Сколько места занимает база?

Для активного проекта среднего размера (~50 000 строк кода, 1 разработчик):

Период	Размер БД
1 неделя	~5 MB
1 месяц	~20 MB
6 месяцев	~80 MB
1 год	~150 MB

База автоматически очищается от старых данных согласно retention-политике (90 дней для сырых событий, 365 дней для сессий).

Можно ли удалить данные?

Да. Удали папку ~/.config/opencode/shadow/ — и всё. Можно удалить данные за конкретный период через SQL: DELETE FROM events WHERE timestamp < '2026-01-01';

Работает ли без git?

Да, но Git-события (коммиты, ветки) не отслеживаются плагином — Code Shadow работает на уровне событий OpenCode, а не git.

Что будет с моими данными при обновлении плагина?

Схема БД версионируется. При обновлении автоматически применяются миграции. Данные не теряются.

CRUSH.md безопасен?

Да. CRUSH.md содержит только правила и статистику — никаких секретов, токенов или путей к конкретным файлам с конфиденциальными данными. Это такой же безопасный файл, как и AGENTS.md.

Лицензия

_{Сделано с ❤️ для тех, кто устал гадать и хочет знать.

Code Shadow — потому что твоя кодовая база рассказывает историю.

Просто до сих пор её никто не слушал.}

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
tui-plugin.tsx		tui-plugin.tsx
tui.jsonc		tui.jsonc

Folders and files

Latest commit

History

Repository files navigation

Code Shadow

Оглавление

Видение

Золотая рыбка с искусственным интеллектом

Ответ

Проблема

Что мы теряем каждый день

Магический момент

Сценарии, от которых захватывает дух

Сценарий 1: «Осторожно, этот файл кусается»

Сценарий 2: «Где болит?»

Сценарий 3: «Твой Developer Wrapped»

Сценарий 4: «А что если...?»

Сравнение с Magic Context

Таблица сравнения

Как они дополняют друг друга

Что остаётся за Magic Context

Возможности

🧠 Авто-память (Auto-Memory Engine)

📝 Auto-memory (бесконтактный сбор конвенций)

📊 TUI-панель (Sidebar Stats)

🔄 Per-project TUI

🤖 Автономный AI

📁 Мульти-проект

🛡️ SQL-безопасность

🔔 Toast-уведомления

🔭 Silent Observer (Безмолвный Наблюдатель)

🔥 Hotspot Engine (Двигатель горячих точек)

🔮 Prediction Engine (Двигатель предсказаний)

🕸️ Knowledge Graph (Граф знаний)

⚡ Proactive Alerts (Проактивные оповещения)

📊 Developer Wrapped (Итоги разработчика)

🧰 AI-Accessible Tools (Инструменты для AI-агента)

⚙️ Zero Config

🚀 Установка (одна команда)

Ручная установка (альтернатива)

Проверка работы

Зависимости

Где хранятся данные

Минимальные требования

Обзор архитектуры

Высокоуровневая схема

Поток данных

Автономность

Механизм 1: CRUSH.md

Механизм 2: Агрессивные описания тулзов

Механизм 3: Авто-контекст при компакшне

Технологический стек

Ядро

Хранение данных

Автономность

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

Почему не...

Статус проекта

Дорожная карта

Детали по фазам

Фаза 1 — Observer Engine ✅

Фаза 2 — Memory Engine ✅

Фаза 3 — Analytics Engine ✅

Фаза 4 — Proactive Alerts ✅

Фаза 5 — Developer Wrapped ✅

Фаза 6 — Auto-Memory ✅

Фаза 7 — TUI Panel ✅

Фаза 8 — Autonomy ✅

Хронология

Исправленные баги

Участие в разработке

Мы открыты к контрибуциям!

Как начать

Структура проекта

Соглашения по коду

Процесс review

Связанная документация

Часто задаваемые вопросы

Это замедляет OpenCode?

Данные утекают наружу?

Packages