Execute one approved/planned todo through the agent loop with optional verify gate

Persist and recall project memory (goal.md §25). action=record saves an ADR-style DECISION with its rationale (the WHY) so a later session recalls it instead of re-litigating; search/list retrieve prior decisions, fix patterns, and facts. Also propose/approve/reject for task-scoped proposals.

Create or refresh a persisted editable plan with todos from expand_request intake

The PUBLIC API of a package/directory: its exported symbols with signatures (and doc-comment summaries), in one query — so you learn what a package exposes without reading every file. Pass a repo-relative path prefix (e.g. "internal/retrieval"). include_unexported=true also lists internals.

Apply one or more search/replace hunks to an existing file. Preferred arg: hunks=[{old_string,new_string,replace_all?,exact?}]. Aliases accepted: edits/changes/replacements, or patch as the same array, or a small unified-diff string with context/-/+ lines. Each old_string must match the current file exactly once unless replace_all is true. If an exact match fails purely on whitespace/indentation (tabs vs spaces, trailing space) AND the snippet anchors to exactly one place, the patch is still applied — new_string is reindented to the file's real style and the response notes whitespace_adjusted. Exact matches also restyle new_string indent chars to the file's tab/space convention. Pass exact=true on a hunk to disable tolerant re-anchoring. Preserves untouched content verbatim. Returns a unified diff and revert_token.

Structural code search via a tree-sitter pattern — find every AST node of a given SHAPE, precisely, where lexical query can only match text. Reads files live from disk (never stale). pattern is tree-sitter's S-expression query syntax with @captures, e.g. (function_declaration name: (identifier) @name) to list Go funcs, or (call_expression function: (selector_expression field: (field_identifier) @m) (#eq? @m "Lock")) to find every .Lock() call site. Use for refactors and audits: 'all functions returning error', 'every struct embedding X', 'all callers shaped like Y'.

