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:

Tracker row	User story	Expected ctx behavior
CLI-002	As a user I can ask ctx for current repo recommendations.	ctx-recommend returns a capped, graph-scored bundle of relevant skills, agents, and MCP servers from the shared recommendation engine.
CLI-026	As a local/API model user I can get harness recommendations and install one.	ctx-harness-install --dry-run interviews model/goals/tools/privacy, recommends a fitting harness above threshold, or emits a no-fit custom harness PRD.
CLI-049	As a DSL runner or custom agent-loop author I can ask ctx for scoped planning capabilities before each loop plan.	python -m ctx.adapters.loopflow emits a permission-gated JSON contract with skill, agent, MCP, ctx MCP server, and gated harness recommendations.
API-011	As a dashboard user I can manually add, edit, or delete entities.	/api/entity/upsert and /api/entity/delete validate type, slug, and body, then queue safe graph/wiki updates instead of mutating blindly.

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  # expand the full markdown 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, Obsidian, and expanded markdown pages:

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

The full wiki-graph.tar.gz includes the shipped skill index, 68,494 skill entity pages under entities/skills/, 67,024 hydrated installable SKILL.md files under converted/, and 207 harness pages 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 --json  # related suggestions
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/

Before pushing, run the local PR gate:

python scripts/ci_preflight.py --profile pr

It 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. Use --profile full before release work to force the source/package gates even for docs-only or graph-only changes.

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.