Skip to content

MCP tools

The CTXone Hub exposes 68 MCP tools, served over HTTP at /mcp (the standard setup) and over stdio, in ten groups:

  • Memory (8): remember, recall, prime, context, summarize_session, what_changed_since, why_did_we, project_status
  • Curation (5): session_segments, draft_stage, drafts_list, draft_promote, draft_discard
  • Plans (16): plan_new, plan_add, plan_start, plan_done, plan_abandon, plan_edit, plan_next, plan_list, plan_show, plan_tasks, plan_link, plan_stale, plan_move, plan_close, plan_complete, plan_archive
  • Sessions and workspaces (4): session_info, session_link_plan, namespace_for_plan, namespace_for_task
  • Docs and help (2): docs_find, help
  • Reminders (9): reminder_create, remind_me, reminder_list, reminder_get, reminder_snooze, reminder_approve, reminder_cancel, reminder_start, reminder_record
  • Code intelligence (9): code_repos, code_search, code_read, callers_of, callees_of, get_active_repo, set_active_repo, code_cross_repo_edges, code_impact (requires --asd-repo or --asd-url at hub startup; the federated code_cross_repo_edges / code_impact shell out to the asd CLI over the shared repo registry)

Any MCP-compatible agent (Claude Code, Cursor, VS Code Copilot with MCP, Codex, etc.) can call these directly.

For setup instructions, see INTEGRATIONS.md. For the underlying concepts, see ARCHITECTURE.md.

Standard (HTTP daemon). Point your tool at a running ctxone-hub --http by URL — one daemon serves MCP + REST + Lens (see Architecture):

{ "mcpServers": { "ctxone": {
"type": "http",
"url": "http://localhost:3001/mcp?namespace=<detected>"
} } }

Fallback (stdio). The Hub also speaks MCP over stdio when spawned per-client without --http — it stays alive for the agent session and handles one client at a time:

{ "mcpServers": { "ctxone": {
"command": "/path/to/ctxone-hub",
"args": ["--path", "/Users/user/.ctxone/memory.db"]
} } }

ctx init writes the right shape for you automatically in every detected tool (defaulting to the http daemon; --transport stdio for the fallback).

Every stdio session is scoped to a namespace — the per-repo isolation unit for branches, plans, memory, taints, reminders, and history (see MEMORY_BRANCH_SCOPING.md). The namespace is resolved once, at server startup:

  1. An explicit --namespace <ns> flag or CTX_NAMESPACE env var wins.
  2. Otherwise the project detection chain runs from the process cwd (the spawning tool starts the MCP server in the project directory): a .ctxproject file in the cwd or any parent, then the repo’s git remote get-url origin looked up in the Hub’s project registry.
  3. No match → the reserved default namespace.

The repository is forked to the resolved namespace for the whole session — every tool call reads and writes inside it.

Branch mirroring happens at startup too: inside a project namespace, the session’s default ref becomes the sanitized current git branch (feature/x → feature-x), auto-created from main on first use. Tools that omit their ref/branch parameter use this session default; explicit refs are unchanged. Detached HEAD → no mirroring, default stays main.

Call project_status at any time to see the resolved namespace, agent id, and default ref.

All tools return structured text (usually JSON). Agents parse the response and decide what to do with it.

Every response from remember, recall, context, summarize_session, what_changed_since, and why_did_we carries token usage metadata in an _ctxone_stats trailer (or embedded fields for the JSON-native tools).


Store a fact, preference, or decision.

Description (from the tool descriptor):

Store a fact, preference, or decision in agent memory. Facts are searchable and carry confidence scores based on importance.

Parameters:

FieldTypeRequiredDefaultDescription
factstringyes—The fact to store
importanceenumnomediumhigh / medium / low
contextstringno—Category (becomes /memory/<context>/<id>)
tagsstring[]no—Queryable tags
refstringnomainBranch to write to
personalboolnofalseWrite to the personal namespace’s main instead of this workspace

Response: JSON object with status, path, commit_id, ref, namespace (which namespace the write landed in), fact.

