Getting Started

CtxCtl makes files and command output smaller before they reach the model. Your agent reads only the symbol it needs — via tree-sitter AST location resolved back to an original-source slice — and compresses command output into key lines plus a head/tail summary.

Install

Cargo

cargo install ctxctl

npm

npm install -g ctxctl
# or
bun add -g ctxctl

Binaries

Download the prebuilt binary for your platform from the GitHub releases page — releases also ship .deb, .rpm, .apk, and Arch packages.

Quick start

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

No whole-file dumps. No raw log walls. Deterministic output — identical runs stay cache-hot.

Configuration

CtxCtl is stateless: config files store only default-behavior preferences. Lookup precedence, high to low:

1. --config <path> (explicit)
2. .ctxctl/config.toml (project-level, discovered walking up like .git)
3. $XDG_CONFIG_HOME/ctxctl/config.toml (XDG global)
4. Built-in defaults

Teach your agent

Load the ctxctl-core skill so your coding agent reaches for symbol slices and compressed output on its own:

# 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 use the skill once without installing it:

npx skills use Xuepoo/ctxctl-skills --skill ctxctl-core

The skill gives agents first-class awareness of the outline / symbol / read / deps / exec workflow — fewer tokens per task, cache-friendly runs.

MCP-native agents can skip the skill entirely and call ctxctl as native tools; see MCP Adapter.