KeiSeiKit-1.0/docs/encyclopedia/multi-cli-agents.md

Multi-CLI agent invocation

Cross-LLM agent execution. Same agent definition, different backend. Same DNA, swap the brain. KeiSeiKit is no longer Claude-Code-only.

KeiSeiKit agents are markdown files. Any LLM CLI that takes a prompt can host them. Three call shapes:

kei agent <name> "<task>"                # DNA-resolved (manifest → primary → claude)
kei agent --on=<backend> <name> "<task>" # override DNA
kei run-via <backend> <name> "<task>"    # explicit backend (no DNA lookup)

Backends — smoke-tested 2026-05-26

Backend	CLI	Flag	Smoke	Notes
claude	claude	-p	✅	Claude Code, native --agent flag
grok	grok	--print	✅	xAI Grok Build TUI, native --agent flag
agy	agy	--print	✅	Google Antigravity (Gemini models). Alias: antigravity
copilot	copilot	--prompt	✅	GitHub Copilot CLI (@github/copilot)
kimi	kimi	TUI-only	⚠	No print mode — launcher saves prompt to tmpfile + opens TUI for paste. kimi acp JSON-RPC integration is future work.
codex	codex	-p	—	OpenAI Codex (register-only; not installed locally)

Run kei run-via list to see installed backends, current primary, and agent names.

DNA — agent prefers a provider

Add provider to the agent manifest:

# _manifests/my-agent.toml
name = "my-agent"
provider = "grok"     # preferred backend; optional
model = "grok-2"      # advisory; informs choice but not yet sent through

The assembler emits it into frontmatter:

---
name: my-agent
provider: grok
---

Resolution order (each falls through if previous returns nothing):

1. --on=<backend> flag on the command line
2. provider: field in agent manifest
3. ~/.claude/config/primary.toml (set via kei primary <backend>)
4. Default: claude

Primary — your default LLM

kei primary                # show current primary (and fallback)
kei primary grok           # set default to Grok
kei primary claude         # back to Claude Code

kei primary writes ~/.claude/config/primary.toml. Any agent without its own provider: field will resolve to this. This is the lever to "swap out Claude Code as the primary shell" — set primary to grok, and every kei agent <name> runs on Grok.

Usage examples

# DNA mode (manifest's provider, or primary, or claude):
kei agent critic "review src/auth.rs"

# Override DNA — try the same agent on a different model for a second opinion:
kei agent --on=grok critic "review src/auth.rs"
kei agent --on=agy  critic "review src/auth.rs"
kei agent --on=copilot critic "review src/auth.rs"

# Explicit backend, no DNA lookup (legacy):
kei run-via grok critic "review src/auth.rs"

# Point at an arbitrary agent file:
kei agent --on=grok --file=/tmp/my-agent.md "do the thing"

# Native --agent flag (grok/claude only):
KEI_NATIVE_AGENT=1 kei agent critic "review src/auth.rs"

How it works

1. Resolves backend from DNA (see above).
2. Reads ~/.claude/agents/<agent-name>.md (assembler-generated prompt).
3. Strips YAML frontmatter.
4. Composes with task: <agent prompt>\n\n---\n\nTASK FOR THIS RUN:\n<task>.
5. Execs the backend's non-interactive CLI with the composed prompt.

No agent file is modified. No new tokens are issued — subscription authentication is whatever each CLI uses (its own login / config dir).

When to use each

This is a tool, not a recommendation. Each backend has different strengths; the substrate is agnostic about which you pick. Pick by:

• Familiarity — the CLI you already use day-to-day.
• Subscription cost — burn the one with cheaper marginal cost first.
• Specific feature — e.g. grok --agent for native sub-agent switching mid-conversation; agy --sandbox for terminal restriction.
• Independent second opinion — same agent, different model, see if conclusions diverge.

Orchestrator picker — kei no longer hardcodes claude

Without args, kei reads ~/.claude/config/primary.toml and execs that CLI. The picker lets you change it interactively:

