yvgude--lean-ctx/docs/reference/generated/mcp-tools.md

Appendix — MCP Tools (generated)

Source of truth: rust/src/server/registry.rs and the tool definitions it registers.

lean-ctx registers 81 MCP tools (granular profile). Each entry below lists the tool name, what it does, and its parameters (* marks required).

ctx_agent

Multi-agent coordination — shared message bus, persistent diaries, stigmergic scent field. WORKFLOW: register agents first, then post/read messages, sync for state alignment. Actions: register (agent_type+role), post (message+category), read (poll), status (active|idle|finished), handoff (task+summary), sync (agents+messages+scent), claim/release (file/task), brief (sub-agent briefing), return (distill→knowledge), diary|recall_diary|diaries (agent journal), share_knowledge|receive_knowledge (cross-agent), list, info. ANTIPATTERN: NOT for single-agent workflows. Use ctx_compose for code understanding.

Parameters: action*, agent_type, category, message, role, status, to_agent

ctx_analyze

Entropy analysis — recommends optimal compression mode for a file path. WORKFLOW: Use BEFORE ctx_read to pick the best mode (full/signatures/auto). Saves tokens by selecting the mode that minimizes size while retaining information.

Parameters: path*

ctx_architecture

Architecture analysis — understand module structure without reading every file. WORKFLOW: use ctx_compose FIRST for code understanding; ctx_architecture for high-level structure. action=overview→high-level; clusters|communities→groupings; layers|cycles→dependency violations; entrypoints|hotspots→risk areas; health→quality; module path='src/' to zoom into a specific module. ANTIPATTERN: does NOT show source code — only structural relationships.

Parameters: action, format, path, root

ctx_artifacts

Context artifact registry with BM25 search — manage and query indexed code artifacts. WORKFLOW: index artifacts first (index/reindex), then search with query for semantic retrieval. Actions: list|status|index|reindex|search|remove. ANTIPATTERN: NOT for general code search — use ctx_semantic_search for codebase queries.

Parameters: action*, format, name, project_root, query, top_k

ctx_benchmark

Benchmark compression modes — measures token savings across all available modes for a file or project. WORKFLOW: use BEFORE ctx_read to pick the optimal compression strategy. Provide a file path, or use action=project for project-wide results. ANTIPATTERN: NOT for production profiling — measures compression, not runtime performance.

Parameters: action, format, path*

ctx_cache

Cache operations — inspect, clear, or invalidate the read cache. Actions: status lists cached files; clear empties all (recover token budget); invalidate path=... refreshes a single entry. Use to diagnose stale content or recover budget after large reads. ANTIPATTERN: does NOT affect disk files — only cached read content.

Parameters: action*, path

ctx_call

Invoke any non-core lean-ctx tool by name — for tools not exposed as standalone MCP tools. Categories: arch, debug, memory, batch, agent, util. Find exact names with ctx_discover_tools (query=keyword; empty query lists all). Cannot invoke itself.

Parameters: arguments, name*

ctx_callgraph

Callers/callees for one symbol (function call edges, not const/var refs). action=callers|callees symbol='fn' → every call site with file:line. action=trace from→to finds the path between two symbols (depth=N). For end-to-end flow understanding use ctx_compose FIRST.

Parameters: action, depth, file, from, symbol, to

ctx_checkpoint

Local shadow git history of the agent's changes — separate from the user's .git. WORKFLOW: snapshot before+after changes to capture exactly what was modified. Actions: snapshot (record current state), log (list checkpoints with SHAs), diff from=... to=... (compare checkpoints), restore ref=... (revert files). ANTIPATTERN: Never touches the user's repository — completely isolated shadow history.

Parameters: action, from, limit, message, path, ref, to

ctx_compare

Preview compression — original vs the bytes lean-ctx would emit, with token counts + line diff. INPUT (pick one): path= (read pipeline) | content= [+ ext=rs|json|csv] (read pipeline) | command= + output= (shell pipeline). Read-only: never changes files, cache, or session. Use to decide whether a mode/pipeline is worth it. ANTIPATTERN: not for reading files (use ctx_read) or restoring archived output (use ctx_expand).

Parameters: command, content, ext, output, path

ctx_compile