personal: true is for what belongs to the person rather than the project, such as a preference. Every workspace’s recall reads the personal namespace, and a personal write isn’t refused when the session fell back to default (HTTP API).

When to call: any time the agent learns a fact about the user’s project that should persist to the next session. Agents are encouraged to call this liberally — the more facts, the better recall ranking gets.


Retrieve memories for a topic.

Description:

Retrieve relevant memories for a topic. Always includes pinned context first, then topic-matched facts, respecting a token budget. Response is JSON including token savings metadata.

Parameters:

FieldTypeRequiredDefaultDescription
topicstringyes—Query string (tokenized)
budgetintegerno1500Max token budget
refstringnomainBranch to read

Response: JSON with results, pinned_count, topic_matches, ctx_tokens_sent, ctx_tokens_estimated_flat, ctx_savings_ratio.

Results are structured: each item has path, pinned: bool and namespace. Pinned items also have title and body; topic matches have value, score, and full_match. Recall reads the personal namespace’s main as well as this workspace, so namespace is either the workspace or _personal; where both hold the same path, the workspace’s copy wins.

When to call: at the start of every agent session, and whenever the agent needs project-specific context mid-session. Think of it as “search my memory for anything relevant to ” — the agent should call it proactively, not just when the user asks.


Load structured sections as pinned or primed memory.

Description:

Load markdown sections as pinned or primed memories. Pinned memories are always included in every recall response (critical context). Sections should be pre-parsed — each entry has a title and body.

Parameters:

FieldTypeRequiredDefaultDescription
sourcestringyes—Group name (idempotent)
pinnedboolnofalseIf true, always include in recall
sectionsarrayyes—Array of {title, body} objects
refstringnomainBranch to write to
personalboolnofalsePrime into the personal namespace’s main, as ctx agents install does

Response: JSON with sections_written count and paths array.

When to call: when loading a new document into memory. Agents typically parse a markdown file on the client side (H1/H2 headings) and pass the parsed sections. The CLI’s ctx prime does exactly this.

Use pinned: true for critical context (project conventions, current status) and pinned: false for searchable reference material.


Load the full context tree for a project.

Description:

Load the full context tree for a specific project or domain. Returns all stored state under that project path.

Parameters:

FieldTypeRequiredDefaultDescription
projectstringyes—Project name (reads /memory/projects/<project>)
refstringnomainBranch to read

Response: JSON with the full subtree serialized. Includes token stats.

When to call: at the start of a session when the user specifies a project, to dump everything under that project into context in one call.


End-of-session commit.

Description:

End-of-session commit capturing what was learned and decided. Call this before closing a session to persist its knowledge.

Parameters:

FieldTypeRequiredDefaultDescription
session_idstringyes—Unique identifier for this session
key_pointsstring[]yes—Bullet points of what was learned
decisionsstring[]no[]Decisions made this session

Writes three paths:

  • /sessions/<id>/summary — joined key points (Checkpoint, 0.9 confidence)
  • /sessions/<id>/decisions — decisions array (Checkpoint, 0.95 confidence)
  • /sessions/<id>/details — full key points (Observe)

When to call: at session end, before the agent shuts down. The corresponding recall on the next session will find these summaries, enabling the “close session, open new one, context preserved” workflow.


Recent commits filtered by timestamp.

Description:

See what has changed in the memory graph since a given date. Shows recent commits and their intents.

Parameters:

FieldTypeRequiredDescription
sincestringyesISO 8601 timestamp (e.g., 2026-04-12T00:00:00Z)

Response: text listing of recent commits with timestamp, category, description, and confidence.

When to call: at session start when the agent wants to catch up on what’s happened since the last session.


Trace the reasoning behind a past decision.

Description:

Trace the reasoning behind a past decision. Searches for the decision and returns its full provenance chain (blame).

Parameters:

FieldTypeRequiredDescription
decisionstringyesSubstring of the decision (e.g., “use BSL 1.1”)

Response: text with matched paths and their blame chains (commit history showing who/when/why).