kei pick               # interactive menu → set primary → launch it
kei                    # splash → exec the configured primary
kei --on=grok          # one-shot launch of grok (does NOT change primary)
kei primary grok       # set default to grok (no launch)
kei primary            # show current primary

The splash shows primary CLI: <backend> so you always know which orchestrator will start. If the chosen primary isn't installed, kei prints the install command and offers kei pick as recovery.

Cross-CLI sub-agent spawn via MCP — spawn_agent

kei-mcp exposes a built-in spawn_agent MCP tool. Any CLI that connects to it as an MCP client can invoke KeiSeiKit agents on any backend, no matter what the orchestrator is:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "spawn_agent",
    "arguments": {
      "name": "critic",
      "task": "review src/auth.rs for race conditions",
      "on": "grok"
    }
  }
}

Internally spawn_agent shells out to kei-agent-cli.sh with the same DNA resolution as kei agent. The on argument is optional — without it, the backend is picked from the agent's manifest, then primary.toml, then claude.

Why this matters: Claude Code has a native Agent tool for sub-agent spawning. Grok / Antigravity / Copilot / Kimi do NOT have that surface natively — but they all support MCP. With spawn_agent exposed via kei-mcp, every backend that speaks MCP gets KeiSeiKit's sub-agent capability. So when Grok is your orchestrator, it can still spawn critic on Claude (or code-implementer on Antigravity, or anything else) — the orchestrator choice no longer caps your sub-agent surface.

Wire kei-mcp into the orchestrator's MCP config (each CLI has its own):

CLI	MCP config
claude	~/.claude/settings.json mcpServers block
grok	~/.grok/config.json (or check grok --help)
agy	~/.antigravity/mcp.json (check agy plugin list)
copilot	~/.copilot/mcp.json (check copilot --help)
kimi	kimi mcp add subcommand

Point each at <kit>/_primitives/_rust/target/release/kei-mcp (built via cargo build -p kei-mcp --release).

Rule enforcement caveat (READ THIS)

KeiSeiKit hooks (numeric-claims-guard, citation-verify, no-github-push, safety-guard, push-to-main, etc.) are Claude Code-side: PreToolUse:Bash / :Edit / :Write events that fire inside Claude Code's process. They do not propagate to grok / agy / copilot / kimi.

That means:

• Prompt-level rules (the agent's instructions inside the .md) DO carry through — the agent reads Constructor Pattern, Evidence Grading, No Hallucination, etc. as part of its system prompt on any backend.
• Tool-level enforcement (hard-deny on git push github.com, citation guard, etc.) only applies on the claude backend. Other backends' tool surfaces are governed by THEIR own hooks/policies.

If you need true rule-enforcement on a non-claude backend, the path is the MCP server (_primitives/_rust/kei-mcp/): registers KeiSeiKit primitives as MCP tools that the other CLI invokes. Tool-side policies travel with the MCP wrapper, not with the CLI.

Adding a new backend

1. Add a [backend.<name>] table to _primitives/cli-backends.toml.
2. Add a case arm in scripts/kei-agent-cli.sh backend_bin() and backend_invoke() for the new CLI's print-flag.
3. Add a row to the smoke-test table above (state PASS/FAIL/PARTIAL).

What it is NOT

• Not a router — picks no backend for you; you (or DNA) ask, it dispatches.
• Not a federation — each backend runs independently with its own context; there is no cross-backend state.
• Not a rule-enforcement layer — hooks only fire on the claude backend (see caveat above). For non-claude rule enforcement use MCP server.
• Not a wrapper around the backend's tool surface — what the CLI can do (Bash, file edits, MCP, etc.) is determined by that CLI, not KeiSeiKit. The substrate only ships the prompt.

Related

• _primitives/_rust/kei-llm-router/ — Beta-posterior router for programmatic model selection inside Rust code (a different layer).
• _primitives/_rust/kei-mcp/ — MCP server that exposes KeiSeiKit primitives to ANY MCP-compatible client (Cursor / Continue / Zed / Aider / Cline / Windsurf / OpenClaw).