Render a URL in headless Chromium and SEE it: returns a WebP screenshot the model can view, plus console output, uncaught JS errors, failed requests, optional performance metrics, and page metadata. Use this (not web, which is HTTP-only) for the VISUAL result or client-side JS behavior — verifying a local dev UI (http://localhost:3000) after a change. Write & run a UI test: outline=true lists the interactive elements with ready-to-use selectors, then actions clicks/fills/asserts through the flow (pass/fail reported). WordPress admin: recipe=wp_login|wp_admin|wp_plugins|wp_posts|wp_new_post + site= fills login from encrypted/env secrets (never logged) and waits for #wpadminbar (plugins/posts navigate after). Session reuse: session= keeps cookies across browser calls in this MCP process. Responsive check: device=mobile|tablet|desktop, or devices=["all"] to capture every viewport in one call. Performance check: metrics=true (FCP, load, request count, page weight). Watch it happen: headed=true opens a visible browser that highlights each click/input. Lean by default — the opt-in outline is bounded, not a full-DOM dump. Loopback always allowed; set allow_private for LAN. Needs the managed browser: if missing, run ch browser install once. Binary must be built with -tags rod (default codehelper update / install.sh).

Everything needed to change one symbol SAFELY, in a single call: its definition source, every call site (with the calling line), the tests that cover it, the risk tier, and a consistency checklist. Use right before editing a symbol — it replaces the read/grep round-trips you'd otherwise make and stops you from missing a caller. The edit-time companion to scout.

Read-only GitHub PR and workflow run summary via gh CLI. Requires connections policy github config and env:GITHUB_TOKEN.

Full report for ONE symbol: definition SOURCE, signature/doc, callers, callees, imports, AND blast_radius + risk. Use after query/scout INSTEAD of raw read_workspace_file or a separate impact call. Pass name or sym: id; when names collide (Nest samples, FastAPI docs_src), pass path= to pin the production (or intentional sample) definition.

ACI one-shot for ONE symbol: bounded SOURCE + callers + callees + imports (+ nearby tests). Prefer after search_hybrid/query instead of chaining context + read_workspace_file. Pass name or sym: id; path= disambiguates collisions.

Read-only SQL against a configured database profile (sqlite or mysql/MariaDB). DDL/DML blocked. Requires connections add-db --read-only; secrets via env:/secret only.

Schema introspection for a configured sqlite or mysql database. Optional comma-separated table filter.

Find symbols that nothing in the indexed graph references — candidate dead code. Lists functions/methods (optionally types/vars) with no inbound call or read edge, after excluding entrypoints, tests, and HTTP handlers that a runtime invokes. Returns CANDIDATES to verify, not a delete list: the call graph misses dynamic dispatch, reflection, and cross-repo callers. Use before a cleanup pass; confirm each with impact(upstream) + a name search first.

Map git-diff changed files to affected symbol ids (vs base_ref). Pair with review (audit the diff) or test_impact (tests to run).

Compiler/static-check self-loop without an LSP: auto-detects the repo toolchain and runs its canonical checks (Go: go build + go vet; Rust: cargo check; TS: tsc --noEmit) in the sandboxed argv runner, then returns structured file:line:col problems. Use after editing to confirm the change compiles and vets clean before you claim it works — the fast feedback loop an LSP would give you. Pass command to run a custom check (e.g. "npm run typecheck").

Up-to-date official documentation for a library/framework/API (codehelper's local-first answer to Context7). Resolves the version this project pins from its manifests, then fetches version-correct docs preferring the llms.txt/llms-full.txt standard before HTML. library may also be a direct https URL (docs page, API reference, or OpenAPI page) to fetch it as-is. Unknown libraries resolve via npm/PyPI/crates metadata; if one is still missing, register it with docs_add. Network fetch is privacy-gated.

Register a documentation source the curated index is missing, so a later docs call resolves to it. Use when docs <name> can't find a framework, internal library, or API reference. Writes the global catalog by default (scope=project for this repo only). Idempotent: re-adding a name replaces it.

Post-edit loop: optional change_kit preview, apply_patch, index refresh, since (changed symbols + blast radius), and diagnostics. Fuses the edit → verify → re-index → respond workflow.

Detect toolchain versions, npm/make scripts, docker-compose hint, and configured aliases/log sources from project files — one call, no shell.

Explain why an orchestration run chose its workflow and tool sequence, including any feedback applied.

Which concrete types implement a Go interface — a heuristic interface→implementation map without go/types. Reads the interface's method set and reports every type whose methods cover it (structural typing); partial matches list the missing methods (often means embedding). Use to answer 'what satisfies this interface?' that ranked search can't. Heuristic: verify pointer-receiver/signatures before relying on it.

Hard done gate: verify hygiene + release readiness. Returns can_claim_done / completion_state. Claim done ONLY when can_claim_done=true. On shallow/ephemeral beds returns completion_state=abstain (structured, not error) — do not invent a green gate. Pass verify_ran=true after argv verify, or verify_abstained=true with verify_reason.

Review the project vocabulary seed and promote terms into the shared glossary. action=review lists frequent candidate terms enriched with the symbols they connect to; action=promote writes a term+definition into the committable project_memory.json; action=list shows the approved glossary.

Global, cross-project learned hints/rules ('don't forget X when working with Y'), keyed by framework/language/dependency/project_type and applied to any project that matches. Use action=add to remember something you discovered (so future work on this stack — in any project — gets the hint up front); action=list to review; action=remove to delete by id. Persisted in ~/.codehelper/learned_hints.json (local-first, syncable).

Rank files by architectural RISK = git churn × call-graph centrality. A file changed often (git history) AND depended on heavily (inbound call edges) is where defects are most likely and refactoring most valuable — high churn alone is just active code, high centrality alone is stable infrastructure, their product isolates the risky core. Deterministic, no model. Use to pick refactor targets, focus review, or find where a change is most dangerous; inspect the top rows with context/change_kit and impact.

Blast radius over the call graph before change/delete/rename. Default direction=upstream (who uses this?). Pass direction=downstream for deps. Bare names prefer non-fixture defs; pass path= on sample collisions. Class/type hubs that are self-only on downstream auto-retry upstream. Sparse graphs: do not treat 0 callers as proof of isolation — check confidence / doctor warnings.

Insert a block of code relative to a symbol's definition, located via the symbol graph (no language server). position is before|after|start_of_body|end_of_body. Returns a preview with surrounding context by default; pass apply=true to write. Heuristic line ranges come from the index — review the preview before applying.

Fused investigation: by default query + context + impact + test_impact. Pass recipe=architecture|dead_code|security|perf for specialized audits (architect Q&A pack, dead_code candidates, review_diff security smells, or hotspots+impact). Returns a compact JSON bundle — replaces chained MCP calls.

ONE-CALL task starter: orient + reuse + docs + decision_points + steps + verify cmds. Use FIRST for feature/fix/vibe starts (replaces project_context→scout→plan). Reuse ranks production over sample/test/fixture (see collision_note). role=architect = design Q&A — cite symbols, do NOT edit until accepted (pair with investigate recipe=architecture). Other roles: security|performance|refactor|feature (default). Param task (alias query accepted with a correction note). After edits: diagnostics→review_diff→verify→finish_check.

List one directory (non-recursive) under the repo root — for LAYOUT only. To FIND code, prefer query/scout, which search the whole indexed graph at once; do not walk the tree directory-by-directory.

Tail a configured LOCAL log source (from connections add-log). Remote logs use remote_exec with a tail recipe.

Run a guided local investigation workflow: classify task, execute a deterministic tool chain (query/context/impact/test_impact/etc.), return a context pack + compact tool trace + verification hints. Requires orchestration enabled.

Enable, disable, or check local orchestration for this project. When enabled, use orchestrate for guided investigation workflows with tool trace memory and feedback/rerun loops.

Store correction for an orchestration run and update orchestration memory. Returns constraints for orchestration_rerun.

Search orchestration memory (feedback rules, negative memory, workflow hints) learned from prior runs.

Rerun a previous orchestration with new constraints. Loads prior run, applies instruction/preferred/avoid entities, returns an updated context pack and diff note.

Architect-mode planner: turn a task into a grounded plan BEFORE writing code — reuse candidates, blast radius, decision_points, role checklist, steps + verify cmds. role=architect = design Q&A (cite symbols; no edit until accepted; pairs with investigate recipe=architecture). Other roles: security|performance|refactor|feature (default). Prefer kickoff for the same pack plus orient/docs.

Release gate bundle: detect_changes + review_diff + finish_check in one call — use before claiming done.

One-time BOOTSTRAP for the current MCP workspace: repo identity, index freshness + stats, stack summary, MCP tool count/routing, matching cross-project hints, and next_step. Default verbosity=short (essentials); verbosity=detailed adds layout/deps/git/scripts; sections=tools adds grouped MCP tool names. It does NOT search code — after calling once, use query/scout. Omit repo on other tools to reuse this workspace.

Locate symbols in the indexed graph (BM25/FTS + 1–2 hop graph expand + RRF; optional vector channel) — not web search. Prefer search_hybrid when you also want a package public_api_map. Production/app defs rank above sample/test/fixture/style noise; pass path= on follow-up context/context_bundle/impact when ambiguous. For broad/architecture questions set include_context_pack=true and limit 24-32. Pair hits with context_bundle before claiming behavior. Empty hits → rephrase, ast_query, or analyze.

Read a text file under the repo root. Returns up to a default 500-line window (files within it return in full); larger files return the first window plus a note telling you the next offset to page from. For CODE, prefer query/context/ast_query: they return just the relevant symbols instead of the whole file. Pass offset/limit to read a specific slice.

Run a NAMED recipe on a configured SSH host (never free-form shell). Host and recipe must exist in connections config; remote argv must be on the host allowlist.

Read-only map of configured SSH hosts, DB connections, log sources, and command aliases for this project. Secrets are never returned — configure via codehelper connections CLI.

Preview-first, graph-driven rename of a symbol and its references (codehelper's heuristic answer to an LSP rename — no language server, no go/types). Resolves the definition via the symbol graph, collects graph-confirmed reference sites, and ALSO runs a word-boundary textual scan to catch references the graph missed, classifying every site as graph-confirmed (high confidence) or textual-only (unverified — may be a same-named field, comment, or string). Returns a per-file plan by default; pass apply=true to write graph-confirmed sites (and include_textual=true to also write textual-only ones). Not type-aware: review before applying.

Revert a prior workspace edit using the revert_token returned by write_workspace_file or apply_patch_workspace_file. Idempotent.

Deterministic diff AUDIT in one call (no LLM): the symbols changed vs base_ref, each with its blast radius + risk tier + covering-test count, plus flags — public_api_changes (potential breaking), untested_changes (test gaps), high_risk — the tests_to_run, and a security/performance/reuse/contracts checklist. Use AFTER editing, before finishing. The write-side complement to plan; pair with diagnostics (build/vet) and review_diff (line-level).

Strict review of actual code changes

Run a user-configured command alias (declarative argv or remote recipe). Aliases with requires_approval need approved=true.

Full orchestration run trace on demand: tool calls, arguments summaries, durations, and errors. Use after orchestrate when compact trace is not enough.

Turn a VAGUE idea into a buildable spec — for when you (or the user) have an idea but don't know what to specify and aren't thinking about security/scale/failure. Returns a Why/What/How restatement, the clarifying_questions that actually change architecture/security/data, the decisions_to_make (data shape, scale, auth boundary), the unstated_nonfunctionals beginners skip, existing building blocks to reuse, and a suggested MVP vs out-of-scope. Use BEFORE kickoff/plan when the request is fuzzy; answer the questions with the user, then run kickoff on the concrete task.

Before adding/fixing: ranked reuse candidates (caller counts) + usage_of_top call site + impact_of_top. Production defs beat sample/test/fixture (collision_note when demoted). Use when locating 'what already does X?' — reuse beats reinventing. Then context/change_kit before editing.

Hybrid locate: BM25/FTS → 1–2 hop call/import expand → RRF fuse (optional vector channel when CODEHELPER_EMBED_URL is set). Prefer over raw query when you need structurally related neighbors, not only lexical matches. Optional path= returns a hub-biased public API map for that package (library spine).

Similar-implementation search for ONE symbol: ranks other symbols whose name, signature, and package resemble the target. Use when you found one function and want peers to extend/copy — distinct from scout (task-oriented reuse) and find_implementations (Go interface satisfaction).

What changed since a git ref, and what to do about it — in ONE call. Fuses detect_changes + impact + test_impact: the symbols changed vs base_ref (including uncommitted edits), the downstream blast radius (distinct dependents, worst risk tier, must-update call sites), and the test files to re-run (reverse call-graph closure, a SAFE over-approximation). Use right after editing, before running the suite — the post-edit companion to scout. Also lists new untracked source files the index can't see yet.

Which tests to run for a change. Walks the reverse call graph from changed (or a named target) symbols to the test functions that reach them — a SAFE over-approximation (never silently skips an affected test). Use after editing, before running the suite, to run only what matters.

Call-graph navigation in ONE deterministic step instead of hopping context→context (a tool call per hop). With from and to: the exact SHORTEST call path between two symbols — "how does the HTTP handler reach the DB write?" — including detecting when the dependency actually runs the other way. With only from: the outbound call-flow tree. Use this for hidden/transitive dependencies that ranked search can't surface; pair with impact (blast radius) and context (1-hop neighbors).

Per-project tool-usage + token report. Layers: (1) codehelper OUTPUT — how much context each tool injected, by tool/session/client (claude-code/cursor/codex) — measurable for EVERY client; (2) Claude + Codex MODEL TOKENS — real billed tokens per session, parsed from Claude Code transcripts (/.claude) and Codex rollouts (/.codex); Cursor doesn't expose these locally. Also surfaces the last change-verification (verify/diagnostics) outcome and a recent-call trail. Read-only; never indexes.

Run lint/build/test gates with argv-mode default (no shell), per-command timeout, optional allowlist. REQUIRED before finish_check: after a green run set finish_check verify_ran=true; if cmds are missing/ephemeral use verify_abstained=true + verify_reason — never invent a green gate.

Fast HTTP-only web verification (codehelper's optimized Playwright alternative): fetch a URL and assert on status, content, JSON paths, regex, and latency. No browser, no JS rendering — ideal for verifying APIs, SSR pages, and health checks in milliseconds. Use for finish/verify gates on web changes.

Search the web for current information and return a compact ranked list of {title, url, snippet} to then fetch/verify with the web or browser tools. Use for finding docs, error messages, library/version facts, or current events — anything outside the indexed repo. Provider is configured via ch config search (Tavily/Brave free keys, or keyless DuckDuckGo fallback). Does not crawl; it finds the URLs to look at.

Replace a file under an indexed repo root (full content). Prefer apply_patch_workspace_file for edits to existing files. Empty content is refused by default (no 0-byte artifacts); pass allow_empty=true only when intentional. Cannot write under .git/, node_modules/, or .env* files. Returns a revert_token usable with revert_workspace_edit.