Build minimal context package within token budget. Modes: handles (references), compressed (content), full (all cached). WORKFLOW: after ctx_read/ctx_compose, package focused context for handoff/subagent. ANTIPATTERN: not for exploration — use ctx_compose/ctx_read first.

Parameters: budget, mode

ctx_compose

PRIMARY TOOL — call FIRST for understanding code (before editing/debugging/'how does X work'). Returns ranked files with relevant symbol source inline grouped by file. Combines BM25 lexical+semantic+associative retrieval+submodular optimization. ANTIPATTERN: Do NOT chain search→read→symbol — one compose replaces the whole chain. ANTIPATTERN: Do NOT Read files whose source compose already returned — it IS the source. WORKFLOW: Fire parallel ctx_read or ctx_compose for different areas.

Parameters: path, task*

ctx_compress

Compress read cache to free token budget. Does not affect session state or knowledge. WORKFLOW: check budget with ctx_context first, then reclaim space.

Parameters: include_signatures

ctx_compress_memory

Compress memory/config file (CLAUDE.md, .cursorrules) preserving code, URLs, and paths. Creates .original.md backup. WORKFLOW: check token overhead with ctx_context, then compress to reduce persistent instruction cost.

Parameters: path*

ctx_context

Session context overview — cached files, seen files, session state, CRP mode. WORKFLOW: track context budget periodically — use before ctx_compress/ctx_compile. ANTIPATTERN: not for reading file content — use ctx_read or ctx_compose.

Parameters: none

ctx_control

Fine-tune context — exclude, include, pin, unpin, set_view, set_priority, mark_outdated, reset, list, history. Overlay-based, reversible, scoped to call/session/project. WORKFLOW: after ctx_compose, exclude low-relevance files. ANTIPATTERN: not for initial context building — use ctx_compose/ctx_read first.

Parameters: action*, reason, scope, target, value

ctx_cost

Cost attribution — track tokens and cost per agent/tool call. Local-first, no external billing. Actions: report (summary), agent (per-agent), tools (per-tool), json (machine), status (live), reset (zero). WORKFLOW: call report to find top cost drivers, then agent/tools for detail.

Parameters: action, agent_id, limit

ctx_dedup

WORKFLOW: action=analyze first to find shared imports/code across files, then action=apply to register dedup hints for ctx_read output. ANTIPATTERN: NOT for permanent dedup — only compression hints for read output.

Parameters: action

ctx_delta

Incremental diff since last read — shows only changed lines after you edit. WORKFLOW: ctx_read(mode=full) -> edit -> ctx_delta (no re-read needed). Use INSTEAD of re-reading the whole file after modifications — saves 90%+ tokens on unchanged content. Path must have a prior ctx_read in this session's cache. For the full git diff against HEAD, use ctx_read(path, mode=diff) instead.

Parameters: path*

ctx_discover

Find shell commands not yet using lean-ctx compression — use when context feels bloated. Shows which commands would save tokens via lean-ctx patterns. limit=N caps results. ANTIPATTERN: not for finding compression bugs — reports missed opportunities only. Run 'lean-ctx init --global' to auto-compress all commands.

Parameters: limit

ctx_discover_tools

WORKFLOW: call FIRST when unsure which tool fits your task — lists all tools on empty query. Then use ctx_call to invoke discovered tools (for static-tool-list clients). ANTIPATTERN: not for runtime invocation — use ctx_call(name=..., arguments=...) directly.

Parameters: query

ctx_edit

Search-and-replace edit with race-condition guards — for simple text replacement in a single file. For editing code you've read, prefer ctx_patch (hash-anchored): it never makes you reproduce old text byte-for-byte. Read with ctx_read(mode="anchored") first. old_string must be unique unless replace_all=true. create=true writes new files. backup creates .bak. MD5/size/mtime pre-guards prevent race conditions. ANTIPATTERN: Do NOT loop on failures — switch to ctx_patch (anchored), or verify file content and adjust old_string. For LSP-aware refactoring (rename, move, inline), use ctx_refactor.

Parameters: create, new_string, old_string, path, replace_all

ctx_execute