When to call: when the user asks “why did we decide X?” or the agent needs to justify a past choice to the user.


Show which project namespace this session operates in.

Description:

Show which project namespace this session’s memory operations land in, plus the agent id stamped on commits. Call this to prove where a write went, or to debug why remembered facts seem missing (usually: they were written in a different namespace).

Parameters: none.

Response: JSON with namespace, agent_id, default_ref (the session’s mirrored git branch, or main), and a hint string. In the default namespace the hint suggests running ctx project add <id> in the repo (or committing its .ctxproject) to get an isolated namespace.

When to call: whenever you need to prove where writes land — at session start, or when a recall comes back empty and you suspect the facts live in another namespace.


Report the LLM turn’s token usage to CTXone.

Description:

Report LLM token usage to CTXone for metrics and cost accounting. Call this after any significant LLM turn — pass the numbers straight from the model’s response usage field.

Parameters:

FieldTypeRequiredDefaultDescription
input_tokensintegeryes—Tokens the model consumed as input
output_tokensintegeryes—Tokens the model generated
cache_read_tokensintegerno0Tokens served from prompt cache (Anthropic)
cache_create_tokensintegerno0Tokens written to prompt cache (Anthropic)
modelstringno—Model identifier for display (e.g. claude-sonnet-4.5)
providerstringno—Provider identifier (anthropic, openai, gemini, …)

Response: JSON object with the updated per-session totals (llm_input_tokens, llm_output_tokens, llm_cache_read_tokens, llm_cache_create_tokens, llm_call_count, last_model, last_provider).

When to call: after every LLM turn where you actually invoked a model. The agent just copies numbers out of the provider response’s usage field into the call parameters. Don’t invent numbers, and don’t call for trivial housekeeping turns.

Why it matters: CTXone’s internal savings ratio is computed from what the Hub itself sent in recall responses — an extrapolation. This tool gives Lens ground-truth measurements of actual model consumption, cache hit ratios, and real dollar cost. Sessions that report LLM usage render with real numbers in Lens; sessions that don’t fall back to the CTXone-side view only.


Tools that return plain text (most of the older ones) append a stats line:

<response body>
_ctxone_stats: {"ctx_tokens_sent":42,"ctx_tokens_estimated_flat":451,"ctx_savings_ratio":10.7}

Tools that return JSON natively (remember, recall, prime, context) embed the same fields directly in the response object.

Well-behaved agents can extract and surface these numbers to the user — CTXone is the only memory layer where “how much did this query save?” is a first-class API response.

Every tool call writes commits with agent_id = "ctxone" (or "ctxone-prime" for prime operations). This means ctx blame shows CTXone-mediated writes separately from writes via the raw engine CLI.

If you’re running multiple agents that share a Hub, consider giving each agent its own namespaced branch (agents/alice, agents/bob) so blame is unambiguous.


Five tools turn a session into durable memory, with the user deciding what’s kept. Split the session into arcs, stage candidate memories from the arcs worth keeping, then keep or drop each candidate. Drafts live under /drafts/<session>/ and aren’t recalled until they’re promoted. The session’s turns stay in the archive either way.

Split a session into topic arcs: contiguous stretches of turns on one git branch and working directory. An arc ends at a branch change, a working-directory change, or an idle gap. No LLM is involved.

When to call: before drafting memories from a session. A session is rarely one topic, so keep the arcs that matter and drop whole tangents.

Parameters: session_id, gap? (idle minutes that start a new arc; default 30, and 0 turns the rule off), ref?.

Returns: { session_id, gap_minutes, segment_count, segments }. Each segment has its turn range (start, end, turn_count), branch, cwd, start and end times, tokens, a label, and the reason it started (start, branch, cwd or gap).


Stage a candidate memory distilled from an arc. It isn’t durable: it waits in /drafts/<session>/ for the user to keep, edit or drop.

When to call: after session_segments, once for each decision, gotcha or open thread worth keeping. The user decides what matters; you surface candidates.

Parameters:

