ctx_status

ctx_status answers “what is this project wired up to, and what have I not pushed yet”. It reads local files only — no network call — so it is the safe first thing to call when a push or pull just failed and the agent needs to know why.

When the agent calls it

The description is deliberately flat, because this tool is diagnostic rather than conversational: “Show local .contexo status: server, repo, auth, local page count, last pull sha, never-pushed pages.” Models reach for it when the user asks whether they are logged in, which repo this project syncs to, or whether anything is unshared.

Parameters

ctx_status takes no parameters.

Response

Eight lines of plain text, always in this order:

Server: https://api.contexo.live
Repo: acme-api
User: dev <dev@example.com>
Authenticated: true
Local pages: 12
Last pull: a4b2c1d3
Never-pushed pages: 2
Pending capture buffers: 1

Reading each line:

Line	Meaning
Server	server_url from the project config, or (none)
Repo	repo_id from the project config, or (none)
User	Name and email from stored credentials, or (anonymous)
Authenticated	true when credentials exist and produce a bearer token
Local pages	Every parseable page in the store, whatever its origin
Last pull	last_pull_sha shortened to 8 chars, or (never)
Never-pushed pages	Pages with no entry in page_shas — never pushed and never pulled
Pending capture buffers	Unarchived session buffers under raw/sessions/_pending/

Two of those are easy to misread:

• “Never-pushed” is derived from sync state, not from content. A page counts as never-pushed only when its path is absent from .contexo/.sync/state.json. A page you edited locally after pushing it is not counted here — nothing in this tool compares local bytes against the server.
• Pending capture buffers predict the distill handshake. The count is every unarchived buffer, whatever its age. ctx_push only pauses when the most recent one was modified in the last 6 hours and holds at least one turn, and the batch contains a concept or analysis page. A zero here is the reliable half: no buffers means a push will go straight through.

Request and response

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ctx_status",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Server: https://api.contexo.live\nRepo: acme-api\nUser: dev <dev@example.com>\nAuthenticated: true\nLocal pages: 12\nLast pull: a4b2c1d3\nNever-pushed pages: 2\nPending capture buffers: 1"
      }
    ]
  }
}

There is no error path. Missing config, missing credentials, and an empty store all render as their placeholder values rather than failing, so the tool is always safe to call inside a Contexo project. Outside one there is nothing to call: with no .contexo/ the server runs dormant and advertises zero tools.

CLI equivalent

ctx status covers most of the same local facts, adds a network check the MCP tool does not do, and drops one field.

ctx status

Initialized: yes
Server: https://contexo.example.com
Repo: acme-api
Authenticated: yes (legacy API key)
User: dev <dev@example.com>
Local pages: 1
Last pull: (never)
Pages never pushed: 0
Pages drifted on server: 0

Before a remote is configured:

ctx status

Initialized: yes
Server: (none — run 'ctx remote set <url>')
Repo: (none — run 'ctx remote set-repo <id>')
Authenticated: no
Local pages: 0
Last pull: (never)
Pages never pushed: 0

Flag	Type	Default	Description
--no-drift	bool	false	skip the per-page server-drift check (faster; offline-friendly)

Differences worth knowing:

• The CLI checks server drift; ctx_status never does. ctx status asks the server for the current sha of every tracked page and lists the ones that moved — the Pages drifted on server line, skippable with --no-drift. The MCP tool makes no network call at all, so an agent that needs drift information reads ctx://wiki/<slug> (which prepends a <DRIFT_NOTICE>) or calls ctx_diff.
• The CLI reports initialization. Outside a Contexo project it prints Not initialized (run 'ctx init') — a state the MCP tool can’t be in, since the server runs dormant with zero tools when there is no .contexo/.
• The CLI does not count capture buffers. Pending capture buffers has no ctx status equivalent; ctx capture status reports pending buffers separately.
• Field labels differ slightly: the CLI says Pages never pushed, the tool says Never-pushed pages, and the CLI adds Initialized: and the auth kind (yes (legacy API key)).

See ctx status for the full command reference and drift and conflicts for what to do when pages have moved.