Run code in sandbox (11 languages) — use when conditionals, multi-line or cross-language transforms. ANTIPATTERN: for simple one-liners, prefer ctx_shell (lower overhead, auto-compressed). action=code (default) for one-shot; action=batch for parallel multi-language; action=file to process a project file (extension auto-detects). Pass intent to focus large output and save tokens. Languages: javascript, typescript, python, shell, ruby, go, rust, php, perl, r, elixir.

Parameters: action, code, intent, items, language, path, timeout

ctx_expand

Retrieve archived tool output: see [Archived:ID] → ctx_expand id=ID (zero-loss, original preserved). head/tail/search filter lines; action=list|search_all browses/queries archives. ANTIPATTERN: not for project files — use ctx_read or ctx_compose.

Parameters: action, end_line, head, id, json_keys, json_path, query, search, session_id, start_line, tail

ctx_explore

Iterative, deterministic code exploration → compact file:line citations. Runs a bounded multi-turn loop (BM25 + static call/import graph + AST symbols) and returns a <final_answer> block of path:start-end spans instead of bodies. USE WHEN: locating WHERE behavior lives across many files, cheaply. vs ctx_compose: compose inlines bodies in one shot; explore returns citations over N turns (far fewer tokens). citation=true emits only the block.

Parameters: citation, max_turns, path, query*

ctx_feedback

Record and report LLM token/latency metrics — use to track efficiency and optimize context usage. WORKFLOW: action=record during each LLM call, then action=report for readable summary. Actions: record (log event), report (readable summary), json (machine-readable), reset (clear data), status (storage info). ANTIPATTERN: not for debugging code behavior — this tracks token/latency stats only. record requires llm_input_tokens + llm_output_tokens.

Parameters: action, agent_id, intent, latency_ms, limit, llm_input_tokens, llm_output_tokens, model, note

ctx_fill

Budget-aware context fill — compress N files to fit a token budget. WORKFLOW: pass paths[] + budget=N; task="..." enables intent-driven pruning. ANTIPATTERN: does NOT decide which files to include — use ctx_plan for project-wide selection. Saves tokens vs per-file reads (for many files with a budget).

Parameters: budget, paths, task

ctx_gain

Gain report — shows token savings from lean-ctx compression. action=wrapped for periodic/annual summary. Other actions: status|report|score|cost|tasks|heatmap|agents|json. period="week"|"month"|"all" scopes the report.

Parameters: action, limit, model, period

ctx_git_read

Read remote git repos via cached shallow clone (not HTML scraping). modes: overview (tree + README) | tree (file list) | read (file content) | grep (search). Accepts repo URLs and GitHub/GitLab blob/tree links (ref+path auto-detected). https-only, SSRF-guarded. Prefer over ctx_url_read for whole-repo access.

Parameters: max_tokens, mode, path, query, ref, timeout_secs, url*

ctx_glob

Find files by glob pattern (respects .gitignore; multi-root via paths). For file CONTENT search use ctx_search.

Parameters: ignore_gitignore, max_results, path, paths, pattern*

ctx_graph

File-level dependency graph queries. action=symbol path="file.rs::fnName" returns the DEFINITION (not usages — use ctx_search for references). neighbors=imports±direction, impact=reverse-dep blast radius, path from→to=dependency chain, diff since=HEAD~1=git change impact, diagram kind=deps|calls (Mermaid). For understanding code use ctx_compose FIRST.

Parameters: action*, depth, format, kind, path, project_root, since, to

ctx_handoff

Context handoff protocol (hashed, deterministic, local-first). Actions: create|show|list|pull|clear|export|import. Stores curated file refs with hashes. Before ending a session or handing off to another agent.

Parameters: action, apply_knowledge, apply_session, apply_workflow, filename, format, path, paths, privacy, write

ctx_heatmap

File access heatmap — shows most frequently accessed files per session. action=status (default) for summary, action=detail for per-file access counts. Identify hot files to optimize context usage.

Parameters: action, path

ctx_impact

Change impact analysis — assess blast radius before refactoring. action=analyze path="file.rs" maps downstream dependents; action=diff compares git refs; action=chain traces from→to dependency paths. depth controls traversal (default 5).

Parameters: action, depth, format, path, root

ctx_index

Index orchestration — manage code graph index. WORKFLOW: status → build → build-full (escalate if stale). ANTI-PATTERN: build-full is expensive — use incremental build first. Actions: status (state), build (incremental), build-full (rebuild).