FieldTypeRequiredDescription
session_idstringyesSession the candidate came from
contentstringyesThe candidate memory
kindstringnodecision, gotcha, open_thread or fact
turns[int, int]noSource turn range, carried onto the memory as provenance
arcstringnoLabel of the arc it came from
contextstringnoSuggested memory context for promotion
pinboolnoSuggest pinning on promotion
refstringnoBranch (default main)

Returns: the staged draft, with its draft_id and path.


List a session’s staged drafts for review, each with its content, kind, source turn range, and suggested context and pin.

Parameters: session_id, ref?.

Returns: { session_id, drafts }.


Promote a draft to durable memory, the “keep” half of curation. Writes its content under /memory/<context>/, or /memory/pinned/curated/ when it’s pinned, records the source session and turn range in the commit, and removes the draft.

When to call: only for drafts the user chose to keep.

Parameters: session_id, draft_id, context? (overrides the draft’s suggestion; default facts), importance? (high 0.95, medium 0.7 by default, low 0.4), ref?.

Returns: { status: "promoted", path, pinned, source: { session, turns } }.


Drop a staged draft, the “drop” half of curation. It never reaches durable memory, and the session’s turns stay in the archive.

Parameters: session_id, draft_id, reason? (recorded in blame), ref?.

Returns: { status: "discarded", draft_id }.


Sixteen MCP tools wrap the plan primitives from the agentstategraph-tasks crate and surface them with proactive “CALL THIS WHEN” descriptions. Plans persist under /plans/<name>/ and survive session boundaries — the same plan can be picked up by another agent or by you tomorrow.

Create a plan.

When to call: the user describes a multi-step task. Don’t ask permission — if the work is multi-step, plan it.

Parameters:

FieldTypeRequiredDescription
namestringyesKebab-case plan name
descriptionstringnoOne or two sentences
refstringnoBranch, default main

Returns the created plan as JSON.


Add a task to a plan.

When to call: enumerating the steps of a multi-step task — add every step as a task before you start executing.

Parameters:

FieldTypeRequiredDescription
plan_idstringyesPlan name
titlestringyesImperative sentence
descriptionstringnoLonger-form (appended to title)
priorityenumnolow / medium / high / critical
parent_idstringnoParent task id for a subtask
assigned_tostringnoAgent id (e.g. claude-code, codex)
blocked_bystring[]noTask ids that must be done first
refstringnoBranch, default main

Passing assigned_to enables the state-driven orchestration pattern — see plan_next below.


Transition pending → in_progress.

When to call: you begin working on a task. Refuses with an error listing the blockers if any entry in blocked_by is not yet done.

Parameters: plan_id, task_id, reason?, ref?.


Transition in_progress → done. Requires a proof.

When to call: you finish a task. Proof kinds in order of preference:

  • commit — a git SHA (strongest)
  • file — a path you created or edited
  • test — a test name that now exists or passes
  • text — human-attested last-resort

Parameters: plan_id, task_id, proof ({kind, value, note?}), reason?, ref?.

Completing the last open task in a plan auto-promotes the plan to completed.


Mark a task as abandoned. Requires a reason.

When to call: a task turns out to be unnecessary, superseded, or no longer wanted. Legal from both pending and in_progress.

Parameters: plan_id, task_id, reason, ref?.


Change a task’s title, description, priority or blockers after it was added. Status, proof, assignment and timestamps never change.

When to call: a task’s scope or wording changed, or its blockers need fixing. An abandoned blocker never counts as done, so after abandoning a task, edit its dependents’ blockers.

Parameters:

FieldTypeRequiredDescription
plan_idstringyesPlan name
task_idstringyesTask to edit
titlestringnoNew title; the description is kept
descriptionstringnoNew description, or "" to remove it; the title is kept
prioritystringnolow, medium, high or critical
blocked_bystring[]noThe whole new blocker list ([] clears it). Each must be a task in this plan, and the list can’t form a cycle
forceboolnoEdit a done or abandoned task (default false)
refstringnoBranch (default main)

