ctx — Skill, Agent, MCP & Harness Recommendations

ctx is not an Amazon-style catalog of skills, MCPs, agents, tools, or harnesses. It is a recommendation layer. Point it at your organization's own tools, or use the pre-built graph, and ctx recommends the smallest useful bundle for the current development window. The goal is to load the right skills, agents, MCP servers, and optional harness at the right moment so hosted LLMs burn fewer tokens and local models waste less CPU/GPU work.

ctx watches what you are building, walks a 79,958-node graph, and recommends a small, top-scored bundle of skills, agents, and MCP servers for the current task. If you use your own local/API model instead of Claude Code or run an external loop such as LoopFlow, ctx has separate harness and adapter flows: tell it the model and goal, review recommendations, and keep installs behind dry-run/update/uninstall controls.

Current shipped snapshot:

• 68,494 skill entity pages, with 67,024 hydrated installable SKILL.md bodies.
• 467 agents, 10,790 MCP servers, and 207 harnesses.
• 1,778,069 graph edges across semantic similarity, tags, slug tokens, source overlap, direct links, quality, usage, type affinity, and graph structure.
• 28,612 long skill bodies converted through the micro-skill gate instead of shipping raw long prompts.
• Entity updates for skills, agents, MCPs, and harnesses print benefits/risks and skip replacement unless you explicitly approve the update.

Why it exists

• Discovery — with 68,494 skill pages, 467 agents, 10,790 MCP servers, and 207 harnesses, you can't possibly know which exist or which apply to your current work.
• Context budget — loading everything wastes tokens and degrades quality. You need the right 10–15 per session.
• Skill rot — skills you installed months ago and never used are cluttering context. Stale ones should be flagged automatically.

Example user stories

The canonical QA tracker is qa/feature_status.csv. The supporting feature ledger docs/qa/feature-user-story-status.csv, dashboard-specific ledger docs/qa/dashboard-user-story-status.csv, and tool-selection/token-history ledger qa/tool-selection-token-history/tracker.csv are supporting detail ledgers that feed that root tracker; canonical status and release readiness stay in qa/feature_status.csv. Bug-smoke audit findings live in qa/bug_smoke_status.csv and are validated by the same public docs tracker. Retested Pass bug-smoke rows must include PASS: retest evidence and a closed next_action starting with Closed;. Rows for public MkDocs pages use the exact docs/...md path from mkdocs.yml as entrypoint_or_route. Public linked docs assets under docs/assets/javascripts/, docs/services/, and docs/toolbox/templates/ are tracker-covered too, so adding, moving, or removing one means adding or updating matching rows in the relevant supporting ledger and canonical tracker. Examples from that tracker:

Install

pip install claude-ctx
ctx-init                    # terminal wizard: hooks, graph, model, harness goal
ctx-init --graph --hooks --model-mode skip  # fast runtime graph + Claude Code hooks
ctx-init --graph --graph-install-mode full  # install the full packed wiki locally
ctx-init --wizard           # force the same wizard from scripts/tests
ctx-init --model-mode custom --model openai/gpt-5.5 --goal "build a CAD agent"

Optional extras: pip install "claude-ctx[embeddings]" for the semantic backend, pip install "claude-ctx[harness]" for local/API model harness runs, pip install "claude-ctx[dev]" for the test toolchain.

Pre-built knowledge graph