Parameters: action*, project_root

ctx_intent

Submit task goals as JSON or short text — server infers from tool calls. ANTI-PATTERN: not needed for simple tasks. query=task|JSON; format=json for JSON output; project_root=scope.

Parameters: format, project_root, query*

ctx_knowledge

Persistent memory across sessions — remember decisions, patterns, and facts for recall. WORKFLOW: save after completing significant tasks; recall at session start. action=remember value='Y' saves a fact (key optional — derived from value; content= is an accepted alias). action=recall query='X' retrieves it (bare recall lists recent facts). action=status shows all categories. action=consolidate imports latest session if present, runs lifecycle, then frees 25% facts/history/procedures capacity. action=gotcha trigger='X' resolution='Y' for known pitfalls. mode=semantic|exact for recall. category groups related facts.

Parameters: action*, as_of, category, confidence, dry_run, examples, format, key, limit, merge, mode, path, pattern_type, query, resolution, severity, store, trigger, value

ctx_ledger

Context ledger — track persistent context pressure. WORKFLOW: status → evict → reset (reset only if budget needs full flush). ANTI-PATTERN: don't evict files you actively need — check status first. Actions: status, reset, evict.

Parameters: action*, targets

ctx_load_tools

Load/unload specialized tool categories to reduce surface area. WORKFLOW: list → load → unload when done. ANTI-PATTERN: don't unload categories you're actively using. Actions: load|unload|list. Categories: arch, debug, memory, metrics, session. Core is always loaded.

Parameters: action*, category

ctx_metrics

Session token statistics — cache hit rates, per-tool savings, pipeline metrics, and signature backend ratios. ANTI-PATTERN: not for real-time monitoring — snapshot of current session. Complements ctx_radar for budget analysis.

Parameters: none

ctx_multi_read