Returns the task with changed, the fields that changed.


Return the highest-priority pickable task.

When to call: you need to know what to work on next.

Parameters:

FieldTypeRequiredDescription
plan_idstringyesPlan name
assigned_tostringnoAgent id, or "me"
include_unassignedboolnoDefault true
assigned_onlyboolnoDefault false
refstringnoBranch

Pass assigned_to="me" to filter to tasks addressed to you. This is the state-driven orchestration primitive: two agents with different agent ids each call plan_next(assigned_to="me") and pick up their own work without stepping on each other. Without assigned_to, any agent sees any pickable task.

Returns the task object or null.


List plans on the branch.

When to call: at the start of any session where you might be resuming prior work.

Parameters: status_filter? (active / completed / archived), ref?.


Fetch a plan with its full task list.

Parameters: plan_id, ref?.


List the tasks of a plan, flat.

Parameters: plan_id, ref?.


Move a plan and every task it contains from one branch (ref) to another. Task ids, statuses, proofs, and the plan-meta envelope are preserved bit-for-bit — only the ref changes.

When to call: promoting a sandboxed plan onto main, pulling someone else’s plan onto a feature branch to collaborate, or refiling work after a branch-strategy change. Refuses when source and target are the same ref, or when a plan with the same name already exists on the target ref.

Parameters: plan_id, target_ref, ref? (source branch, default main).


Close a finished plan with a required summary of what it achieved, the plan-level analog of a task’s proof. Refuses unless every task is done or abandoned. Prefer it to plan_complete, which force-closes a plan that still has open tasks.

When to call: the plan’s last task is finished. Afterwards, push the plan’s commits and open an MR for its branch.

Parameters: plan_id, summary, ref?.


Force-close a whole plan in one shot: abandons every still-open task with a reason, then closes the plan with a required summary. Use it when the remaining work no longer matters (scope cut, plan superseded). When every task is already finished, use plan_close; for progress, use plan_done per task.

Parameters: plan_id, summary, reason? (stamped on each abandoned task; default “Plan force-completed by user”), ref?.


Set plan status to archived. Soft — task data is preserved.

Parameters: plan_id, ref?.


Record that a task, when done, satisfies a task in another plan — a cross-plan dependency pointer (the substrate’s blocked_by is within-plan only). Advisory: it does not auto-close the target; completing the linked task surfaces a reminder to close the other one.

When to call: work in one plan closes out a task tracked in another.

Parameters: plan_id, task_id, target (as "plan/task"), ref?.


List in-progress tasks idle for N days (default 7) across active plans, most-stale first. The drift guard plan_start’s warning defends against.

When to call: resuming work or auditing state to catch tasks left silently in-progress. Complements plan_next, which only returns the next pending task and never shows what’s in progress.

Parameters: days? (default 7), ref?.


Describe a session: the workspace it lives in, the git branches it touched (with turn counts), and the plan tasks it worked on.

When to call: before acting on a session, to confirm it’s in the workspace you expect or to see what plans it advanced. A session belongs to the workspace of the repo it ran in; if this reports another one, you’re connected to the wrong workspace (reconnect with ?namespace=<name>, or set CTX_NAMESPACE for the CLI).

Parameters: session_id, ref?.

Returns: { session_id, namespace, present_in_this_workspace, provenance, links }. provenance and links are null for sessions recorded before they were captured.


Record that a session worked on a plan task. Links from commit messages that name a task (a (plan t-NNN) trailer) are derived automatically; this records the rest, such as a refactor with no trailer, or work discussed but not committed.

Parameters: session_id, plan, task (t-4 or t-004), note? (kept as the link’s evidence), ref?.

Returns: { status, plan, task, validated, already_linked }. validated: false means the plan or task isn’t in this workspace. The link is still recorded, but you’re probably connected to the wrong workspace.


Find which workspace holds a plan, by scanning every workspace.

When to call: you have a plan id but not its workspace, for example after a write was refused because no workspace could be derived, or when resuming with a plan id from another session.

Parameters: plan_id.

