内容
# ctx
**LLM に渡す文脈を、選り分ける。**
`ctx` は、リポジトリから AI に渡すコンテキストを作るための Rust 製 CLI / TUI / MCP server です。
ファイル構造、トークン数、Git 状態、シンボル、関連度を見ながら、必要なファイルだけを束ね、何を省いたかも記録します。
```bash
ctx --tokens --git --symbols .
ctx where "session login"
ctx where "session login" --format json | ctx pack --from-where --budget 30000 --out context.md
```
`tree` は構造を見る道具です。`rg` は文字列を探す道具です。
`ctx` は、LLM に渡す前に **select → order → budget → record** を行うための道具です。
## 功能概述
- **可视化**: ディレクトリ構造にトークン数、Git 状態、ファイル役割、シンボルを重ねて表示します。
- **查找**: 自然語クエリから関連ファイルをランキングします。
- **打包**: 目的と予算に合わせて AI-ready な context bundle を生成します。
- **验证**: `ctx pack` の contract manifest を使い、LLM 応答が渡した根拠に沿っているか検証します。
- **回放**: pack snapshot を保存し、後から差分や再現性を確認します。
- **浏览 / TUI / MCP**: Web UI、端末 UI、Claude Code / Cursor などからの MCP tool 呼び出しに対応します。
## 安装
現時点ではソースからビルドします。通常のビルドには Rust toolchain が必要です。
Web frontend を再ビルドする場合だけ Node.js / pnpm が必要です。
```bash
git clone https://github.com/simota/ctx
cd ctx
make build
./bin/ctx --help
```
ユーザー環境へ入れる場合:
```bash
make install
ctx --help
```
`make install` は `cargo install --path crates/ctx-cli --locked --force` を実行し、`ctx` を Cargo の bin ディレクトリへ配置します。
## 快速入门
### 1. リポジトリを俯瞰する
```bash
ctx --tokens --git --symbols .
ctx --budget 50000 .
ctx --plan claude-pro --tokens .
```
`--plain` を付けると screen reader 向けの罫線なし出力になります。
`--json` を付けると構造化出力として処理できます。
### 2. 関連ファイルを探す
```bash
ctx where "authentication session"
ctx where "Pack" --format json --limit 5
ctx where --all "Auth Handler"
ctx where --regex 'http\.Handler' "server"
ctx where "ABテスト" --literal "ABテスト"
```
`ctx where` は、basename / path / symbol / content のシグナルを組み合わせてファイルをランキングします。
`--literal` を付けると、クエリの小文字化や token 分割を使わず、大文字小文字を区別した exact パターンで候補を絞り込めます。
逐語検索を最速で行いたい場合は `rg`、構文パターン検索をしたい場合は `ast-grep` が適しています。
### 3. AI に渡す bundle を作る
```bash
ctx pack . --goal "debug session expiration" --budget 30000 --out context.md
ctx pack . --changed --budget 20000
ctx pack . --diff HEAD~1..HEAD --layout unified
ctx where "session login" --format json | ctx pack --from-where --budget 30000 --out context.md
```
`ctx pack` は既定で末尾に `ctx:contract` manifest を埋め込みます。
不要な場合は `--no-contract` を指定します。
### 4. 小さく読む
```bash
ctx focus Pack --hops 1 --budget 8000
ctx skim crates/ctx-cli/src/main.rs --budget 800
ctx map --depth 2 --by tokens
ctx map --depth 2 --by churn
ctx digest --since 7d
ctx noise --top 20
```
`focus` はシンボルやファイルを起点に周辺文脈を集めます。
`skim` は単一ファイルを token budget 内に縮約します。
`noise` は pack に入れるべきでない低信号ファイル候補を出します。
## 命令概述
| 命令 | 用途 |
|---|---|
| `ctx [path]` | 显示仓库树 |
| `ctx pack` | 生成 AI-ready context bundle |
| `ctx where` | 搜索相关文件 |
| `ctx focus` | 生成以符号为起点的 mini-pack |
| `ctx skim` | 将单个文件缩减到预算内 |
| `ctx map` | 显示 token / file / symbol / churn 的热图 |
| `ctx digest` | 总结最近的变更 |
| `ctx replay` | 管理 pack 快照 |
| `ctx noise` | 检测 context noise 候选 |
| `ctx echo` | 评估 bundle 是否能回答问题 |
| `ctx contract verify` | 验证 pack contract 和响应 |
| `ctx audit verify` | 验证审计日志 |
| `ctx deps` / `ctx impact` | 显示依赖关系和影响范围 |
| `ctx roots` | 管理已知仓库根目录 |
| `ctx onboarding` | 生成代码库 onboarding 的阅读顺序 |
| `ctx browse` | 启动本地 Web UI |
| `ctx tui` | 启动终端 UI |
| `ctx mcp serve` | 启动 MCP server |
| `ctx doctor` | 诊断执行环境 |
## MCP
`ctx mcp serve` 是 JSON-RPC stdio 的 MCP server，可以从 Claude Code 或 Cursor 等 MCP client 调用。
```json
{
"mcpServers": {
"ctx": {
"command": "ctx",
"args": ["mcp", "serve", "--root", "/path/to/repo"]
}
}
}
```
## 浏览器界面
```bash
ctx browse .
ctx browse . --no-open --port 8765 --bind 127.0.0.1
```
`ctx browse` 启动本地 Axum web server，默认为浏览器显示。
如果要禁止浏览器启动，可以使用 `--no-open`。
## 配置
示例配置文件位于 [`ctx.toml.example`](ctx.toml.example)。
```bash
cp ctx.toml.example ctx.toml
```
主要配置区域：
- `[ignore]`：`.gitignore` 中附加的路径模式
- `[ai]`：tokenizer 和默认 token 预算
- `[security]`：secret scan / redact / 严格离线
- `[pack]`：pack 预设
- `[hooks]`：pre/post pack hook
- `[audit]`：audit log 和查询掩码
## 安全模型
`ctx` 是一个本地优先的工具。
通常的 tree / where / pack 操作仅读取本地文件，不涉及外部传输。
为了安全，`ctx` 具有以下行为：
- 默认避免 `.env*`, `*.pem`, `*.key`, `credentials.json`, `.netrc`, `.aws/` 等包含秘密的文件。
- 如果启用 secret scan / redact，则在 pack 或 MCP 响应中隐藏检测到的秘密候选。
- MCP server 使用 root jail，默认拒绝访问根目录之外的文件。
- audit log 是可选的，可以根据需要选择原始 / 哈希 / 掩码的查询处理。
## 项目结构
```text
crates/
ctx-cli/ 主要 CLI 二进制文件
ctx-pack/ context bundle 生成
ctx-where/ 相关性搜索
ctx-symbols/ tree-sitter 符号提取
ctx-tokens/ token 估计
ctx-web/ Axum web server 和嵌入式 SPA
ctx-mcp/ MCP server
ctx-tui/ 终端 UI
ctx-replay/ pack 快照支持
ctx-contract/ pack-as-contract 验证
ctx-*/ 支持库
web/ Svelte / Vite 前端源代码
crates/ctx-web/dist/ 嵌入式前端资产
docs/ 静态站点和 ADRs
ci/ CI 和 parity 助手
loops/ 循环自动化笔记
```
主要二进制文件是 `crates/ctx-cli`。
仓库故意组织成 Rust crates 而不是单个整体，以便独立测试和演化各个功能。
## 开发
```bash
make build # 构建调试二进制文件并复制到 ./bin/ctx
make release # 构建优化二进制文件并复制到 ./bin/ctx
make check # cargo check for CLI crate
make test # Rust 测试套件，包括 Go parity oracle 门控
make lint # cargo clippy
make fmt # cargo fmt
make web # 重建 web 前端到 crates/ctx-web/dist
make dev # 运行 Vite 开发服务器
make run ARGS="pack ."
```
## 授权
MIT.
