Agent integration

ctxindex integrates with agents through its CLI. Claude Code, Codex, OpenClaw, and any other agent that can execute shell commands can use the same deterministic interface.

Why the CLI is the integration surface

There is no ctxindex MCP server. The CLI already provides the properties an agent integration needs:

• deterministic commands and --json output;
• stable exit codes for branching and recovery;
• one provider-neutral vocabulary across mail, calendars, files, and extension-defined domains;
• registry-derived descriptions of loaded Profiles, Source Adapters, fields, formats, and Actions.

An MCP server or agent-specific adapter would duplicate that contract and introduce another surface that could drift. Keep agent policy, approval, and multi-step reasoning in the agent; use ctxindex for context access and typed provider Actions.

Start by discovering the loaded interface

Do not hard-code kinds, Source options, formats, or Action schemas when the registry can report them.

ctxindex describe --full --json
ctxindex source list --json
ctxindex describe profile communication.message --json
ctxindex describe adapter google.calendar --json

describe is especially important when external Extensions are loaded: they can add Profiles and Source Adapters without adding provider-specific commands.

Compose a read workflow

ctxindex search "quarterly planning" \
  --realm company \
  --kind mail \
  --json

ctxindex get 'ctx://01J00000000000000000000000/message/stable-message-id' --json

ctxindex thread get 'ctx://01J00000000000000000000000/message/stable-message-id' --json

Compose a Draft workflow

Inspect the Action before generating input:

ctxindex action describe communication.message.draft.create \
  --source company-mail \
  --json

Then validate the agent's proposed content against the returned schema and invoke the Action through one explicit mailbox Source:

cat > /tmp/ctxindex-draft.json <<'JSON'
{
  "to": ["recipient@example.com"],
  "subject": "Project update",
  "bodyText": "The project is ready for review."
}
JSON

ctxindex action run communication.message.draft.create \
  --source company-mail \
  --input /tmp/ctxindex-draft.json \
  --json

The result includes the normalized Draft Resource Ref. Text composed in an agent conversation is not a Draft until this provider-persisting Action succeeds. ctxindex does not send mail.

For a threaded reply, first use get to materialize a complete parent in the same selected Source. Then use the strict reply branch; it accepts only the parent Ref and body text:

ctxindex get 'ctx://01J00000000000000000000000/message/stable-message-id' --json

ctxindex action run communication.message.draft.create \
  --source company-mail \
  --input '{"replyToRef":"ctx://01J00000000000000000000000/message/stable-message-id","bodyText":"Thanks for the update."}' \
  --json

Reply Draft updates require the complete local Draft and parent in that Source and must repeat the Draft's immutable replyToRef. The reply update branch accepts exactly {ref, replyToRef, bodyText}; it does not accept recipient or subject overrides. See Mail workflows for both complete update shapes.

Agent execution rules

• Request --json on commands that expose it, and parse the JSON instead of scraping human output.
• Check the process exit code before consuming output.
• Keep Source selection explicit for Actions.
• Preserve per-origin warnings from search; one provider failure can coexist with valid results from other origins.
• Use describe output as the authority for loaded vocabulary and input schemas.