DEPRECATED → use ctx_read with paths=['a.rs','b.rs']. Folded into ctx_read (#509); hidden from tools/list, still callable for one release.

Parameters: fresh, mode, paths*

ctx_multi_repo

Multi-repository — add, remove, search project directories. WORKFLOW: list_roots → add_root/remove_root → search. ANTI-PATTERN: not for single-repo projects — use ctx_search. Actions: add_root|remove_root|list_roots|search|status|save_config. Cross-repo search runs hybrid retrieval per root (BM25+dense+SPLADE) and merges with RRF; mode="bm25" forces lexical-only. ctx_search/ctx_glob/ctx_tree/ctx_read all accept a repo= arg (not in their own schema) to target a registered root by alias instead of the project root — list_roots shows the aliases.

Parameters: action*, alias, max_results, mode, path, query, roots

ctx_outline

WORKFLOW: call BEFORE ctx_read to map code structure (a syntax-aware table of contents). Accepts a FILE or a DIRECTORY (folder surface — per-file symbols). Symbols come from tree-sitter (27 languages, real line spans); a conservative regex fallback covers the rest. kind=fn|struct|class|trait|enum|impl|all filters by kind; match= filters by name (case-insensitive); format=json emits deterministic JSON labelling the backend per file. ANTIPATTERN: NOT for file content (use ctx_read) or deep understanding (use ctx_compose).

Parameters: format, kind, match, path*

ctx_overview

WORKFLOW: call at session START before ctx_compose/ctx_read. ANTIPATTERN: NOT for source code — structure only. Use ctx_compose for code understanding. Project map — task='your goal' scopes files by relevance (PageRank on symbol graph). High-level structure only, no source body. ~10x cheaper than ctx_compose.

Parameters: path, task

ctx_pack

WORKFLOW: create -> export -> import -> install for sharing context state. ANTIPATTERN: NOT for ephemeral session save (use ctx_session). Context Package Manager — create, install, manage portable context packages with knowledge, graph, session patterns, and gotchas. Actions: pr, create, list, info, remove, install, export, import, auto_load, summary. Saves tokens: pre-built context state (avoids re-building).

Parameters: action*, apply, author, base, depth, description, diff, enable, file, format, layers, level, name, project_root, scope, tags, version

ctx_package

WORKFLOW: save -> resume in new session for agent handoff. ANTIPATTERN: NOT for internal session persistence (use ctx_session). Self-contained JSON bundles: session state, summaries, knowledge. Actions: save, resume, list, info. Saves tokens: portable across sessions/agents.

Parameters: action, description, path

ctx_patch

Hash-anchored edit — patch by (line, hash) anchor; never reproduce old text byte-for-byte. Anchors N:hh| come from ctx_read(mode="anchored") or ctx_search(anchored=true). op=set_line one line; replace_lines start_..end_ range; insert_after (line 0 = top); delete; replace_symbol (name + new_body); create writes a NEW file from new_text. new_text="" deletes. Batch via ops:[{op,line,hash,new_text},…] — one preimage, applied all-or-nothing. Stale anchor → CONFLICT with fresh anchors to retry (no partial writes).

Parameters: end_hash, end_line, hash, line, name, new_body, new_text, op, ops, path*, start_hash, start_line

ctx_plan

WORKFLOW: set task+profile -> ctx_plan -> use results with ctx_read/ctx_compose. ANTIPATTERN: NOT for compressing already-selected files (use ctx_fill). Selects files for context via Phi scoring + budget + policy. task=short English; budget=token limit (default 12000); profile=ultra_lean|balanced|forensic. Saves tokens by prioritizing relevant files.

Parameters: budget, profile, task*

ctx_plugins

WORKFLOW: list -> info/name -> enable/disable. ANTIPATTERN: NOT for tool listing (use ctx_discover_tools). Plugin management — list, enable, disable, info, hooks. name required for enable/disable/info. Extends tool functionality. Saves tokens: loads only needed plugins.

Parameters: action*, name

ctx_prefetch

WORKFLOW: call BEFORE context-heavy operations to minimize latency. ANTIPATTERN: NOT for normal reads — only for proactive cache warming. Prewarms cache for blast radius files via graph + task signals. task=description; changed_files=paths for blast radius; budget_tokens=soft budget (default 3000); max_files=limit (default 10). Saves latency (not tokens): preloads files before needed.

Parameters: budget_tokens, changed_files, max_files, root, task

ctx_preload

Caches task-relevant files, returns L-curve-optimized summary. WORKFLOW: call at session start or when switching tasks, before ctx_read. ANTIPATTERN: not for reading individual files — use ctx_read instead. ~50-100 tokens vs ~5000 for individual reads (~50x savings).

Parameters: path, task*

ctx_proof

Export machine-readable ContextProofV1 (Verifier, SLO, Pipeline, Provenance). WORKFLOW: call after completing a task to generate audit trail. ANTIPATTERN: not for budget analysis — use ctx_radar/ctx_metrics instead. action=export (only valid); format=json|summary|both; write=true|false; max_evidence=max tool receipts (default 50). Writes to .lean-ctx/proofs/.

Parameters: action*, filename, format, max_evidence, max_ledger_files, project_root, write

ctx_provider

Query GitHub, GitLab, Jira, Postgres, MCP bridges, custom REST. WORKFLOW: action=list first to discover configured providers. ANTIPATTERN: not for file content — use ctx_compose/ctx_read instead. provider=id (github|gitlab|jira|mcp:); resource=issues|pull_requests. Data flows through consolidation pipeline; results searchable via ctx_semantic_search.

Parameters: action*, iid, labels, limit, mode, provider, resource, state, status

ctx_quality

WORKFLOW: report (project score+hotspots+$ tax) → file (one file) → delta (vs HEAD). Code health = clean code as a token-cost lever: cognitive complexity, naming, and the estimated token 'quality tax' of over-threshold functions. ANTIPATTERN: NOT a linter/style checker — it scores navigability, not formatting.

Parameters: action, format, path, root

ctx_radar

Context budget breakdown — system prompt, messages, tools, reads, shell. WORKFLOW: call when context window tight to find biggest consumers. ANTIPATTERN: not for per-call timing — use ctx_metrics instead. format=display (human-readable) or json (structured). Complements ctx_metrics for comprehensive budget analysis. Saves tokens vs manual budget estimation.

Parameters: format

ctx_read

Read source files. mode REQUIRED — choose by intent (see mode below). To UNDERSTAND code run ctx_compose FIRST; ctx_read after it identified files. anchored → edit by reference via ctx_patch (no exact-recall).

Parameters: aggressiveness, fresh, limit, mode, offset, path, paths, protect, raw, start_line

ctx_refactor

Rename, move, safe_delete, inline, read-only analyses via LSP/IDE. WORKFLOW: use action=references first to find usages before refactoring. ANTIPATTERN: not for symbol discovery — use ctx_symbol/ctx_compose. Single-phase edits (replace_symbol_body, reformat) work headless via name_path. Two-phase ops (_preview+_apply) need JetBrains IDE (else BACKEND_REQUIRED). Conflicts blocked unless force=true. See action parameter for full list.

Parameters: action*, column, direction, end_line, expected_hash, force, keep_definition, line, mode, name_path, new_body, new_name, optimize_imports, path, plan_hash, propagate, scope, search_comments, search_text_occurrences, target_parent, target_path, text

ctx_repomap

PageRank symbol map ranked by structural importance + session relevance. WORKFLOW: call for codebase-wide orientation at session start. ANTIPATTERN: not for task-scoped views — use ctx_overview instead. focus_files=['path/*.rs'] boosts specific areas; max_tokens controls size (default 2048). Saves tokens vs reading all files individually.

Parameters: focus_files, max_tokens, path

ctx_response

Compress LLM response text via structural de-duplication. Removes repetitive patterns while preserving key information. WORKFLOW: use after receiving a response, before storing/forwarding. ANTIPATTERN: no-op when CRP mode is off — use ctx_read compression instead.

Parameters: text*

ctx_retrieve

Retrieve original uncompressed content from the session cache (CCR) — restores full verbatim source when compressed ctx_read output is insufficient. WORKFLOW: call ctx_read FIRST to populate cache, then ctx_retrieve for verbatim. query='text' to find matching lines within cached content. ANTIPATTERN: not for reading files directly — use ctx_read.

Parameters: path*, query

ctx_review

Automated code review with impact analysis, caller tracking, and test discovery. Actions: review (single file), diff-review (from git diff text), checklist (structured review questions). depth=N (default 3). WORKFLOW: run tests first, then use review for structured analysis. ANTIPATTERN: not a substitute for actual test execution.

Parameters: action*, depth, path

ctx_routes

Discover HTTP API endpoints without reading route definition files. Auto-detects: Express, Flask, FastAPI, Actix, Spring, Rails, Next.js. method=GET|POST filters by verb; path='/api' filters by prefix. ANTIPATTERN: not for filesystem paths — use ctx_tree. Saves tokens vs grepping route definitions.

Parameters: method, path

ctx_rules

Cross-agent rules governance (ContextOps). Actions: sync (distribute rules to agents), diff (show drift), lint (check consistency), status (sync state), init (create central config). WORKFLOW: run status first to check state, then sync if out of date.

Parameters: action*, agent

ctx_search

Search code; action picks the engine (default regex). regex(pattern) | semantic(query, by meaning) | symbol(name, AST-exact; or handle=path#name@Lline) | reindex | find_related(file_path,line). anchored=true tags hits for ctx_patch. Run ctx_compose FIRST.

Parameters: action, anchored, file, file_path, handle, include, kind, line, max_results, mode, name, path, paths, pattern, query, top_k

ctx_semantic_search

[Deprecated → ctx_search action="semantic"] Search code by meaning (BM25+embeddings); reindex / find_related are ctx_search actions too. Hidden from tools/list but still callable for one release — prefer ctx_search.

Parameters: action, file_path, languages, line, mode, path, path_glob, query*, top_k

ctx_session

Session memory. save at session end, load at start, status = snapshot; task|finding|decision record progress (value=text). ANTIPATTERN: permanent project knowledge → ctx_knowledge.

Parameters: action*, session_id, value

ctx_share

WORKFLOW: push from agent A → pull from agent B shares cached file contexts. Actions: push|pull|list|clear. Omit to_agent for broadcast. ANTIPATTERN: NOT file transfer — shares lean-ctx cache entries only.

Parameters: action*, message, paths, to_agent

ctx_shell

WORKFLOW: preferred — auto-compresses output (build/test/log). raw=true for verbatim output. [exit:N] on errors (lossless). ANTIPATTERN: multi-line scripts → ctx_execute.

Parameters: command*, cwd, env, raw, timeout_ms

ctx_skillify

WORKFLOW: mine to extract patterns → list to review → promote to activate. Codifies patterns into .cursor/rules/skillify-*.mdc. Actions: mine|list|status|promote. Idempotent. ANTIPATTERN: one-off rules → write .mdc by hand.

Parameters: action, slug

ctx_smart_read

DEPRECATED → use ctx_read (it auto-selects the mode; omit mode). Folded into ctx_read (#509); hidden from tools/list, still callable for one release.

Parameters: path*

ctx_smells

WORKFLOW: rules (list detectors) → scan (run on project). Code smell detection: dead_code, long_function, god_file, complexity, etc. rule='name' or path='file' to filter. ANTIPATTERN: NOT a linter — no style/format enforcement.

Parameters: action, format, path, root, rule

ctx_summary

WORKFLOW: record after tasks → recall with query. Compact session digests (task, files, decisions, next steps). Actions: recall|record|list. Auto-captured on checkpoints. ANTIPATTERN: structured facts → ctx_knowledge.

Parameters: action, query, top_k

ctx_symbol

[Deprecated → ctx_search action="symbol"] Get one symbol's body by name (AST-precise); optional file/kind narrow. Hidden from tools/list but still callable for one release — prefer ctx_search.

Parameters: file, kind, name*

ctx_task

Multi-agent task orchestration. WORKFLOW: action=create → action=list to review → action=update to change state. Actions: create|update|list|get|cancel|message|info. States: working|input-required|completed|failed|canceled. ANTIPATTERN: not for code execution — use ctx_shell or ctx_execute.

Parameters: action*, description, message, state, task_id, to_agent

ctx_tools

Gateway to downstream MCP servers — unlimited external tools at ~constant context cost. actions: find (query → top-N relevant tools) | call (proxy a server::tool) | list (servers+counts) | refresh. WORKFLOW: find to discover, then call the chosen server::tool. ANTIPATTERN: not for built-in tools — use those directly.

Parameters: action, arguments, query, tool

ctx_transcript_compact

Compact an OpenAI-format message array deterministically: keep system + fresh tail verbatim, replace older turns with a recoverable summary, offload raw turns into session memory (indexed for recall). Returns JSON {messages, stats}. tool_call/tool_result pairs never split.

Parameters: focus_topic, fresh_tail_tokens, messages*, protect_min_messages

ctx_tree

Directory tree with file counts per directory. depth=N (default 3); show_hidden for dotfiles; paths for multi-root. respect_gitignore filters ignored files (default true). WORKFLOW: lightweight orientation before ctx_repomap or ctx_compose.

Parameters: depth, path, paths, respect_gitignore, show_hidden

ctx_url_read

Fetch URL: pages→Markdown; PDF→text; YouTube→transcript; mode=auto best per type. mode=facts|quotes for research (claims+confidence). query='topic' focuses extraction. GitHub blob/raw URLs auto-resolve to raw file. SSRF-guarded (no private IPs). max_tokens=6000; timeout_secs=20 (max 60).

Parameters: max_items, max_tokens, mode, query, timeout_secs, url*

ctx_verify

Verification observability — tool call statistics and claim-based verification. WORKFLOW: action=stats to monitor tool usage; action=proof|v2 for Lean4 proof verification. Actions: stats|proof|v2 (format=summary|json|both, default summary). ANTIPATTERN: not for runtime verification during active development — use for periodic audit.

Parameters: action, format

ctx_workflow

Workflow rails — state machine with evidence tracking. WORKFLOW: start → transition (multiple) → complete. evidence_add before transition to attach proof. Built-in plan_code_test when spec omitted. Actions: start|status|transition|complete|evidence_add|evidence_list|stop. spec=WorkflowSpec JSON for custom states/transitions. ANTIPATTERN: NOT for one-shot tasks — use direct tool calls instead.

Parameters: action, key, name, spec, to, value

shell

Shell command with auto-compression (~95 patterns). Alias for ctx_shell. Output is compressed for token savings. For verbatim output pass raw=true. Use when your MCP client prefers shell/bash over ctx_shell — transparently delegates to ctx_shell internals.

Parameters: command*, cwd, raw