List registered projects. Defaults to the current workspace.

workspace:

• None (default) → projects in the current workspace (CMCP_WORKSPACE env > config.toml [user].last_workspace > "default"). This matches the orchestrator's "what am I working on right now" expectation.

• "__all__" (or "*") → every registered project across all workspaces

• any other name → that workspace's members

Return the registry entry for one project.

This is metadata only — the working directory, adapter, description, and tags. Dispatch work via dispatch_query to actually hit the agent.

What actually happened in a project, where it stands, what's live.

Use this when the user returns to a project after time away, asks "what's the state of X?", or before dispatching into a project you haven't touched this session. Unlike dispatch_history / orchestration_history — which only know about work that went through central-mcp — a pulse reads the repository itself, so direct commits, interactive agent sessions, and manual edits show up too.

Sections (each degrades independently, with a reason when unavailable — never assume a missing section means "nothing happened"):

• git: branch, upstream ahead/behind, working-tree dirt with a bounded file sample, and the last commits commits.

• dispatches: in-flight work, the last history outcomes with prompts and previews, and all-time success/failure counts. stale holds rows still marked running after hours — a crashed or restarted server never wrote their terminal state, so report them as unfinished, not as live work.

• sessions: resumable agent conversations, when the project's agent has a session reader.

• pull_requests: open PRs via gh. The only network call here — pass include_pr=False when sweeping many projects.

Nothing is stored: every call recomputes from source. Synthesize the result into a short narrative ("since your last visit … currently … next …") rather than reciting the fields back to the user.

Record what was done / what was left / what comes next for a project.

This is the durable memory a return briefing is built from. project_pulse reads the repository and can tell anyone what is true; only you can record what was meant — why an approach was abandoned, what is half finished, what should happen next. None of that is recoverable from git later, so it is lost unless it is written down now.

When to call it — this matters more than the arguments. Call it at the end of any stretch of real work in a registered project, whether or not that work came through central-mcp. A session someone opened directly in the repo is the most common case and the one most likely to be forgotten. Also call it when you learn something that changes the plan, and especially when you abandon an approach: "tried X, it fails because Y" leaves no commit, no diff, no trace at all, and is the single most valuable thing this file can hold.

Do not call it for trivia (a typo fix, a question answered) — an over-full ledger gets skimmed, which is the same as empty.

Arguments: note — free text: what happened, what was left, what was learned. name — registered project name. Omit if passing cwd. cwd — a path inside the project; resolved to whichever project owns it. Use this when you know where you are but not what it is registered as. next_step — one line: what should happen next. A briefing offers this back for confirmation, so write it as an instruction to a future reader, not a note to yourself. source — "agent" when you are recording your own work (default), "user" when you are writing down what the human just told you. Keep these honest: the ledger's whole value is that a reader can tell a first-hand record from a relayed one.

Dispatch a prompt to a project or workspace. NON-BLOCKING.

name: project name, or @workspace to fan-out to all projects in that workspace. When a workspace is targeted, each member project is dispatched independently and a list of dispatch_ids is returned.

Spawns a one-shot subprocess (e.g. claude -p "..." --continue) in the project's cwd and returns immediately with a dispatch_id (<100ms).

agent (optional): override the project's registered agent for this one dispatch only. Useful for e.g. sending a design-heavy task to a different agent without mutating the registry. Registry is unchanged.

fallback (optional): list of agent names to try in order if the primary agent exits non-zero (e.g. token/rate limit, crash). If omitted, the project's saved fallback from the registry is used. Pass an empty list [] to explicitly disable fallback for this dispatch.

permission_mode controls how the agent handles permission prompts:

• "bypass" — skip all prompts (default for new projects)

• "auto" — claude-only; classifier-reviewed actions (Sonnet/Opus 4.6 only)

• "restricted" — no skip flag; agent may fail on operations needing approval

• None (default): use the project's saved mode, or "bypass" for new projects. The resolved value is saved to the registry for future dispatches.

session_id (optional): one-shot override for conversation resumption.

• Given → resume that specific session (agent-specific flag: claude -r <uuid>, codex resume <id>, droid -s <uuid>, opencode -s <uuid>, gemini --resume <index>). After this dispatch the agent's own "resume latest" mechanism picks up the just-used session, so subsequent default dispatches continue from it without restating the id.

• None (default): use the project's saved session_id if any (persistent pin), otherwise fall back to the agent's "resume latest" flag. Droid has no headless "resume latest", so absence of a session_id means a fresh session on every droid dispatch.

language (optional): one-shot override for the response language.

• A non-empty string (e.g. "Korean", "ko", "Français", "fr") → prepend a "Respond to the user in ." directive to the prompt.

• "" (empty string) → suppress the project's saved language for this call (fall back to agent default, usually English) without mutating the registry.

• None (default) → use the project's saved language, set via update_project(language=...). If unset, no directive is added.

Poll a background dispatch started by dispatch_background.

