Imported from CrackingShells/colgrep-mcp (
AGENTS.md). Install upstream withnpx skills add CrackingShells/colgrep-mcp. Copyright stays with the author.
AGENTS.md — maintaining colgrep-mcp
Orientation for the coding agents that maintain this repository. The landing
README.md is for humans deciding whether to install; this file is for you,
and it is deliberately a surface: everything longer than a line lives in a
skill of the dev plugin below.
What this is
A stdio MCP server (Python, mcp SDK v2) that wraps the colgrep CLI so
agents get semantic and hybrid code search as tools. The repository root is
at the same time a Claude Code plugin, an Agent Plugins 1.0 plugin and a Codex
plugin; all three launch the same server with uv run. Both its users and its
maintainers are LLM agents inside harnesses; design for them first.
Execution model
Work here is run by a lead that delegates first. The lead holds the architecture,
the specs and the merges; implementers take bounded, file-disjoint leaves in their
own worktrees, on the cheapest tier that finishes a leaf with the gates green.
Two currencies decide who does what. Tokens: the lead runs on the most capable
tier and everything it reads or edits itself stays in its context, re-sent on every
later turn of the cycle; an implementer's tokens are spent once, on a cheaper tier,
in a context discarded after its report. Latency: parallel leaves cost the
slowest leaf rather than the sum, but each dispatch carries a fixed overhead (the
brief, then the implementer's cold read of this file, its leaf and the cited
reports) that measured leaves place at 4–15 minutes (KT-C, KT-D). So delegation
is the default, and not stubborn: a leaf the lead finishes faster than it can brief
(scaffold, shared helpers, CI, this file, changelog) stays with the lead. Whatever
the harness offers for parallel workers instantiates this; with nothing, the lead
runs the same roadmap sequentially under the same discipline. Load the
campaign-lead dev skill before deciding a task is too small for it.
Load the dev plugin
claude --plugin-dir ./dev # from a clone
claude plugin install colgrep-mcp-dev@cracking-shells # from CrackingShells/Nest, after `claude plugin marketplace add CrackingShells/Nest`colgrep-mcp-dev (dev/) ships the maintainer skills; the product plugin
colgrep-mcp (root) never does. Load a skill when its trigger fires:
| Skill | Load it when |
|---|---|
maintainer-policy |
you are about to add scaffold, CI, hooks, docs or a "best practice"; review or refactor server code; choose between perf and refactor; write a docstring |
campaign-lead |
a task has, or might have, more than one lead-sized leaf — decide that inside the skill, not before it: architecture report, roadmap, worktrees, dispatch, reviewer pass, closing a cycle |
landing-and-release |
you commit, rebase, merge, open or land a PR, resolve a conflict, cut a release, or cz check rejects you |
stack-traps |
you run colgrep by hand, touch a handler or a manifest, debug a plugin that does not connect, read a Windows CI failure, or claude -p fails |
Repo map
| Path | Holds | Edited by |
|---|---|---|
server/colgrep_mcp/ |
the server: server.py (assembly), adapter.py (colgrep subprocess), tools_search.py, tools_index.py, resources.py, prompts.py, errors.py, guide.md (agent guide served as a resource) |
implementers |
server/tests/ |
pytest suite against fake_colgrep.py; test_manifests.py, test_version.py, test_changelog.py, test_readme.py, test_dev_plugin.py are drift guards; e2e/run_e2e.py drives the real binary (not collected by pytest) |
implementers |
server/pyproject.toml |
the only version source, dependencies, [tool.commitizen], [tool.ruff], pytest config |
cz bump for the version; humans/agents for the rest |
plugin.json, mcp.json, .claude-plugin/, .agents/ |
product plugin manifests for the three ecosystems; Codex reads the root plugin.json and its extensions["com.openai"] block rather than a directory of its own; each MCP config (.claude-plugin/mcp.json, mcp.json) launches uvx colgrep-mcp==<version>; version fields and the pins are written by cz bump only |
launcher/packaging changes |
colgrep-mcp.spec.json |
the spec the manifests above are regenerated from, by the playbook's spawning-agent-plugins generator. Declares hub mode (marketplace.hub names CrackingShells/Nest), so regenerating writes no marketplace file here. Must stay byte-identical to the playbook's assets/examples/colgrep-mcp.spec.json: that copy is what the playbook's regeneration guard measures against this repo, so a divergence leaves the guard green while measuring a spec nobody uses |
maintainers, in lockstep with the playbook's copy |
skills/colgrep-search/SKILL.md |
the end-user skill that teaches agents when to use the tools | when tool semantics change |
hooks/ |
the plugin hooks: hooks.json (events every hook-capable harness knows), one <event>.json per event not every harness knows (worktree-remove.json), colgrep_policy.py (one stdlib script serving all events); pinned by server/tests/test_hooks.py |
when the search policy or the harness wiring changes |
dev/ |
the colgrep-mcp-dev plugin: skills/<name>/ (SKILL.md, references/, scripts/), evals/<name>-triggers/case.yaml; versioned by cz bump with the product |
maintainers, when a cycle learns something |
CONTRIBUTING.md |
the commit vocabulary cz check enforces and the release recipe; the rest points at landing-and-release |
with the commitizen config, never alone |
CHANGELOG.md |
Keep-a-Changelog; sections since 0.1.0 are generated by cz bump |
cz bump |
__reports__/<topic>/ |
architecture, findings, observation and retrospective reports per campaign (writing-reports skill) |
leads and reviewers |
__roadmap__/<campaign>/ |
BFS roadmaps; status tables are written only by dirtree-rdm (managing-roadmaps skill) |
leads |
.github/workflows/ci.yml |
ruff check, ruff format check, pytest on three OSes, cz check and a uv build + twine check on pull requests |
when gates change |
.github/workflows/publish.yml |
on a v* tag push: build, PyPI upload by trusted publishing, GitHub release from the CHANGELOG section |
when the release path changes |
Gate commands
All Python commands run from server/. Green is the norm; a red gate blocks a merge.
cd server && uv run pytest # ~10 s, no model download
cd server && uv run ruff check && uv run ruff format --check
cd server && uv run cz check --rev-range main..HEAD # every commit on the branch matches CONTRIBUTING
cd server && uv run cz bump --dry-run # what the next release would be, from history alone
claude plugin validate . && claude plugin validate ./dev # both plugins and the marketplace
claude --plugin-dir . mcp list # the manifest connects — it launches the PyPI pin, not this tree
claude mcp add colgrep-dev -- uv run --quiet --directory ./server colgrep-mcp # to exercise this tree instead
claude --plugin-dir ./dev plugin details colgrep-mcp-dev # the loader sees all four skills (~530 always-on tokens)Opt-in: COLGREP_MCP_REAL=1 uv run pytest adds the few tests that need the real
colgrep; uv run python tests/e2e/run_e2e.py --corpus <some other repo> runs the
end-to-end driver — never against this repository (see stack-traps).
Report ids in docstrings and skills
Docstrings and the dev skills cite report ids as pointers to measured evidence,
not narration. The same R01 label is reused per campaign; the module
docstring's topic disambiguates which one. KT-* are knowledge-transfer
reports, OBS-* observation reports from a reviewer pass.
| Id | Report |
|---|---|
R01 (colgrep_mcp) |
__reports__/colgrep_mcp/00-architecture_v0.md |
R02 |
__reports__/colgrep_mcp/01-findings_mcp_feature_matrix_v0.md |
R03 |
__reports__/colgrep_mcp/01-findings_colgrep_behaviour_v0.md |
R05 (sections D1–D11, M1–M5) |
__reports__/colgrep_mcp/02-architecture_v1.md |
F1–F14 |
__reports__/colgrep_mcp/02-observation_code_review_v0.md |
R01 (repo_health) |
__reports__/repo_health/00-architecture_v0.md |
R01 (consistency) |
__reports__/consistency/00-architecture_v0.md |
R01 (dev_plugin) |
__reports__/dev_plugin/00-architecture_v0.md |
R01 (pypi_publication) |
__reports__/pypi_publication/00-architecture_v0.md |
R01 (harness_wiring) |
__reports__/harness_wiring/00-architecture_v0.md |
R01 (index_housekeeping) |
__reports__/index_housekeeping/00-architecture_v0.md |
R02 (index_housekeeping) |
__reports__/index_housekeeping/00-findings_clear_probe_v0.md |
KT-B |
__reports__/colgrep_mcp/03-knowledge_transfer_v0.md |
KT-H |
__reports__/repo_health/02-knowledge_transfer_v0.md |
KT-C |
__reports__/consistency/02-knowledge_transfer_v0.md |
KT-D |
__reports__/dev_plugin/03-knowledge_transfer_v0.md |
OBS-H |
__reports__/repo_health/01-observation_review_v0.md |
OBS-C |
__reports__/consistency/01-observation_review_v0.md |
OBS-D |
__reports__/dev_plugin/02-observation_review_v0.md |
PH |
__reports__/repo_health/00-findings_launch_placeholders_v0.md |
CI |
__reports__/repo_health/03-findings_ci_matrix_v0.md |
RI |
__reports__/repo_health/04-findings_remote_install_v0.md |
Where the rest went
- Conventions (commit shape, branches, one idiom per concern, perf numbers):
maintainer-policy,landing-and-release. - Coordinating a campaign:
campaign-lead(composes with the machine skillswriting-history,managing-roadmaps,writing-reports). - Traps (colgrep flag order and project folding,
.mcp.jsonplacement, worktrees seeing only commits, conflict markers, anchored ignore rules, derived versions):stack-traps,landing-and-release. - Retrospectives with next-cycle items: the latest
*knowledge_transfer*report in each__reports__/topic.