Tools
Workflow & Orchestration Tools
Workflow state machines, context handoff, code execution, and feedback
These tools manage multi-step workflows with state machines, enable context handoff between sessions, execute code in sandboxed environments, and collect quality feedback for continuous improvement.
Tools Overview
| Tool | What It Does |
|---|---|
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. |
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. |
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. |
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. |
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). |
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/. |
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. |
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. |
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. |
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. |
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. |
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. |
ctx_workflow
ctx_workflow implements state-machine-driven workflows for complex multi-step tasks.
Define named workflows with ordered steps, transition between states, and enforce evidence collection
at each stage.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | No | Workflow operation to perform |
name | string | No | Workflow name (for create/start) |
key | string | No | Workflow key / identifier |
spec | string | No | Workflow specification (JSON) |
to | string | No | Target state for transition |
value | string | No | Evidence value for the current step |
Example: Bug Fix Workflow
ctx_workflow action="start" name="bugfix" spec='{"steps":["reproduce","diagnose","fix","test","verify"]}'
→ Workflow bugfix started at step: reproduce
ctx_workflow action="transition" key="bugfix" to="diagnose" value="Reproduced in test_auth.rs:42"
→ bugfix: reproduce → diagnose (evidence saved)ctx_handoff
ctx_handoff enables context transfer between sessions or agents via the Context Ledger
Protocol (hashed, deterministic, local-first). Create a ledger of your current context
(files, decisions, progress) and pull it in a new session without re-reading everything.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | No | create, show, list (default), pull, clear, export, or import |
path | string | No | Ledger file path (for show/pull/import) |
paths | string[] | No | Multiple paths to include |
apply_knowledge | boolean | No | Include knowledge base in handoff |
apply_session | boolean | No | Include session state |
apply_workflow | boolean | No | Include workflow state |
Example: Create & Pull Context
# Create a handoff ledger before ending the session
ctx_handoff action="create"
→ Ledger created: 12 files, 3 knowledge entries, 1 workflow
# In a new session: pull everything from the ledger
ctx_handoff action="pull" apply_knowledge=true apply_session=true
→ Pulled: 12 cached files, 3 knowledge entries, workflow "bugfix" at step "test"ctx_execute
Run code in sandboxed subprocesses across 11 languages. See the full ctx_execute documentation for language support and examples.
ctx_feedback
ctx_feedback records quality signals about tool usage - latency, token counts, model info,
and free-form notes. This data feeds into LeanCTX's adaptive optimization over time.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | No | Feedback operation |
intent | string | No | What the agent was trying to do |
model | string | No | LLM model name |
latency_ms | number | No | Time taken in milliseconds |
llm_input_tokens | number | No | Input token count |
llm_output_tokens | number | No | Output token count |
note | string | No | Free-form quality note |
ctx_pack v3.4.5
ctx_pack generates a PR Context Pack: changed files, related tests, impact summary, and relevant context artifacts, ideal for code reviews and handoffs.
Packages use the open .ctxpkg file format.
| Param | Type | Req | Description |
|---|---|---|---|
action | string | No | pr (default), create, list, info, remove, install, export, import, auto_load, or summary |
name | string | For create/info/remove/install/export | Package name |
format | string | No | markdown (default) or json (for pr) |
ctx_proof v3.4.5
ctx_proof exports a machine-readable ContextProofV1 artifact containing verifier results, SLO evaluations, pipeline metrics, and provenance data.
Proofs are written to .lean-ctx/proofs/.
| Param | Type | Req | Description |
|---|---|---|---|
format | string | No | json (default) or html |