Returns: { plan_id, namespaces, hint }. Pass the workspace as CTX_NAMESPACE, --namespace or ?namespace=.


Find which workspace holds a task, by scanning every workspace for the task under its plan.

Parameters: plan_id, task_id.

Returns: { plan_id, task_id, namespaces, hint }.


Find registered canonical docs whose path/scope/answers/owner match a query (omit query to list all). Returns each doc’s path, status, scope, and what it answers — a pointer to the canonical .md file, not its content.

When to call: before reading files or writing a new doc, to find where a topic is already documented. Distinct from prime, which imports doc content into recall.

Parameters: query?, ref?.


Exact syntax, examples and gotchas for a ctx or asd feature, on demand (about 150-250 tokens), instead of carrying every tool’s full docs in context. The docs are compiled into the Hub, so they match the running code.

When to call: before using a feature whose exact syntax you’re unsure of. Omit topic for the grouped catalog of every feature, to discover ones you’d otherwise miss.

Parameters: topic?: a feature name (remember) or a phrase (“save a memory”); it fuzzy-matches. A topic that isn’t here may be an asd feature, and the response says so.


These tools mediate writes that shouldn’t be casual: deletion, branch creation, and trust controls. They exist as MCP tools so agents can introspect and act on the same surfaces a human reaches for in Lens or via ctx.

Forget a path by writing a rollback commit. The data isn’t physically removed — its history is preserved in blame — but get and recall will no longer surface it.

Parameters: path, reason?, ref?, personal? (forget from the personal namespace; a recall result’s namespace says which holds it).

When to call: when a fact is wrong, expired, or the user explicitly asks to forget it. Prefer forget over editing a fact in place — the audit trail tells the next session “this used to be true, here’s why we stopped believing it.”


List every branch with its current head commit id.

Parameters: none.


Create a new branch starting from from (default "main").

Parameters: name, from?.

When to call: before doing speculative or breaking work. Branches sandbox both code and memory — remember calls on a feature branch stay there until the branch merges. See MEMORY_BRANCH_SCOPING.md for the full model.


Merge source into target (default "main"). Returns {status: "ok", commit_id} on success, or {status: "conflict", conflicts: [...]} if the 3-way merge can’t proceed cleanly. Conflicting paths are returned structurally so the caller can write the desired value on target and re-attempt.

Parameters: source, target?, description?, reasoning?.

When to call: once a feature branch is ready to land back on the trunk. Mirror of the ctx merge CLI command.


List active taints / quarantines / watches across the graph.

Parameters: path_prefix?, effect?.


Check whether agent_id may write to path at the given confidence, given any active taints/quarantines. Returns can_write, effect (the strongest blocking effect, if any), and the matching taint id.

Parameters: path, agent_id, confidence?.

When to call: before any write you’re not certain is allowed — especially in multi-agent settings where another agent may have fenced off a path.


Apply a taint, quarantine, or watch to a path. kind selects the variant: taint (with an effect of warn/block/review/ isolate/advisory), quarantine (with optional authorized_agents whitelist), or watch (advisory tracking).

Parameters: path, kind, reason, plus effect?, authorized_agents?, min_confidence?, expires_at?.


Resolve (lift) an active taint, quarantine, or watch by id. The record isn’t deleted — it’s marked resolved with a reason for audit.

Parameters: taint_id, reason.


Pull-based scheduling primitives. Create a reminder now; call remind_me at any future checkpoint to retrieve what’s due. Reminders are ordered by priority then due_at. The autonomous flag controls whether execution requires user approval first.

Schedule a reminder for yourself or another agent.

Parameters: title, instructions, due_at (ISO 8601), priority? (critical|high|medium|low|minimal, default medium), autonomous? (default true), schedule? (once|interval|daily|weekly), commands?, refs?, tags?.


Return all currently actionable reminders (due or awaiting_permission), ordered by priority. Lazily promotes any pending reminders whose due_at has passed. Call this at session start and after completing any task.

Parameters: none.


List reminders with optional filters.

