Skip to content
Back to search

CTX

CTX - Context Runtime Engine for Coding Agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alegau03--ctx/badge.svg)](/listings/alegau03--ctx)

HTML

<a href="/listings/alegau03--ctx"><img src="/api/listings/alegau03--ctx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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-bin` - `brew tap Alegau03/ctx && brew install ctx`

Update paths:

- `ctx update` - `ctx update --check` - `cargo install ctx-cli --force` - rerun the installer script - `npm update -g @alegau/ctx-bin` - `brew 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](https://github.com/Alegau03/CTX/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](docs/install.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 382 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>CTX</h1>
  3. <h3>The context layer for AI coding agents</h3>
  4. <p><strong>Reduce token waste in OpenCode and AI coding workflows with graph memory, compact task packs, read-cache compression, command pruning, and a live right-sidebar dashboard.</strong></p>
  5. <p>OpenCode-first runtime · Local MCP tools · Read cache + delta-aware indexing · Single Rust binary</p>
  6. <p>
  7. <img src="https://img.shields.io/badge/CI-ready-22c55e?style=flat-square" alt="CI ready" />
  8. <img src="https://img.shields.io/badge/local--first-yes-0f172a?style=flat-square" alt="Local first" />
  9. <img src="https://img.shields.io/badge/telemetry-local-2563eb?style=flat-square" alt="Telemetry local" />
  10. <img src="https://img.shields.io/badge/license-MIT-f43f5e?style=flat-square" alt="MIT license" />
  11. </p>
  12. <p>
  13. <a href="#install-ctx">Install</a> ·
  14. <a href="#opencode-first-usage">OpenCode Usage</a> ·
  15. <a href="#ctx-dashboard">Dashboard</a> ·
  16. <a href="#proof-from-the-demo-fixture">Benchmarks</a> ·
  17. <a href="#documentation">Docs</a> ·
  18. <a href="#security">Security</a>
  19. </p>
  20. </div>
  21. > 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.
  22. ## See It In Action
  23. | Install + Bootstrap | Planning + Packing | Read Cache + Dashboard |
  24. |---|---|---|
  25. | ![Install + Bootstrap](docs/assets/gif1.gif) | ![Planning + Packing](docs/assets/gif2.gif) | ![Read Cache + Dashboard](docs/assets/gif3.gif) |
  26. | 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. |
  27. ## Contents
  28. - [What CTX Is](#what-ctx-is)
  29. - [Why It Exists](#why-it-exists)
  30. - [Install CTX](#install-ctx)
  31. - [OpenCode-First Usage](#opencode-first-usage)
  32. - [What Works Today](#what-works-today)
  33. - [Graph Memory](#graph-memory)
  34. - [CTX Dashboard](#ctx-dashboard)
  35. - [Proof From The Demo Fixture](#proof-from-the-demo-fixture)
  36. - [Demo And Screenshots](#demo-and-screenshots)
  37. - [Security](#security)
  38. - [Documentation](#documentation)
  39. - [Repository Layout](#repository-layout)
  40. ## What CTX Is
  41. 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.
  42. CTX is **not** another agent launcher.
  43. - OpenCode keeps the selected model, provider, and normal workflow.
  44. - CTX sits underneath as the context layer.
  45. - The product surface is the OpenCode-native `/ctx-*` experience, not wrapper-first shell workflows.
  46. ## Why It Exists
  47. Coding agents usually waste tokens on things that are useful once but expensive forever.
  48. | Problem | Traditional flow | CTX flow |
  49. |---|---|---|
  50. | Project rules | Reload a full `AGENTS.md` every turn | Import rules into graph memory and retrieve only the relevant directives |
  51. | File rereads | Pay full price for the same file again | Re-read unchanged files through `digest` / `outline` modes with local read-cache compression |
  52. | Noisy logs | Paste thousands of repeated lines | Run `/ctx-run` or prune logs into root-cause signal |
  53. | Broad diffs | Feed huge patches | Keep only task-relevant hunks and changed symbols |
  54. | Repo navigation | Manual file spelunking | Query local graph, snippets, symbols, and semantic ranking |
  55. | Host integration | Wrapper commands outside the agent | OpenCode-native `/ctx-*` commands plus local MCP tools |
  56. ## Install CTX
  57. Install CTX with the channel that fits your workflow best:
  58. - `cargo install ctx-cli`
  59. - one-line installer script
  60. - GitHub Release archives
  61. - `npm i -g @alegau/ctx-bin`
  62. - `brew tap Alegau03/ctx && brew install ctx`
  63. Update paths:
  64. - `ctx update`
  65. - `ctx update --check`
  66. - `cargo install ctx-cli --force`
  67. - rerun the installer script
  68. - `npm update -g @alegau/ctx-bin`
  69. - `brew upgrade ctx`
  70. ### Cargo
  71. ```bash
  72. cargo install ctx-cli
  73. ```
  74. ### One-Line Installer
  75. ```bash
  76. curl -fsSL https://raw.githubusercontent.com/Alegau03/CTX/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 104 on GitHub
  77. ```
  78. ### npm
  79. ```bash
  80. npm i -g @alegau/ctx-bin
  81. ```
  82. ### Homebrew
  83. ```bash
  84. brew tap Alegau03/ctx
  85. brew install ctx
  86. ```
  87. ### Source Install
  88. ```bash
  89. git clone https://github.com/Alegau03/CTX.git
  90. cd CTX
  91. cargo install --locked --path crates/ctx-cli
  92. ```
  93. Verify:
  94. ```bash
  95. ctx help
  96. ctx doctor
  97. ctx update --check
  98. ```
  99. Native update command:
  100. ```bash
  101. ctx update
  102. ```
  103. How `ctx update` behaves:
  104. - installer-based installs: reruns the official installer path
  105. - Cargo installs: prints `cargo install ctx-cli --force`
  106. - npm installs: prints `npm update -g @alegau/ctx-bin`
  107. - Homebrew installs: prints `brew upgrade ctx`
  108. - ambiguous installs: prints all supported update commands without guessing
  109. ### GitHub Release Archive
  110. Download the latest assets from [GitHub Releases](https://github.com/Alegau03/CTX/releases), then run:
  111. ```bash
  112. shasum -a 256 -c SHA256SUMS
  113. tar -xzf ctx-0.2.5-aarch64-apple-darwin.tar.gz
  114. mkdir -p "$HOME/.local/bin"
  115. install -m 0755 ctx-0.2.5-aarch64-apple-darwin/ctx "$HOME/.local/bin/ctx"
  116. export PATH="$HOME/.local/bin:$PATH"
  117. ```
  118. If you prefer a system-wide install:
  119. ```bash
  120. sudo install -m 0755 ctx-0.2.5-aarch64-apple-darwin/ctx /usr/local/bin/ctx
  121. ```
  122. For the full install matrix, release verification notes, native update behavior, and distribution details, see [docs/install.md](docs/install.md).
  123. ## OpenCode-First Usage
  124. Once `ctx` is installed, enable it in any project:
  125. ```bash
  126. cd /path/to/your/project
  127. ctx init
  128. ctx index
  129. ctx opencode install
  130. opencode
  131. ```
  132. If you want the leanest possible OpenCode surface first:
  133. ```bash
  134. ctx opencode install --profile core
  135. ```
  136. Profile summary:
  137. - `full` (default): full CTX slash-command surface plus the live right-sidebar `CTX Dashboard`
  138. - `core`: lean daily workflow with `/ctx`, `/ctx-doctor`, `/ctx-plan`, `/ctx-retrieve`, `/ctx-pack`, `/ctx-run`, `/ctx-prune-logs`, `/ctx-stats`, and `/ctx-gain`
  139. Inside OpenCode, start with:
  140. ```text
  141. /ctx
  142. ```
  143. From there, the main workflow is:
  144. ```text
  145. /ctx-doctor
  146. /ctx-memory-bootstrap
  147. /ctx-plan <task>
  148. /ctx-retrieve <query>
  149. /ctx-read <file> [mode]
  150. /ctx-pack <task>
  151. /ctx-compare <task>
  152. /ctx-run <shell command>
  153. /ctx-gain
  154. /ctx-dashboard
  155. ```
  156. Toolbooks and reusable lessons are also first-class:
  157. ```text
  158. /ctx-toolbook-import <name> <file>
  159. /ctx-toolbook-search <name> "<query>"
  160. /ctx-toolbook-pack <name> "<task>"
  161. /ctx-learn <key> "<body>"
  162. ```
  163. For full usage, expected outputs, and CLI equivalents, see [guide.md](guide.md) and [docs/commands.md](docs/commands.md).
  164. ## What Works Today
  165. | Area | Current state |
  166. |---|---|
  167. | OpenCode integration | `ctx opencode install` writes `opencode.json`, `.opencode/commands/*.md`, `.opencode/instructions/ctx-host-first.md`, and in `full` profile also provisions `.opencode/tui.json` plus a live sidebar plugin |
  168. | Install profiles | `ctx opencode install --profile full|core` lets you choose between the full CTX surface and a lean daily workflow |
  169. | Command center | `/ctx` shows a categorized CTX menu and best next command |
  170. | Planning | `/ctx-plan <task>` combines retrieval, graph, memory, and pack signals into an implementation plan |
  171. | Context packing | `/ctx-pack <task>` builds compact task packs with graph, memory, failure, diff, and attachment signals |
  172. | Density check | `/ctx-compare <task>` shows before-vs-CTX token density for one task |
  173. | Read cache | `/ctx-read <file> [mode]` supports `full`, `outline`, and `digest` with session re-read compression |
  174. | Delta-aware indexing | repeated `ctx index` runs reuse unchanged files and write index-cache summaries |
  175. | Command compression | `/ctx-run <shell command>` keeps the root cause and stores the raw log |
  176. | Gain reporting | `/ctx-gain` summarizes recent token savings and top repeated queries |
  177. | Dashboard | the `full` profile adds a live right-sidebar `CTX Dashboard`, while `/ctx-dashboard` prints a local snapshot in-thread |
  178. | Graph memory | bootstrap/import/search/list/get/set/delete/export project directives seeded from `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, and Copilot instructions |
  179. | Toolbooks | OpenCode-only `/ctx-toolbook-*` commands keep large CLI manuals out of `AGENTS.md` |
  180. | Learning | `/ctx-learn <key> "<body>"` stores reusable project lessons in graph memory |
  181. | Retrieval | hybrid graph, snippets, FTS, symbols, and semantic ranking with local fallback |
  182. | Pruning | deterministic log and diff pruning with parser-aware diagnostics |
  183. | MCP | local stdio MCP plus localhost HTTP JSON-RPC runtime |
  184. | File coverage | Rust, Python, TypeScript, JavaScript, Markdown runbooks, and common config/script files |
  185. | Privacy | local-only defaults, sensitive attachment blocking, local audit log |
  186. ## Graph Memory
  187. 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.
  188. Instead of this:
  189. - one giant `AGENTS.md`
  190. - every host turn re-reading it
  191. - unclear relevance to the active task
  192. CTX lets you do this:
  193. - import rules once with `/ctx-memory-bootstrap`
  194. - retrieve only task-relevant directives with `/ctx-memory-search`
  195. - fold those directives into `/ctx-plan` and `/ctx-pack`
  196. - store new lessons with `/ctx-learn`
  197. ## CTX Dashboard
  198. When CTX is installed with the default `full` profile, OpenCode gets a live `CTX Dashboard` in the right sidebar.
  199. 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:
  200. - total estimated tokens saved
  201. - average tokens saved per run
  202. - average and latest reduction percentages
  203. - read-cache hit rate
  204. - index-cache reuse rate
  205. - top current win
  206. - latest pack artifact
  207. 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.
  208. Use the `core` profile when you want the smallest possible slash-command surface and do not need the sidebar yet.
  209. ## Proof From The Demo Fixture
  210. The committed demo benchmark compares a traditional markdown-rule flow against CTX graph memory on `demo/fixtures/opencode-auth-lab`.
  211. | Metric | Result |
  212. |---|---:|
  213. | Markdown rule tokens | `744` |
  214. | Graph memory tokens | `322` |
  215. | Token reduction | `56.72%` |
  216. | Query coverage | `markdown=1.00`, `graph=1.00` |
  217. | Markdown answer success | `33.33%` |
  218. | Graph memory answer success | `100.00%` |
  219. | Quality wins | `markdown=0`, `graph=1`, `ties=0` |
  220. Reproduce it with:
  221. ```bash
  222. scripts/demo/opencode-auth-lab-benchmark.sh ./target/debug/ctx
  223. ```
  224. Evidence files:
  225. - [benchmark report](demo/fixtures/opencode-auth-lab/benchmarks/report.md)
  226. - [benchmark JSON](demo/fixtures/opencode-auth-lab/benchmarks/report.json)
  227. - [demo walkthrough](docs/demo-walkthrough.md)
  228. External validation is also committed in [docs/external-benchmark-agentsmd.md](docs/external-benchmark-agentsmd.md), including a public-repo snapshot with:
  229. - token reduction `72.62%`
  230. - query coverage `markdown=1.00`, `graph=0.89`
  231. - success rate `markdown=0.50`, `graph=1.00`
  232. - quality wins `markdown=0`, `graph=1`, `ties=0`
  233. ## Demo And Screenshots
  234. | Media Slot | Suggested Asset |
  235. |---|---|
  236. | Hero GIF | full install -> `ctx init` -> `ctx index` -> `ctx opencode install` -> `/ctx` |
  237. | Sidebar GIF | live right-sidebar `CTX Dashboard` refreshing after `/ctx-pack` and `/ctx-read` |
  238. | Command GIF | `/ctx-plan`, `/ctx-pack`, `/ctx-compare`, `/ctx-run` |
  239. | Static Screenshot | `CTX Dashboard` in OpenCode right sidebar |
  240. | Asset | Status |
  241. |---|---|
  242. | Fixture project | `demo/fixtures/opencode-auth-lab` is committed |
  243. | Automated smoke | `scripts/demo/opencode-auth-lab-smoke.sh` |
  244. | MCP smoke | `scripts/demo/opencode-auth-lab-mcp-smoke.sh` |
  245. | Benchmark smoke | `scripts/demo/opencode-auth-lab-benchmark.sh` |
  246. | Demo walkthrough | [docs/demo-walkthrough.md](docs/demo-walkthrough.md) |
  247. | Recording script | [docs/demo-script.md](docs/demo-script.md) |
  248. | Demo video | [Watch the OpenCode demo video](https://youtu.be/gFwGb7sCzKI) |
  249. ## Security
  250. CTX is local-first by default:
  251. - `local_only = true`
  252. - `remote_upload_enabled = false`
  253. - no mandatory network calls
  254. - `.ctx/graph.db`, `.ctx/packs/`, `.ctx/stats/`, and `.ctx/audit.log` stay local
  255. - sensitive-looking attachments such as `.env`, private keys, credentials, and secret files are blocked by default
  256. See [docs/security.md](docs/security.md).
  257. ## Documentation
  258. | File | Purpose |
  259. |---|---|
  260. | [guide.md](guide.md) | Operational OpenCode workflow, examples, expected outputs |
  261. | [docs/commands.md](docs/commands.md) | Complete CTX command syntax and explanations |
  262. | [docs/install.md](docs/install.md) | Install paths, PATH notes, release archive verification |
  263. | [docs/opencode-integration.md](docs/opencode-integration.md) | OpenCode integration architecture and install profiles |
  264. | [docs/demo-script.md](docs/demo-script.md) | Recording sequence for demos and walkthroughs |
  265. | [docs/demo-walkthrough.md](docs/demo-walkthrough.md) | End-to-end fixture validation |
  266. | [docs/architecture.md](docs/architecture.md) | Runtime architecture |
  267. | [docs/security.md](docs/security.md) | Privacy and trust model |
  268. | [docs/release-playbook.md](docs/release-playbook.md) | Release messaging and checklist |
  269. | [docs/final-qa.md](docs/final-qa.md) | Final QA gate |
  270. | [docs/external-benchmark-agentsmd.md](docs/external-benchmark-agentsmd.md) | Public external benchmark evidence |
  271. ## Repository Layout
  272. | Path | Purpose |
  273. |---|---|
  274. | `crates/ctx-cli` | `ctx` binary, OpenCode bootstrap, user-facing CLI commands |
  275. | `crates/ctx-core` | Runtime orchestration for indexing, packing, memory, retrieval, benchmarks |
  276. | `crates/ctx-graph` | SQLite graph, FTS, memory directives, run metadata |
  277. | `crates/ctx-mcp` | Local MCP runtime over stdio and localhost HTTP JSON-RPC |
  278. | `crates/ctx-pack` | Budget-aware context packing and rewriting |
  279. | `crates/ctx-prune` | Log and diff pruning |
  280. | `crates/ctx-ast` | Symbol extraction and code slicing |
  281. | `crates/ctx-semantic` | Semantic ranking and local fallback embedding backend |
  282. | `crates/ctx-telemetry` | Local stats, audit lines, benchmark summaries |
  283. | `demo/fixtures/opencode-auth-lab` | Realistic fixture project for smoke tests and benchmark proof |
  284. | `scripts/demo` | Demo smoke, MCP smoke, and benchmark scripts |
  285. | `scripts/install.sh` | Official user-local installer script |
  286. | `scripts/release` | Build, package, verify, and final QA scripts |
  287. | `packages/ctx-bin` | npm binary package that downloads prebuilt release assets |
  288. | `Formula/ctx.rb` | Homebrew formula source used for local tap preparation |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.