Ctx
Open source Agentic Development Environment (ADE): a hackable desktop workbench for coding agents.
ctxrs · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ctxrs/ctxAbout this skill
name: ctx description: Use ctx as working memory for prior agent work. Before starting or continuing work in an unfamiliar area, resuming earlier work, or revisiting an investigation, search prior sessions to ground yourself in earlier context. When ctx blame is available, use it to trace a line, file, commit, or PR to the agent session that produced it. Use when prior decisions, constraints, attempts, tool calls, transcript evidence, or code provenance may matter.
ctx
Use ctx to ground your work in relevant prior agent sessions. Search local history for earlier decisions, constraints, attempts, and evidence. When ctx blame is available, use it to trace code and Git artifacts to the agent session that produced them.
ctx retrieves source material; you perform the analysis. Keep every conclusion grounded in the retrieved evidence.
Prerequisites
-
Require the
ctxCLI to be installed and set up. If it is missing and installing tools is appropriate for the task, use the installer for the current platform.macOS and Linux:
curl -fsSL https://ctx.rs/install | shWindows PowerShell:
irm https://ctx.rs/install.ps1 | iex -
If ctx is installed but not initialized, run:
ctx setup -
First setup can take time while ctx indexes past sessions. Allow setup to finish or keep it running in an appropriate background session.
-
If ctx remains unavailable, say so and do not invent history or provenance.
Get help and full documentation
This skill provides top-level workflow guidance, not a complete ctx command reference. When exact command behavior, options, output formats, installation, or troubleshooting details matter, consult help from the installed version rather than guessing:
ctx <command> --help
ctx docs search "<topic>"
ctx docs show <topic>
ctx docs list
Prefer ctx docs search and ctx docs show for agent use because they return
concise text and match the installed ctx version. When a man-page view is
useful, run:
ctx docs man --print ctx
Use ctx.rs for the product website and documentation. Use GitHub for source, releases, and issues. Treat these as secondary resources; prefer installed help for command details.
Choose history search or Pro blame
- Search local history when the request concerns a topic, decision, constraint, error, command, file, prior attempt, or previous session.
- Use ctx blame when the request starts from a line, file, commit, or PR and asks which agent session produced it or why it was written that way.
- Combine both when blame identifies a session and broader search is needed to find related investigations or follow-up work.
Search local history
-
Confirm ctx is ready when starting from a cold context:
ctx status ctx sourcesUse
ctx status --format jsonorctx sources --format jsononly when a script needs exact fields. Otherwise, it is less token-efficient than default output formatting. -
Search with normal language first. Add terms or filters when useful:
ctx search "<query>" ctx search "<query>" --workspace <workspace> ctx search "<query>" --file <path> ctx search "<query>" --since 30d ctx search "<query>" --session <ctx-session-id>These are entry points, not a complete option reference. Use
ctx search --helporctx docs show searchfor all search filters and behavior.Prefer default text output for agent reading. Use
--format jsononly when piping tojqor a script, or when exact machine-readable fields are required.Run several searches with different wording for topic research. Use a session-scoped search when one result looks relevant and dense event-level matches are needed.
Ordinary search already covers primary and subagent work, returning one best result per root task before repeats. Use
--primary-onlyonly when the task deliberately calls for a narrow primary agent search.Use
--verbosefor full ctx IDs, provider IDs, source details, and copyable follow-up commands without switching to JSON. -
Inspect relevant results before relying on them:
ctx show event <ctx-event-id> --window 5 ctx show session <ctx-session-id> -
Locate original provider material when source identity or resume hints matter:
ctx locate event <ctx-event-id> ctx locate session <ctx-session-id> -
Write a transcript when the user or another agent needs a file:
ctx show session <ctx-session-id> --format markdown --out <output-path>Direct CLI searches automatically exclude the current session tree for Codex, DeepSeek Harness, Grok Build, Pi, Claude Code, Goose, Hermes, Shelley, Qwen Code, and Mux when the current session can be identified unambiguously. Unsupported or ambiguous detection fails open: ctx leaves the history included.
--include-current-sessionrestores the automatically excluded tree. Repeat--exclude-session <ctx-uuid-or-unambiguous-prefix>to exclude exact named sessions; the option is repeatable and conflicts with--session. MCP searches do not automatically exclude the caller's session.
Trace code with ctx blame
ctx blame requires Pro access. Determine availability from ctx status or a
typed ctx failure; do not infer commercial state.
- If the trial is active, a paid subscription is active or canceling but still paid through, or valid offline grace applies, use blame whenever it is relevant without asking again about Pro access.
- If Pro has not been activated and an eligible free trial may be available,
explain that blame needs Pro and offer to start the trial with
ctx pro. Starting the trial consumes its one-time time window, so runctx proonly after the human approves, unless the current request already explicitly