Parameters: status?, priority_at_most?, created_by?, due_before?, ref_id?, tags?.


Retrieve a single reminder by id, including its full execution history.

Parameters: id.


Defer a reminder to a later time without cancelling it.

Parameters: id, until (ISO 8601).


Approve a non-autonomous reminder for execution. Transitions awaiting_permission → due.

Parameters: id, approved_by?.


Cancel a reminder permanently. Use reminder_snooze to defer instead.

Parameters: id.


Mark a reminder as in-progress. Opens a partial execution record. Call just before acting; follow with reminder_record when done.

Parameters: id, agent_id?.


Record the outcome of an execution attempt. result is one of: success | failed | deferred | snoozed | cancelled. On success with a repeating schedule, resets to pending with a new due_at.

Parameters: id, result, notes?, task_id?, agent_id?.


Low-level read tools that mirror the engine’s HTTP surface. Agents generally reach for recall first; these are for cases where the agent already knows the path or wants to introspect provenance.

Read the JSON value stored at a path.

Parameters: path, ref?.


List every path under prefix on the given branch.

Parameters: prefix?, ref?.


Full-text substring search across every stored value on the branch.

Parameters: query, ref?.


Return the last N commits on a branch — newest first — with agent id, intent category, description, confidence, and tags.

Parameters: limit?, ref?.


Return the full provenance chain for a path: every commit that touched it, who wrote it, with what intent and confidence.

Parameters: path, ref?.


Compute the structural diff between two refs (branches or commits).

Parameters: ref_a, ref_b.



Code intelligence tools proxy read requests to an AgentStateDeveloper (ASD) server. They require the hub to be started with at least one ASD repo configured — either via --asd-repo (hub manages asd-serve processes) or --asd-url (you run asd-serve yourself).

Option A — hub-managed process pool (recommended):

Terminal window
ctxone-hub --http \
--asd-repo myproject=/home/alice/myproject/.asd-state.db \
--asd-repo otherlib=/home/alice/otherlib/.asd-state.db

The hub spawns one asd-serve process per repo on first use, kills it after 5 minutes of idle, and restarts it transparently on the next request.

Option B — pre-running asd-serve (manual):

Terminal window
asd-serve --db /home/alice/myproject/.asd-state.db &
# Prints: listening on 127.0.0.1:4120
ctxone-hub --http --asd-url myproject=http://127.0.0.1:4120

Multiple --asd-repo / --asd-url flags can be mixed. The repo name you supply becomes the value for the repo parameter in every code tool call.


List all ASD repos registered with this hub.

Parameters: (none)

Returns: JSON array [{ name, url }].

// response
[
{ "name": "myproject", "url": "http://127.0.0.1:54321" },
{ "name": "otherlib", "url": "pool:otherlib" }
]

url is the resolved endpoint for pre-running repos; pool-managed repos show pool:<name> until the process is first requested.


Search code symbols by concept or keyword across name, signature, doc comment, file path, and ledger summaries. Returns ranked results.

Use this for feature archaeology when you don’t know the exact symbol name.

Parameters:

NameTypeDefaultDescription
querystring—Search terms (concept, function name, effect label, …)
repostringfirst registeredRepo name from code_repos. Omit when only one repo is registered.
kindstring—Filter to function, method, class, module, variable
languagestring—Filter to python or typescript
limitnumber20Max results

Returns: JSON array of matching symbol records with relevance scores.

// request
{ "query": "charge card payment", "repo": "myproject", "limit": 5 }
// response
[
{
"qname": "payments.charge_card",
"kind": "function",
"file": "payments.py",
"signature": "def charge_card(user_id: str, amount: float)",
"score": 0.92
}
]

Read a symbol by qualified name. Returns the symbol, its declared and transitive effects, and all ledger decisions — the full context needed to reason about a code unit.

Parameters:

NameTypeDefaultDescription
qnamestring—Fully-qualified symbol name (e.g. payments.charge_card)
repostringfirst registeredRepo name

Returns: { symbol, effects, ledger }.

