Your coding agent pays for every byte of context. ctxctl makes files and command output smaller before they reach the model.
Agents dump whole files and raw build logs into context, then burn tokens re-reading what they already saw. ctxctl is a stateless context layer with a CLI-first design (optional ctxctl mcp adapter): an agent reads only the symbol it needs — via tree-sitter AST location → original-source slice — and compresses command output with byte-stable results that hit provider prompt caching.
ctxctl outline src/server.rs# src/server.rs [12 symbols, ~2.1 KB -> ~410 tokens, saved ~80%]
fn handle_request L:42-58 pub async fn handle_request(&self, id: u64)
struct Config L:60-71 pub struct Config {
fn validate L:73-88 fn validate(cfg: &Config) -> Result<(), Error> {
ctxctl symbol src/server.rs --name handle_request --compact# handle_request src/server.rs:42-58 (58 tokens, saved ~85%)
pub async fn handle_request(&self, id: u64) -> Result<String, Error> { ... }
ctxctl exec "cargo build" --keep "Finished"... [214 lines omitted]
Finished `dev` profile [unoptimized + debuginfo] target(s) in 4.82s
exit code 0 · Saved ~70% (1,240 -> 372 tokens)
No whole-file dumps. No raw log walls. Deterministic output — identical runs stay cache-hot.
English | 简体中文
From a scripted-agent benchmark (pi driving deepseek-v4-flash on OpenRouter across four real tasks: three source files of 51–96 KB plus a 1,914-line build log; single run per arm):
| Measurement | Result |
|---|---|
Native ctxctl mcp tools vs built-in read/bash — session cost |
−33% |
| Same benchmark — uncached (fully billed) input tokens | −31% |
Log-analysis task via ctxctl exec |
−84% cost |
| Exploring a 96 KB file through outline/symbol slices | −86% uncached input |
| File outlines vs whole-file reads | 91–95% smaller |
Savings scale inversely with provider prefix-caching quality: models whose providers cache aggressively still cut uncached input, while a weak-caching model (solar-pro4) saved 47% session cost. Exec compression is the least conditional win (~80%+ everywhere).
cargo install ctxctlnpm install -g ctxctl
# or
bun add -g ctxctlDownload the prebuilt binary for your platform from the releases page (also ships .deb, .rpm, .apk, and Arch packages).
ctxctl outline src/main.rs # symbol map + savings
ctxctl symbol src/main.rs --name run --compact # one symbol, body folded
ctxctl read src/main.rs --lines 40-80 # raw line slices
ctxctl deps src/main.rs # import graph (local/external)
ctxctl exec "cargo test" --keep "FAILED|passed" # run + compress output
ctxctl outline src/main.rs --json # machine contract| Command | Purpose |
|---|---|
outline <file> |
Symbol outline with token-savings stats |
symbol <file> --name <s> |
Original-source slice of one symbol (--compact, --signature, --lines) |
read <file> --lines 100-150,200-210 |
Raw line-range slices (no AST) |
deps <file> |
Import/module dependency graph (local / external / ignored) |
exec <cmd> [--keep <pat>] |
Run a command, compress its output |
mcp |
Serve all commands as MCP tools over stdio (optional adapter) |
Global flags: --json (machine contract), --config <path>, --no-saved. Config: --config > .ctxctl/config.toml (walk-up) > XDG > defaults.
Load the ctxctl skill to teach your coding agent to read files by symbol slice and compress command output instead of dumping raw context:
# List available skills
npx skills add Xuepoo/ctxctl-skills --list
# Install the core skill for all detected agents
npx skills add Xuepoo/ctxctl-skills --all
# Or install for specific agents
npx skills add Xuepoo/ctxctl-skills \
--skill ctxctl-core \
--agent codex \
--agent claude-code \
--agent cursor \
--agent github-copilotUse the skill once without installing it:
npx skills use Xuepoo/ctxctl-skills --skill ctxctl-coreThe skill gives agents first-class awareness of the outline / symbol / read / deps / exec workflow — fewer tokens per task, cache-friendly runs. The CLI supports GitHub shorthand, full URLs, and local paths; see https://github.com/vercel-labs/skills.
- Website & guides: ctxctl.xuepoo.xyz
- Agent skill source: ctxctl-skills
- CLI-first, stateless — every invocation is self-contained: no state file, no background process. An optional
ctxctl mcpadapter serves the same commands as MCP tools for MCP-native agents. - Byte-stable output — no timestamps, no counters; identical inputs produce identical bytes so provider prompt caches stay hot.
- Slices, not summaries — symbols come from the original source by byte range; nothing is reworded.
- Minimal deps — 14 language backends via tree-sitter, zero network dependencies.
Rust edition 2024 workspace: ctx-symbol (symbol engine), ctx-exec (output compression), ctxctl (thin clap shell).
just check # fmt + clippy + check + test
cargo test # 172 testsMIT