Graph-backed recommendations need the pre-built graph. By default, ctx-init --graph installs the fast runtime artifact: graph/wiki-graph-runtime.tar.gz in source checkouts, or the matching GitHub release asset from pip installs. It contains graphify-out/*, the shipped skill index needed for recommendations, and the 207 harness pages needed by ctx-harness-install and LoopFlow adapter harness recommendations:

ctx-init --graph

The full LLM-wiki artifact remains available for local browsing and Obsidian. High-fanout skill, agent, MCP, converted, and concept pages are stored in wiki-packs/ instead of expanded as individual files:

ctx-init --graph --graph-install-mode full

The full wiki-graph.tar.gz includes the shipped skill index and a wiki-pack base containing 68,494 skill entity pages plus 67,024 hydrated installable SKILL.md files. Harness pages remain directly available under entities/harnesses/.

Windows: PowerShell's built-in tar.exe does not support --force-local; use tar -xzf graph\wiki-graph.tar.gz -C "$env:USERPROFILE\.claude\skill-wiki". In Git Bash or MSYS, use --force-local only when your -C target is a drive-letter path such as C:/Users/....

Use

After ctx-init --hooks or the wizard hook step, ctx observes Claude Code's PostToolUse and Stop events. Typical flow:

ctx-scan-repo --repo .     # scan current repo and stack signals
ctx-scan-repo --repo . --recommend  # include skill/agent/MCP recommendations
ctx-agent-add --agent-path ./code-reviewer.md --name code-reviewer
ctx-harness-add --repo https://github.com/earthtojake/text-to-cad --tag cad
ctx-harness-install text-to-cad --dry-run   # inspect before cloning/running anything
ctx-harness-install text-to-cad             # install after reviewing the plan
ctx-harness-install text-to-cad --update --dry-run
ctx-harness-install text-to-cad --uninstall --dry-run
ctx-recommend "fix FastAPI auth" --selected skill:fastapi-pro --active mcp-server:codex-cli --json
ctx-recommend "LoCoBench python feature_implementation no API keys" --local-code-task --no-api-keys --language python --json
python -m ctx --help      # same run/resume/sessions CLI as the ctx script
python -m ctx.adapters.loopflow --goal "fix checkout e2e" --permissions skills,agents,mcps
ctx-skill-quality list     # four-signal quality score for every skill
ctx-skill-quality explain python-patterns   # drill into a single skill
ctx-skill-health dashboard # structural health + drift detection
ctx-toolbox run --event pre-commit          # run a council on the current diff
ctx-telemetry-export --dry-run --json       # inspect privacy-redacted telemetry spool
ctx-monitor serve          # local dashboard: http://127.0.0.1:8765/

ctx-recommend accepts --selected, --rejected, --active, --baseline-context, --include-baseline-context, --show-unavailable, --local-code-task, --no-api-keys, and --language so loops can recover from partial choices without re-suggesting active or baseline host context.

Before pushing, run the two-tier local PR gate. Start with the smoke profile when you want quick feedback before paying for the heavier lanes:

scripts/no_mistakes_run.sh fast --profile smoke

Then run the full fast committed-HEAD gate:

scripts/no_mistakes_run.sh fast

That runner selects checks from the same classifier as PR preflight, groups independent checks into isolated temporary worktree lanes, and runs them in parallel. The smoke profile keeps cheap invariants, no-test policy, ruff, and public docs tracker checks while deferring slow unit, package, graph, browser, similarity, telemetry, and strict docs lanes to the normal PR profile. Treat the normal profile as the fast front door before no-mistakes or PR. It writes lane timing evidence to .gate/local-fast.json by default; use lane filters for quick reruns after a failed lane:

scripts/no_mistakes_run.sh fast --lane static --lane unit
scripts/no_mistakes_run.sh fast --lane unit --lane canary --lane contract --lane clean-host
scripts/no_mistakes_run.sh fast --skip-lane graph
scripts/no_mistakes_run.sh fast --summary-json /tmp/local-fast.json

Use the gate wrapper when the branch is ready for no-mistakes. It refuses implicit/stale intent, runs smoke + full local-fast first, then starts no-mistakes with the explicit branch objective:

scripts/no_mistakes_run.sh gate --intent "narrow task statement for this branch"

The serial preflight/no-mistakes path remains available when you need to inspect individual checks. Preflight uses the same changed-file classifier as GitHub Actions, then runs the matching local checks: stats, ruff format/check, mypy, pip check, unit coverage, canaries, package build, twine, docs, graph validation, browser, and similarity gates as needed. For docs changes, that docs gate runs the public docs tracker checks before the strict MkDocs build. When graph artifacts are changed and still checked out as Git LFS pointers, preflight hydrates only the required tarballs, checks the pointer SHA-256 and size caps, then validates the artifacts. Use --profile full before release work to force the source/package gates even for docs-only or graph-only changes. Always pass an explicit narrow no-mistakes intent so review/test/doc agents validate this branch instead of inferring a stale broader goal from local transcripts.

The ctx-monitor dashboard shows currently loaded skills, agents, MCP servers, installed harness records, selectable recommendations (/recommend), and generic-harness validation/escalation plus tool-selection/token-usage state (/runtime). It provides load/unload buttons where ctx owns the live action, a graph view (/graph?slug=...), the LLM-wiki entity browser (/wiki/<slug>), a filterable skills grid, a session timeline, audit/runtime log views, and a live SSE event stream. Installed harness records appear in /loaded; harness pages appear in /wiki and /graph. Harness install/update/uninstall actions stay in ctx-harness-install.

When ctx-skill-add, ctx-agent-add, ctx-mcp-add, or ctx-harness-add finds an existing entity, ctx prints a benefits/risks update review and skips replacement by default. Re-run with --update-existing to apply the catalog or local asset update after review.

Step-by-step entity onboarding: https://stevesolun.github.io/ctx/entity-onboarding/

Full docs, architecture, and every module: https://stevesolun.github.io/ctx/

License

MIT — see LICENSE.