// request
{ "qname": "payments.charge_card", "repo": "myproject" }
// response
{
"symbol": {
"qname": "payments.charge_card",
"kind": "function",
"file": "payments.py",
"signature": "def charge_card(user_id: str, amount: float)"
},
"effects": {
"declared": [
{ "effect": "io.db.write", "note": "INSERT INTO charges" },
{ "effect": "log" },
{ "effect": "throw" }
],
"transitive": [],
"verification": { "status": "unverified" }
},
"ledger": [
{
"kind": "hazard",
"summary": "boundary at 10000 is undocumented",
"tags": ["approved", "approved-by:alice@example.com"]
}
]
}

List symbols that call the given symbol (inbound call edges).

Parameters:

NameTypeDefaultDescription
qnamestring—Target symbol
repostringfirst registeredRepo name

Returns: JSON array of calling symbol records.

// request
{ "qname": "payments.charge_card", "repo": "myproject" }
// response
[
{ "qname": "driver.main", "kind": "function", "file": "_driver.py" }
]

List symbols called by the given symbol (outbound call edges).

Parameters:

NameTypeDefaultDescription
qnamestring—Target symbol
repostringfirst registeredRepo name

Returns: JSON array of callee symbol records.

// request
{ "qname": "driver.main", "repo": "myproject" }
// response
[
{ "qname": "payments.charge_card", "kind": "function", "file": "payments.py" },
{ "qname": "payments.get_balance", "kind": "function", "file": "payments.py" }
]

Map the service edges between every repo registered with ASD: a client call in one repo matched to the route that serves it in another. It runs asd repo edges over the shared repo registry, so index each repo first to keep its contracts current.

When to call: before a cross-service change, or to find hidden dependencies between repos. For one endpoint’s blast radius, use code_impact; this returns every edge.

Parameters: none.

Returns: every cross-repo edge, as JSON from asd.


Given an endpoint you’re about to change, return its consumers in other repos and the invariants and hazards each consumer’s own ledger records: what breaks if it changes, and what those callers were promised. It runs asd repo impact <target>.

Parameters: target: a route-handler qname (get_orders or app.routes.get_orders) or a contract (http:GET /api/orders/{}).

Returns: the consumers and their invariants and hazards, as JSON from asd.


Return the active ASD repo for this session (set via set_active_repo), or null if none is set. Also returns the list of registered repo names so the agent can pick one.

Parameters: none.

Returns: { "active_repo": <name|null>, "known_repos": [ … ] }.


Set the active ASD repo for this session. Subsequent code tools (code_search, code_read, callers_of, callees_of) default to this repo when their repo parameter is omitted — so you don’t repeat repo on every call in a single-repo session.

When to call: at the start of a session focused on one registered repo. Errors if the repo isn’t registered; pass an empty string to clear.

Parameters: repo (registered repo name; empty string clears).


These tools round out the 65-tool surface. They follow the same request/response conventions as the tools above; call the help tool (ctx help <name>) for exact parameters and examples on demand.

Help & docs

  • help — on-demand instruction disclosure: returns per-feature syntax, examples, and gotchas for a ctx (or asd) tool, or the full catalog. Backed by a shared cross-tool registry so ctx and asd resolve each other’s topics.
  • docs_find — search docs that were imported into memory (via prime / ctx prime) and return the best-matching sections.

Plans (extended)

  • plan_link — link a plan to a related plan, session, or task.
  • plan_stale — surface plans that have gone stale (untouched / drifted).
  • plan_close — close a plan out (distinct from plan_complete / plan_archive).

Drafts — stage proposed memory writes for review before they land:

  • draft_stage — stage a proposed memory write without committing it.
  • drafts_list — list currently staged drafts.
  • draft_promote — promote a staged draft into committed memory.
  • draft_discard — discard a staged draft.

Sessions

  • session_segments — list the segments (topic arcs) of a session.
  • session_info — describe a session: its namespace, the branches it touched, and the plans/tasks it advanced.
  • session_link_plan — associate a session with a plan.