AgentTrace — локальная аналитика сессий AI-кодинг-агентов

AgentTrace — локальный TUI и CLI для аудита работы AI-кодинг-агентов. Утилита на Rust читает журналы сессий, которые агенты уже сохраняют на компьютере, и сводит их в единую картину: сколько потрачено токенов и времени, какие запуски оказались медленными, где были ошибки, повторные попытки и признаки регрессии. Один бинарник работает без размещённого бэкенда, поэтому промпты, код и логи не нужно отправлять в облако. Проект распространяется по лицензии MIT.

Какую проблему решает AgentTrace

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

AgentTrace превращает отдельные журналы в отчёт для регулярного анализа. С его помощью можно:

• сравнивать исторические сессии по источнику агента, модели, входным, выходным и кэшированным токенам, оценке стоимости и реальному времени;
• находить зависшие запуски, длинные паузы, циклы повторных попыток, медленные вызовы инструментов и большие параметры;
• ранжировать сессии по стоимости, длительности, числу ходов, здоровью, сбоям, аномалиям, модели, источнику или текстовому запросу;
• сравнивать запуск с локальным baseline, если он предоставлен, и изучать временную линию инцидента;
• видеть честный уровень полноты данных вместо предположения, что журнал каждого агента содержит все необходимые события.

Главный принцип — локальность. AgentTrace анализирует уже существующие локальные данные и не требует переносить рабочую переписку во внешний сервис.

Поддерживаемые источники

Один из главных аргументов в пользу AgentTrace — широкий набор парсеров. По README проекта, инструмент читает журналы и выгрузки следующих систем:

• Claude Code;
• Codex CLI;
• Gemini CLI и Qwen Code;
• Cline, Aider и Cursor;
• Hermes Agent, OpenCode, OpenClaw, Pi, Oh My Pi и Kimi CLI;
• логи в стиле Copilot;
• общие файлы JSON и JSONL с трассами.

Это полезно, когда в одной рабочей среде используются разные агенты. Вместо набора отдельных журналов и несовместимых утилит появляется общий слой анализа. При этом AgentTrace различает подробность каждой сессии: для неё может быть доступно детальное событийное представление Detailed, только агрегаты Aggregate или ограниченные данные Limited. Неполный журнал не выдаётся за полную трассировку.

Установка

Для macOS и Linux доступна установка через Homebrew:

brew install luoyuctl/tap/agenttrace

Универсальный пакет для macOS, Linux и Windows требует Node.js 18 или новее:

npm install -g @zack78/agenttrace

В Windows также есть WinGet:

winget install --id Luoyuctl.AgentTrace --exact

Можно установить последний релиз вручную:

curl -fsSL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | sh

Для разработчиков доступна сборка из исходников через Cargo:

cargo install --git https://github.com/luoyuctl/agenttrace agenttrace

Установленную версию можно проверить командой:

agenttrace --version

Пакеты появляются после публикации соответствующих релизов, поэтому набор доступных способов установки зависит от состояния релизов проекта.

Первый запуск

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

agenttrace

В TUI доступны обзор, список критичных сессий, детали конкретного запуска и диагностика. Тот же бинарник поддерживает CLI-отчёты. Например:

agenttrace --sessions
agenttrace --overview

Флаги удобны для автоматизации и быстрого получения текста вместо интерактивного просмотра. При этом отчёты не ограничиваются таблицей в терминале: обзор можно подготовить в JSON, Markdown или автономном HTML.

Аудит стоимости и рекомендации

Команда --audit проверяет исходные компоненты токенов, нормализованные цены и уверенность в применении pricing fallback:

agenttrace --audit --range 30d -f json

Для локальных названий моделей и нестандартных цен можно передать отдельный файл через AGENTTRACE_PRICING_FILE. Он поддерживает псевдонимы и цены за миллион токенов:

{
  "aliases": {
    "provider/raw-model": "my-model"
  },
  "prices": {
    "my-model": {
      "input": 1,
      "output": 2,
      "cw": 0,
      "cr": 0
    }
  }
}

Команда --recommend ранжирует действия по серьёзности проблемы и ожидаемому влиянию:

agenttrace --recommend --range 30d -f json

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

Отчёты по управлению агентами

Помимо расходов, AgentTrace собирает несколько специализированных отчётов. Для наблюдаемых вызовов MCP используется команда:

agenttrace --mcp-governance --range 30d -f json

Она показывает фактически зафиксированные вызовы MCP. Покрытие загруженных серверов остаётся недоступным, если исходный журнал не содержит таких данных: инструмент не дополняет факты догадками.

Тренды работы с контекстом и файлами выводятся так:

agenttrace --context-trends --range 30d -f json

Отслеживаются повторные чтения, работа с кэшем, шаблоны чтения и записи, а также поведение контекста между сессиями. Это помогает заметить не отдельный медленный запуск, а повторяющийся архитектурный или рабочий паттерн.

Для эвристической корреляции с локальным Git доступна команда:

agenttrace --delivery-evidence --range 30d -f json

Она сопоставляет временные метки локальных коммитов с сессиями в режиме только для чтения. Результат не доказывает, что конкретный коммит попал в main, и сам проект обозначает доставку как эвристику.

Диагностика медленных запусков

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

Содержимое промптов, ответов, результатов и аргументов инструментов в шаги не записывается. Это не полноценный просмотрщик всей переписки, а диагностический слой с минимально необходимыми данными. Пользователь видит, где расходовалось время, не превращая журнал шагов в ещё одну копию чувствительного контекста.

Как читать отчёты

Обзор включает область данных и уровень доверия к ней: покрытие каждого источника, пропущенные при разборе записи, найденные кэши, неизвестные модели и случаи применения pricing fallback. Вместе с оценкой стоимости отчёт показывает рекомендации, наблюдаемую активность MCP, тренды контекста и сигналы работы с Git.

Такая прозрачность особенно полезна для CI и командного анализа. JSON удобен для автоматических проверок, Markdown — для чтения в pull request или артефакте сборки, автономный HTML — для архива или локального просмотра. При этом чувствительные данные остаются локальными.

Документация и связанные проекты

Документация AgentTrace разделена на отдельные руководства. Для работы с проектом полезны индекс документации, интеграция с CI, governance-отчёты, импорт Cursor и руководство для парсеров.

В исходном проекте также даны ссылки на репозитории Homebrew tap, каталог пакетов WinGet, awesome-mac, antigravity-awesome-skills и awesome-claude-skills.

AgentTrace не пытается заменить журналы самих агентов или официальную биллинговую систему провайдера. Его роль практичнее: локально собрать уже доступные данные, честно показать их полноту, выделить дорогие и медленные запуски и дать основание для следующего шага. Если команда регулярно работает с несколькими AI-агентами, такой слой наблюдаемости закрывает важный пробел между финальным ответом и реальной стоимостью выполненной задачи.