CTX is a local context runtime for OpenCode and AI coding agents. It keeps repository knowledge, reusable rules, shell output, diffs, and file rereads compact before they ever bloat the model context.
See It In Action
| Install + Bootstrap | Planning + Packing | Read Cache + Dashboard |
|---|---|---|
 |  |  |
Install ctx, run ctx init, ctx index, ctx opencode install, then open OpenCode. | Build a plan, pack the smallest useful context, and compare broad vs packed token cost. | Re-read files through digest mode and watch live savings in the right sidebar. |
Contents
- What CTX Is
- Why It Exists
- Install CTX
- OpenCode-First Usage
- What Works Today
- Graph Memory
- CTX Dashboard
- Proof From The Demo Fixture
- Demo And Screenshots
- Security
- Documentation
- Repository Layout
What CTX Is
CTX is a local runtime layer for OpenCode. It indexes the repository, stores reusable guidance as graph memory, exposes local MCP tools, generates OpenCode slash commands, and keeps local telemetry about token savings, cache reuse, and compact context packs.
CTX is not another agent launcher.
- OpenCode keeps the selected model, provider, and normal workflow.
- CTX sits underneath as the context layer.
- The product surface is the OpenCode-native
/ctx-*experience, not wrapper-first shell workflows.
Why It Exists
Coding agents usually waste tokens on things that are useful once but expensive forever.
Install CTX
Install CTX with the channel that fits your workflow best:
cargo install ctx-cli- one-line installer script
- GitHub Release archives
npm i -g @alegau/ctx-binbrew tap Alegau03/ctx && brew install ctx
Update paths:
ctx updatectx update --checkcargo install ctx-cli --force- rerun the installer script
npm update -g @alegau/ctx-binbrew upgrade ctx
Cargo
cargo install ctx-cli
One-Line Installer
curl -fsSL https://raw.githubusercontent.com/Alegau03/CTX/main/scripts/install.sh | sh
npm
npm i -g @alegau/ctx-bin
Homebrew
brew tap Alegau03/ctx
brew install ctx
Source Install
git clone https://github.com/Alegau03/CTX.git
cd CTX
cargo install --locked --path crates/ctx-cli
Verify:
ctx help
ctx doctor
ctx update --check
Native update command:
ctx update
How ctx update behaves:
- installer-based installs: reruns the official installer path
- Cargo installs: prints
cargo install ctx-cli --force - npm installs: prints
npm update -g @alegau/ctx-bin - Homebrew installs: prints
brew upgrade ctx - ambiguous installs: prints all supported update commands without guessing
GitHub Release Archive
Download the latest assets from GitHub Releases, then run:
shasum -a 256 -c SHA256SUMS
tar -xzf ctx-0.2.5-aarch64-apple-darwin.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 ctx-0.2.5-aarch64-apple-darwin/ctx "$HOME/.local/bin/ctx"
export PATH="$HOME/.local/bin:$PATH"
If you prefer a system-wide install:
sudo install -m 0755 ctx-0.2.5-aarch64-apple-darwin/ctx /usr/local/bin/ctx
For the full install matrix, release verification notes, native update behavior, and distribution details, see docs/install.md.
OpenCode-First Usage
Once ctx is installed, enable it in any project:
cd /path/to/your/project
ctx init
ctx index
ctx opencode install
opencode
If you want the leanest possible OpenCode surface first:
ctx opencode install --profile core
Profile summary:
full(default): full CTX slash-command surface plus the live right-sidebarCTX Dashboardcore: lean daily workflow with/ctx,/ctx-doctor,/ctx-plan,/ctx-retrieve,/ctx-pack,/ctx-run,/ctx-prune-logs,/ctx-stats, and/ctx-gain
Inside OpenCode, start with:
/ctx
From there, the main workflow is:
/ctx-doctor
/ctx-memory-bootstrap
/ctx-plan <task>
/ctx-retrieve <query>
/ctx-read <file> [mode]
/ctx-pack <task>
/ctx-compare <task>
/ctx-run <shell command>
/ctx-gain
/ctx-dashboard
Toolbooks and reusable lessons are also first-class:
/ctx-toolbook-import <name> <file>
/ctx-toolbook-search <name> "<query>"
/ctx-toolbook-pack <name> "<task>"
/ctx-learn <key> "<body>"
For full usage, expected outputs, and CLI equivalents, see guide.md and docs/commands.md.
What Works Today
Graph Memory
Graph Memory is CTX's structured replacement for repeatedly loading whole instruction markdown files. It keeps directives local, queryable, editable, and exportable when markdown compatibility is still needed.
Instead of this:
- one giant
AGENTS.md - every host turn re-reading it
- unclear relevance to the active task
CTX lets you do this:
- import rules once with
/ctx-memory-bootstrap - retrieve only task-relevant directives with
/ctx-memory-search - fold those directives into
/ctx-planand/ctx-pack - store new lessons with
/ctx-learn
CTX Dashboard
When CTX is installed with the default full profile, OpenCode gets a live CTX Dashboard in the right sidebar.
The sidebar is meant to be a lightweight control tower for the current repo, not another verbose chat response. It auto-refreshes local runtime metrics such as:
- total estimated tokens saved
- average tokens saved per run
- average and latest reduction percentages
- read-cache hit rate
- index-cache reuse rate
- top current win
- latest pack artifact
The right-sidebar view is intentionally compact. It focuses on the live metrics that matter most instead of repeating verbose activity logs or warning blocks that are already available in the main CTX outputs.
Use the core profile when you want the smallest possible slash-command surface and do not need the sidebar yet.
Proof From The Demo Fixture
The committed demo benchmark compares a traditional markdown-rule flow against CTX graph memory on demo/fixtures/opencode-auth-lab.
Reproduce it with:
scripts/demo/opencode-auth-lab-benchmark.sh ./target/debug/ctx
Evidence files:
External validation is also committed in docs/external-benchmark-agentsmd.md, including a public-repo snapshot with:
- token reduction
72.62% - query coverage
markdown=1.00,graph=0.89 - success rate
markdown=0.50,graph=1.00 - quality wins
markdown=0,graph=1,ties=0
Demo And Screenshots
Security
CTX is local-first by default:
local_only = trueremote_upload_enabled = false- no mandatory network calls
.ctx/graph.db,.ctx/packs/,.ctx/stats/, and.ctx/audit.logstay local- sensitive-looking attachments such as
.env, private keys, credentials, and secret files are blocked by default
See docs/security.md.