Как заглянуть под капот ИИ-агентам с помощью claude-tap
Когда вы запускаете Claude Code или Cursor, кажется, что происходит магия: агент сам сканирует файлы, пишет тесты и исправляет баги. Но за этим фасадом скрывается бесконечный поток JSON-запросов к API. Иногда агент начинает «тупить», зацикливаться или выдавать странные ошибки, и в такие моменты хочется просто увидеть, что именно он отправляет в Anthropic или OpenAI.
Обычно для этого приходится лезть в логи или пытаться перехватить трафик через сложные прокси. Проект claude-tap решает эту проблему элегантно. Это локальный прокси и вьюер трейсов, который специально заточен под работу с AI-агентами.
Зачем это нужно на практике
Главная беда CLI-агентов — непрозрачность. Вы видите красивый прогресс-бар в терминале, но не знаете, какой системный промпт сейчас активен, сколько токенов ушло на контекст и как выглядят определения инструментов (tools), которые агент использует для доступа к вашей файловой системе.
claude-tap работает как «черный ящик» для самолета. Он записывает каждый шаг взаимодействия и упаковывает это в удобный интерфейс. Это помогает, когда нужно:
- Понять, почему агент не видит очевидную ошибку в коде (возможно, она просто не влезла в контекстное окно).
- Отладить собственные инструменты или интеграции.
- Сравнить, как меняется поведение модели при смене системного промпта.
- Сохранить историю работы агента для отчета или архива.
Что умеет инструмент
Проект поддерживает внушительный список клиентов: от официального Claude Code до Cursor CLI, Gemini CLI и даже Kimi.
Просмотр контекста в реальном времени
По умолчанию claude-tap запускает live-вьюер. Вы работаете в терминале, а в браузере открывается вкладка, где в реальном времени появляются карточки запросов. Там видно всё: системные инструкции, историю переписки, схемы вызова функций и ответы модели.
Структурные диффы
Это, пожалуй, самая полезная фича. Инструмент умеет сравнивать соседние запросы. Если агент сделал пять итераций подряд, вы можете нажать одну кнопку и увидеть, что именно изменилось в промпте на шестом шаге. Это избавляет от необходимости вручную сравнивать огромные куски JSON.
Локальность и приватность
Весь трафик остается на вашей машине. Инструмент не отправляет данные на сторонние серверы для визуализации. Более того, он автоматически вырезает заголовки авторизации (API-ключи) перед записью в лог, так что трейсами можно делиться с коллегами, не боясь утечки токенов.
Как это устроено технически
Под капотом у claude-tap — Python и система проксирования. В зависимости от клиента он использует либо реверс-прокси (подменяет BASE_URL), либо форвард-прокси (через переменные окружения HTTPS_PROXY).
Интересно реализована работа с потоковыми ответами (SSE). Инструмент перехватывает стриминг, реконструирует финальный текст и считает токены прямо на лету. Для пользователя это выглядит как мгновенно готовый результат, хотя на самом деле прокси проделал немало работы по сборке чанков данных.
Как начать пользоваться
Установка максимально простая, особенно если у вас есть uv:
uv tool install claude-tap
Или через обычный pip:
pip install claude-tap
Чтобы запустить, например, Claude Code через прокси, достаточно написать:
claude-tap
Команда сама подхватит нужный бинарник и прокинет все аргументы. Если вы используете специфичные модели или хотите подключить DeepSeek через совместимый API, это тоже настраивается через переменные окружения. Например, для работы Claude Code с DeepSeek API:
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
claude-tap -- --permission-mode bypassPermissions
Кому это пригодится
В первую очередь тем, кто активно внедряет AI-агентов в свой рабочий процесс и хочет контролировать расходы токенов. Трейсы помогают увидеть, где агент «жрет» лишнее, отправляя в контекст ненужные файлы.
Также это маст-хэв для разработчиков, которые пишут свои обертки над LLM или создают кастомные инструменты для агентов. Видеть реальный JSON, который приходит от модели, гораздо эффективнее, чем пытаться угадать причину ошибки по косвенным признакам в терминале.
Проект активно развивается, и хотя документация местами лаконична, основной функционал работает стабильно. Если вы устали от «магии» ИИ и хотите вернуть контроль над процессом разработки — попробуйте claude-tap. Это один из тех инструментов, который после первого использования прочно оседает в папке со скриптами.