Returns {status: "running", elapsed_sec} while the subprocess is alive, or the full result (same shape as dispatch_query's return value) once it has exited.

Read what a dispatch has printed so far, without waiting for it to finish.

check_dispatch returns output only after the agent exits. Use this while a dispatch is still running — to answer "what is it doing right now?", or to look closer when output.state is quiet.

Arguments: dispatch_id — the id dispatch returned. since — the next_since value from your previous call, to get only newer lines. Omit it on the first call. A plain ISO 8601 timestamp is accepted too. max_lines — most lines to return (default 50). When more are new, you get the newest and skipped counts the rest.

Returns lines (oldest first; each has ts, stream, agent, text), skipped, next_since, the dispatch status, and output:

state streaming | quiet | no_output_yet | exit_only last_output_age_sec seconds since the newest line output_lines lines emitted so far

Read output.state before you report on a silent dispatch:

• exit_only — this agent prints only when it exits (claude does). No lines is its normal state. Do not report it as stuck.

• quiet — the agent printed before and has printed nothing for 15 minutes. It may be stuck. Tell the user; do not cancel on your own.

• no_output_yet — nothing printed so far. Report the elapsed time.

Lines are raw agent output (often JSON events) — summarize them for the user; do not paste them. Once status is no longer running, call check_dispatch for the final result.

List active and recently completed background dispatches, including those started by other central-mcp processes (shared state via ~/.central-mcp/dispatches.db).

status (optional): filter to one of running / complete / error / timeout / cancelled, or the alias failed — anything that ended badly (error, timeout, or complete with ok=false; cancelled is deliberate and excluded).

since (optional): ISO 8601 timestamp; only dispatches whose finished_at is strictly later are returned (still-running rows are unaffected by this filter).

Together these back the resident-agent failure watch without central-mcp holding subscriber state: call list_dispatches(status="failed", since=<watermark>), alert on whatever comes back, and advance your watermark to the max finished_at you saw. The strict-greater-than filter means an unchanged watermark never re-alerts the same failure.

Abort a running background dispatch. No-op if already finished.

Sets a cancel flag so _run_bg stops before the next fallback attempt, then terminates the current subprocess. The background thread finalizes the status to "cancelled".

Append a project to registry.yaml.

Registration is immediate. The agent is not spawned until the next dispatch call. If the agent is codex, also adds a trusted- directory entry to ~/.codex/config.toml so codex exec doesn't refuse to run in that path.

language (optional): preferred response language for dispatches (e.g. "Korean", "ko", "Français", "fr"). When set, every future dispatch prepends "Respond to the user in ." to the prompt. Omit or leave empty for the agent's own default (English).

workspace (optional): if given, also add the project to this workspace.

Reorder the registry's projects list.

order is a sequence of project names; those names move to the front of the registry in the given order. By default any project not named in order keeps its original relative position after the reordered prefix, so a partial reorder is always safe (no need to enumerate every project). Pass strict=True to require order to list every registered project exactly once.

Raises an error for unknown names, duplicates, or (in strict mode) missing ones. The reorder persists to registry.yaml immediately, but panes in an already-running cmcp tmux / cmcp zellij session don't rearrange live — rerun the multiplexer command to see the new layout (auto-teardown since 0.6.8 makes this a one-step flow).

Remove a project from registry.yaml.

Update an existing project's fields. Omitted args stay unchanged.

Use this to permanently change a project's primary agent, edit its description/tags, flip its permission_mode preference, set a fallback chain of agents to try when the primary fails (e.g. token limits hit), pin a specific session_id, or set a preferred response language for dispatches.

language behavior:

• A non-empty string (e.g. "Korean", "ko", "Français", "fr") → every future dispatch prepends "Respond to the user in ." to the prompt. One-shot dispatch(language="...") still overrides.

• "" (empty string) → clear the saved language; dispatches fall back to the agent's own default (English).

• None (omitted) → leave the saved language untouched.

session_id behavior:

• A non-empty string → all future dispatches without an explicit session_id will resume that session (useful for droid, which has no headless "resume latest", and for guarding other agents against ambient-drift when interactive sessions share the cwd).

• "" (empty string) → clear the pin, returning to the agent's default resume-latest behavior.

• None (omitted) → leave the pin untouched.

Agent names in agent and fallback are validated. permission_mode must be one of "bypass", "auto", "restricted". If any value is invalid the registry is not touched.

List resumable agent conversation sessions for one project.

Queries the project's agent for sessions saved in its own store scoped to the project's cwd (filesystem scan for claude/codex/droid, subprocess call for gemini/opencode). Returns at most limit sessions sorted by most-recently-modified.

Each session dict carries id, optional title, optional bounded preview, optional created / modified (ISO 8601), and optional turns. preview is a short best-effort snippet from the session contents (often the first recognizable user message, or a backend's own title-like summary) so callers can distinguish threads without resuming them. Use the returned id with dispatch(session_id=...) to resume a specific thread as a one-shot — the agent's own resume-latest mechanism picks the just-used session up for subsequent default dispatches, so the id rarely needs to be restated.

pinned echoes the project's currently saved session_id (if any) so the orchestrator can mark it in UI.

Return the current content of ~/.central-mcp/user.md and the available preference sections.

The file holds only user-authored rules — there is no scaffolded template, so an empty content means "no preferences set yet". The response also carries available_sections (valid section values for update_user_preferences) and examples (a hint of what the user might want to set, surfaced when the user asks what's configurable). Call this before update_user_preferences so you can merge new rules with anything already saved.

Persist a user preference to ~/.central-mcp/user.md.

Call this when the user expresses a PERSISTENT preference — reporting style, language, routing hints, or process rules. Applied every future session. NOT for one-off turn instructions; those need no persistence.

section — one of: "Reporting style" how to format and present responses "Routing hints" which agents/projects to prefer for task types "Process management rules" concurrency or approval constraints "Other preferences" anything else

content — new full text for that section (replaces its existing content; other sections are untouched). Plain language, bullet points recommended: "- Switch to Korean for all responses." "- Prefer claude for architecture.\n- Use codex for shell scripting."

Tip: call get_user_preferences() first so you can merge old and new content.

Return the last N completed/failed/cancelled dispatches for one project.

Reads ~/.central-mcp/logs/<project>/dispatch.jsonl and extracts terminal events (merged with their matching start so each record carries both the prompt and the outcome). For a cross-project portfolio summary, use orchestration_history instead.

Pre-rendered portfolio summary for push delivery — paste digest_markdown VERBATIM; do not re-summarize it.

Built for the resident-agent digest loop (a cron that forwards the portfolio state to chat every morning), and equally usable by a terminal orchestrator when the user asks for a daily/weekly recap. The rendering is fixed server-side for the same reason token_usage.summary_markdown is: an LLM re-composing the report daily makes every day look different, and omissions are invisible.

Data spine is the pulse, so — unlike orchestration_history — work that never went through central-mcp (direct commits, interactive sessions) is counted. Sections:

• active: projects with activity inside the window (commits, dispatch outcomes, in-flight count, uncommitted files)

• warnings: failed dispatches in the window, dispatches stuck in running for hours (report as unfinished, never as live), and quiet projects with uncommitted work sitting in them

• quiet: everything else, longest-idle first

• quota: compact per-agent subscription windows (when include_quota)

workspace: same semantics as list_projects — None for the current workspace, a name, or "__all__" for everything. since_hours: activity window (24 daily; 168 weekly). quiet_days: idle threshold for the uncommitted-work warning.

Nothing is stored; every call recomputes from source. Scheduling and alert watermarks belong to the caller (list_dispatches with status="failed" + since covers the alert half).

Portfolio-wide snapshot: in-flight dispatches + recent milestones + per-project stats.

Answers "how is everything going?" without per-project polling. Pulls:

• in_flight: currently running dispatches (from memory)

• recent: last N timeline milestones (dispatched/complete/ error/cancelled) across all projects, newest first

• per_project: counts of succeeded/failed/in-flight per project within window_minutes (or all-time if not given)

• registered_projects: registry snapshot for context

workspace (optional): when given, filters recent milestones, per-project stats, and in-flight dispatches to only projects in that workspace.

include_archives (optional): when True, attach archived_summaries — one compact aggregate per rotated timeline file — so callers get a window onto long-past activity without raw records bloating context. Live timeline.jsonl is always included.

Portfolio-wide token-usage aggregation (SQL over tokens.db) plus a normalized per-agent subscription quota snapshot.

Separated from orchestration_history so token monitoring can evolve independently of event/dispatch history (and eventually power a live token pane). Reads are windowed by the user's configured timezone.

period: today | week | month | all project: restrict to one project name (mutually exclusive with workspace; if both are given, project wins) workspace: restrict to projects in a workspace (via registry) group_by: project | agent | source — how breakdown is keyed include_quota: include per-agent subscription window utilization (default True). Cached 60s in-process; opt out for fast bulk polling. include_summary: include a pre-rendered markdown HUD (summary_markdown) the orchestrator can surface verbatim (default True). Uses Unicode block bars, emoji color markers (🟢 < 50%, 🟡 50–89%, 🔴 ≥ 90%), and fixed-width alignment inside a fenced code block. Disable to save tokens when you only need the raw structured data.

Returns: { "ok": True, "period": "today", "window": {"start": ISO, "end": ISO} | {"start": null, "end": null}, "group_by": "project", "breakdown": { key: {dispatch, orchestrator, total, input, output} }, # When group_by="project", # tokens that aren't tied to # any registered project # (orchestrator-session usage) # are bucketed under the # special key "ORCHESTRATOR", # always emitted first in the # breakdown. "total": {dispatch, orchestrator, total, input, output}, "quota": { # only when include_quota=True "claude": {"mode": "pro", "five_hour": {"used_pct", "resets_in"}, "seven_day": {"used_pct", "resets_in"}}, "codex": {"mode": "chatgpt", "primary": {...}, "secondary": {...}}, "gemini": {"mode": "auth_only", "auth_type": ..., "note": ...}, "fetched_at": ISO, "cached": bool, }, "summary_markdown": "Token Usage — ...\n```text\n..." # only when include_summary=True # — pre-rendered HUD; surface # verbatim, do not re-format. }