https://github.com/lis186/ccxray
X-ray vision for AI agent sessions — a transparent HTTP proxy and dashboard for Claude Code
https://github.com/lis186/ccxray
Last synced: 3 months ago
JSON representation
X-ray vision for AI agent sessions — a transparent HTTP proxy and dashboard for Claude Code
- Host: GitHub
- URL: https://github.com/lis186/ccxray
- Owner: lis186
- License: mit
- Created: 2026-04-03T05:19:06.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T01:32:08.000Z (3 months ago)
- Last Synced: 2026-04-07T08:03:32.576Z (3 months ago)
- Language: JavaScript
- Size: 2.07 MB
- Stars: 83
- Watchers: 1
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.ja.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - ccxray - A transparent HTTP proxy and real-time dashboard that sits between Claude Code and the Anthropic API. Captures every request and response without configuration, presenting them in a Miller-column interface with session grouping, token/cost tracking, and context-window visualization. (Latest Additions)
- awesome-claude-code-cn - ccxray - 一个透明的 HTTP 代理和实时仪表板，位于 Claude Code 和 Anthropic API 之间。无需配置即可捕获每个请求和响应，并以 Miller 列界面呈现，具有会话分组、令牌/成本跟踪和上下文窗口可视化功能。 (最新添加)
README
# ccxray
[English](README.md) | [正體中文](README.zh-TW.md) | **日本語**
AIエージェントセッションのX線ビュー。ゼロ設定のHTTPプロキシで、Claude CodeとAnthropic API間のすべてのAPI呼び出しを記録し、エージェント内部で実際に何が起きているかを確認できるリアルタイムダッシュボードを提供します。
## なぜ必要か
Claude Codeはブラックボックスです。以下が見えません：
- どんなシステムプロンプトを送信しているか（バージョン間の変更も含む）
- 各ツール呼び出しのコスト
- なぜ30秒も思考しているのか
- 200Kトークンのコンテキストウィンドウを何が消費しているのか
ccxrayはそれをガラス箱に変えます。
## クイックスタート
```bash
npx ccxray claude
```
これだけです。プロキシが起動し、Claude Codeがプロキシ経由で接続し、ダッシュボードが自動的にブラウザで開きます。複数のターミナルで実行すると、自動的に一つのダッシュボードを共有します。
### その他の実行方法
```bash
ccxray # プロキシ + ダッシュボードのみ
ccxray claude --continue # すべてのclaude引数がそのまま渡される
ccxray --port 8080 claude # カスタムポート（独立モード、hub共有なし）
ccxray claude --no-browser # ブラウザの自動オープンをスキップ
ccxray status # hubの情報と接続中のクライアントを表示
ANTHROPIC_BASE_URL=http://localhost:5577 claude # 手動設定（既存セッション）
```
### マルチプロジェクト
複数のターミナルで `ccxray claude` を実行すると、自動的に単一のプロキシとダッシュボードを共有します。設定は不要です。
```bash
# Terminal 1
cd ~/project-a && ccxray claude # hubを起動 + claude
# Terminal 2
cd ~/project-b && ccxray claude # 既存のhubに接続
# 両プロジェクトが http://localhost:5577 のダッシュボードに表示
```
Hubプロセスがクラッシュした場合、接続中のクライアントは数秒以内に自動的に復旧します。
```bash
$ ccxray status
Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.1.0)
Connected clients (2):
[1] pid 23456 — ~/dev/project-a
[2] pid 34567 — ~/dev/project-b
```
`--port` を使用すると独立モードで実行できます。
## 機能
### タイムライン
エージェントの思考をリアルタイムで観察。各ターンを思考ブロック（所要時間付き）、ツール呼び出しのインラインプレビュー、アシスタント応答に分解します。
### 使用量とコスト
実際の支出を把握。セッションヒートマップ、消費レート、ROI計算 — トークンの行き先を正確に把握できます。
### システムプロンプト追跡
バージョンの自動検出とdiffビューア。すべてのエージェントタイプ — メインエージェント、サブエージェント（Explore、Web Searchなど）— のシステムプロンプトを閲覧し、更新ごとの変更点を正確に把握できます。
### その他
- **セッション検出** — Claude Codeセッションごとに自動グループ化。プロジェクト/作業ディレクトリの抽出付き
- **トークン会計** — ターンごとの内訳：input/output/cache-read/cache-createトークン、USD単位のコスト、コンテキストウィンドウ使用率バー
## 仕組み
```
Claude Code ──► ccxray (:5577) ──► api.anthropic.com（または ANTHROPIC_BASE_URL）
│
▼
~/.ccxray/logs/ (JSON)
│
▼
ダッシュボード（同じポート）
```
ccxrayは透過型HTTPプロキシです。リクエストをそのままAnthropicに転送し、リクエストとレスポンスの両方をJSONファイルとして記録し、同じポートでWebダッシュボードを提供します。APIキーは不要です — Claude Codeが送信する内容をそのまま通過させます。
## 設定
### CLIフラグ
| フラグ | 説明 |
|---|---|
| `--port ` | プロキシ + ダッシュボードのポート（デフォルト: 5577）。hub共有を無効化 |
| `--no-browser` | ダッシュボードをブラウザで自動オープンしない |
### 環境変数
| 変数 | デフォルト | 説明 |
|---|---|---|
| `PROXY_PORT` | `5577` | プロキシ + ダッシュボードのポート（`--port`で上書き） |
| `BROWSER` | — | `none`に設定すると自動オープンを無効化 |
| `AUTH_TOKEN` | _（なし）_ | アクセス制御用APIキー（未設定時は無効） |
| `CCXRAY_HOME` | `~/.ccxray` | hubロックファイル、ログ、hub.logの基本ディレクトリ |
| `CCXRAY_MAX_ENTRIES` | `5000` | メモリ上の最大エントリ数（古いものから削除。ディスクログには影響なし） |
| `ANTHROPIC_BASE_URL` | — | カスタム上流Anthropicエンドポイント（企業ゲートウェイなど）。ccxrayは起動時にこの値を読み取り、`api.anthropic.com`の代わりにそこへ転送します。`ANTHROPIC_TEST_*`が設定されている場合はそちらが優先されます。 |
ログは`~/.ccxray/logs/`に`{timestamp}_req.json`と`{timestamp}_res.json`として保存されます。v1.0からアップグレードする場合、`./logs/`のログは初回起動時に自動的に移行されます。
## Docker
```bash
docker build -t ccxray .
docker run -p 5577:5577 ccxray
```
## 要件
- Node.js 18+
## 作者の他のプロジェクト
- [SourceAtlas](https://sourceatlas.io/) — あらゆるコードベースへのマップ
- [AskRoundtable](https://github.com/AskRoundtable/expert-skills) — AIをMunger、Feynman、Paul Grahamのように思考させる
- Xで [@lis186](https://x.com/lis186) をフォローして最新情報をチェック
## ライセンス
MIT