Status: Implemented. This document specifies the pi backend for raymond and records the rationale for adding it. pi is the sole planned non-Claude backend — codex, gemini, cursor, and copilot are postponed indefinitely; the reasoning is below under "Why pi, and only pi."
For background on the existing Claude Code integration that this feature parallels, see code-structure.md and "Backend abstraction (where pi plugs in)" below.
Two strategic principles drive the choice — coverage and stability — and a third practical observation (mechanical fit with raymond's existing surface) seals it.
Raymond's existing Claude Code path uses subsidized Anthropic tokens via a Claude Code subscription — the discounted rate that makes Claude usage economical for long-running workflows. Pi covers the rest of the provider landscape on equivalently favorable terms:
- OpenAI — pi can drive an OpenAI Codex subscription, getting the same discounted-token economics that Codex CLI users enjoy.
- Microsoft / enterprise — pi can drive a GitHub Copilot subscription, which is the path enterprises typically have budget and approval for.
- Google and others — pi's multi-provider selector
(
--provider <name>,--model <pattern>,--thinking <level>) handles the remaining providers via their own credentials.
Notably, pi driving Claude does not use the Claude Code subscription — it falls through to retail Anthropic API pricing ("extra usage"). That's why raymond keeps its own direct Claude Code integration rather than routing Claude through pi: each backend is responsible for the provider it serves cheapest.
Between Claude Code (for Anthropic, subsidized) and pi (for everyone else, subsidized where the provider offers it), the practical provider matrix is covered. Adding codex / gemini / cursor / copilot as first-class backends would mostly duplicate routes pi already covers, at the cost of more integration surface to maintain.
Model behavior will always drift — that's an unavoidable cost of building on LLMs. What raymond can avoid is a second layer of drift on top: the layer introduced by an opinionated harness sitting between raymond and the model.
Claude Code, Codex CLI, Gemini CLI, Cursor, and Copilot CLI all have
their own opinions about prompt shaping, permission flows, tool
surfaces, and stream-event semantics. Those opinions change. A raymond
workflow that works today against one of those harnesses can fail
tomorrow when the harness changes its mind about, say, how <tool_use>
blocks are emitted or which tools auto-approve.
Pi is deliberately bare-bones-but-extensible. Its protocol surface
(--mode json, --mode rpc) is small, its prompt handling is
unopinionated, and its philosophy is to expose the provider's behavior
rather than reshape it. That makes pi a more stable foundation for
raymond to build on. Raymond still inherits model drift via pi, but it
does not inherit a second moving target on top of that.
The historical risk is real: GitHub Copilot CLI removed its --headless --stdio flags in 2026 (issue #1606) and pushed integrators toward
--acp instead — a breaking change for any wrapper. Pi's smaller
surface and explicit thin-wrapper framing make that class of disruption
less likely.
Beyond the strategic case, pi is also a good mechanical fit for the surface raymond already drives:
- It exposes a structured machine protocol (
--mode jsonfor an event stream and--mode rpcfor a bidirectional JSONL channel on stdin/stdout) that is well-suited to long-lived orchestration. - It supports first-class
--system-prompt(replace) and--append-system-prompt(append) — strictly more than Claude, which has only--append-system-prompt. Useful as a forward-looking knob even though raymond doesn't drive system prompts today. - It supports session resume by id (
--session <path|id>,-cfor most recent) and a separate--fork <path|id>operation that branches from a specific session — which is what raymond's<call>and cross-workflow call/return need (the callee inheriting the caller's history). - Its multi-provider model selector (
--provider <name>,--model <pattern>,--thinking <level>) lets raymond authors run workflows against models from Anthropic, OpenAI, Google, and others without changing backend.
The trade-off is that pi has a smaller user base and is less battle-tested
than the vendor CLIs, and a few raymond-internal assumptions
(per-event-cost telemetry on the live stream and Claude's
--permission-mode acceptEdits shape) have no direct equivalent on pi
and degrade as documented in "Features that are unavailable" below.
Prior versions of this strategy surveyed five candidate backends — Codex
CLI, Gemini CLI, Cursor CLI, pi, and GitHub Copilot CLI — with a
capability comparison table covering one-shot mode, stream-JSON, system
prompts, auto-approve, session resume, continue-and-fork, cost
reporting, and working-directory handling. That survey is in the git
history of docs/pi-backend-rationale.md; it is not reproduced here
because the strategy decision above renders it moot. Git history also
preserves the corresponding (now-deleted) copilot-backend.md feature
spec.
What this backend covers:
- pi runs as a second backend behind the
internal/backendabstraction, alongside the original Claude-only path. - Workflow-level
backend:declaration in the manifest (Claude Code remains the default when absent). - Per-state knobs (
model,effort,allowed_transitions, timeout) and the tool disallow list are mapped onto pi's equivalents, degrading cleanly where pi has no direct equivalent.
Out of scope, now and for the foreseeable future:
- Per-state backend switching. A workflow that genuinely needs both Claude and pi composes them via cross-workflow invocation (see cross-workflow-design.md).
- Any other backend (codex, gemini, cursor, copilot) as a first-class
raymond integration. Workflows that want those providers should use
pi with the appropriate
--providersetting.
The Claude Code integration is narrow and well-isolated, and the backend
abstraction (internal/backend) is in place. The pi implementation is a
sibling of ClaudeBackend; the executor, orchestrator, and observers are
unchanged at the seam.
-
Command construction:
internal/ccwrap/ccwrap.go—BuildClaudeCommandassembles flags. The binary nameclaudeis held in theclaudeExepackage variable (overridable in tests).BuildClaudeEnvstripsCLAUDECODEto prevent nested sessions, andInvokeStream/Invokewrap execution. Flags assembled today:--output-format stream-json,-p,--permission-mode acceptEditsor--dangerously-skip-permissions,--model,--effort,--resume <id>or-c --fork-session,--disallowed-tools(hardcoded:EnterPlanMode,ExitPlanMode,AskUserQuestion,NotebookEdit), and the prompt after--. -
Stream parsing:
internal/backend/claude.go—emitClaudeStreamEventstranslates Claude stream-JSON objects into Sink callbacks. Message types handled:assistant(text andtool_useitems),user(tool results, withis_errordriving ErrorOccurred via Sink.OnToolError), andresult(final, withis_errordriving usage-limit detection viaisClaudeLimitResult). Cost is read fromtotal_cost_usdand tokens summed fromusage.cache_creation_input_tokens,cache_read_input_tokens, andinput_tokens(extractClaudeCost,extractClaudeTokensin the same file). Session ID is read fromsession_idormetadata.session_idviaccwrap.ExtractSessionID. -
Backend interface:
internal/backend/backend.godefinesBackend.RunTurn(ctx, TurnSpec, Sink) (TurnResult, error)plus the neutral error types (TimeoutError,LimitError,RunError). The Claude implementation lives ininternal/backend/claude.go. A pi implementation goes alongside it (internal/backend/pi.go). -
Per-state agent config:
internal/policy/policy.godefinesPolicywithAllowedTransitions,Model,Effort. Per-workflow launch defaults live ininternal/state/state.goasLaunchParams(DangerouslySkipPermissions,Model,Effort,Timeout,ContinueAndFork,OnAsk). -
Executor abstraction:
internal/executors/executors.godefines aStateExecutorinterface with two implementations (MarkdownExecutor,ScriptExecutor). Selection is by file extension (GetExecutor). The markdown executor now callsbackend.Backend.RunTurn(defaulting to the Claude backend); the pi-vs-Claude split happens at that call. -
Manifest:
internal/manifest/manifest.godefines theManifeststruct. This is where thebackend:field lands.
The original five-candidate design notes left eight open questions. Most resolve automatically under the pi-only strategy because pi has session resume, fork, system-prompt flags, and stream-JSON. The remainder are resolved in the rest of this document:
backend:shape — structured block. A workflow writes either the bare stringbackend: pior a name plus options (backend:withname:andoptions:children, exposing pi-specific knobs likesession_dir,tools,extensions,skills). That lets pi's flag surface come through faithfully without inventing a generic cross-backend vocabulary for them.- Model field shape — opaque pass-through. The workflow author writes
Claude vocabulary (
opus,sonnet) when targeting Claude or pi vocabulary (provider/id, e.g.anthropic/claude-sonnet-4-6) when targeting pi. - Tool disallow list — Claude-specific scaffolding; no-op on pi.
Raymond's hardcoded list (
EnterPlanMode,ExitPlanMode,AskUserQuestion,NotebookEdit) names tools that don't exist in pi's surface. - MCP — not supported under pi. Pi is not MCP-native; it uses
--extensionand--skillinstead. Workflows that require an MCP-hosted tool can't run under pi unless the tool also ships as a pi extension or skill. (Raymond'sray servedaemon does not expose an MCP surface either; see daemon-server.md. The agent-side tool surface discussed here is a separate concern.) - Availability preflight —
pi --versionis run once at workflow start (and on resume), failing fast with a clear message if pi isn't installed.
A workflow opts into the pi backend in its manifest:
# workflow.yaml
backend: piFor YAML scope (single-file) workflows, the same backend: key sits at the
top of the YAML alongside name, description. For multi-file or zipped
workflows it sits in workflow.yaml.
When backend: is absent, raymond uses the existing Claude Code default. The
backend cannot vary between states within a single workflow; mixed-backend
work composes via cross-workflow invocation
(see cross-workflow-design.md).
For options that are pi-specific, the backend: key accepts a structured
form:
backend:
name: pi
options:
provider: anthropic # --provider
thinking: medium # --thinking <off|low|medium|high|xhigh>
tools: [read, edit, write, grep, find, ls] # --tools allowlist (omit `bash` unless needed)
no_builtin_tools: true # --no-builtin-tools / -nbt (mutually exclusive with `tools`)
no_tools: true # --no-tools / -nt (mutually exclusive with the above)
extensions: # --extension (repeatable; npm package, git URL, or local path)
- <extension-source>
skills: # --skill (repeatable; local path)
- ./skills/<skill-dir>
no_extensions: true # --no-extensions (disables auto-discovery)
no_skills: true # --no-skills (disables auto-discovery)
session_dir: <path> # --session-dir (override pi's default)All fields are optional; the example above shows the shapes, not a
recommended set. The intent is that pi's flag surface is exposed faithfully
under options: rather than translated through a generic vocabulary,
because the meanings are pi-specific (especially the tool allowlist and
skill/extension model). The boolean flags shown as true above are pi's
"opt out" switches; their default is implicitly false (don't pass the
corresponding pi flag).
Per-state YAML frontmatter continues to declare model: and effort: (the
existing knobs from internal/policy/policy.go), but their interpretation
adapts to pi:
| Frontmatter field | Claude backend | pi backend |
|---|---|---|
model: <id> |
--model <id> (e.g. sonnet, opus) |
--model <pattern>; the workflow author may use pi's provider/id syntax (e.g. anthropic/claude-sonnet-4-6) when the workflow targets pi specifically |
effort: <level> |
--effort <id> (Claude's vocabulary) |
--thinking <off|low|medium|high|xhigh>. Raymond translates low/medium/high 1:1; values outside pi's vocabulary are passed verbatim and produce a clear error if rejected by pi |
Workflow authors who want to keep the workflow portable across backends should prefer values that are valid for both. Workflows that target pi exclusively may use pi-native model patterns directly.
ray run and ray serve keep their existing flags. The interpretation
of --dangerously-skip-permissions adapts: pi has no per-call permission
prompts the way Claude does. Instead, pi's safety boundary is the
--tools allowlist and the --no-tools / --no-builtin-tools flags. In the
pi backend:
--dangerously-skip-permissions(raymond CLI) ⇒ raymond passes the workflow's declaredtoolsallowlist if present, otherwise no--toolsflag at all (pi runs with its default tool surface).- The default (no flag) ⇒ raymond passes the workflow's declared
toolsallowlist if present, otherwise it passes a conservative built-in default:read, edit, write, grep, find, ls— pi's built-in tools minusbash. A workflow that needsbashunder the default safety mode must opt in by listing it explicitly inbackend.options.tools. This preserves the spirit of "ask before risky things" for pi, even though the mechanism differs from Claude's per-call prompts.
This is the most user-visible semantic difference between the two backends and will be called out in the authoring guide.
When a workflow declares backend: pi, raymond probes for the pi binary
once at workflow start (and once on resume) via a single pi --version
invocation with a 5-second timeout, and fails fast with a clear "pi not
found in PATH" message that points at install instructions (pi is
distributed as an npm package — npm install -g @mariozechner/pi-coding-agent
— and therefore requires a Node.js runtime on the host). The cost is one
process spawn; the payoff is that a missing binary surfaces immediately
instead of mid-workflow.
Raymond does not validate API credentials at preflight. Pi is expected
to be already authenticated against whatever provider the workflow uses
(pi auth or environment variables); credential errors surface from pi's
first real invocation just as they do for Claude today.
The following raymond features work identically under the pi backend. The backend abstraction handles the translation; workflow authors notice no difference.
- State graph and transition tags. All seven transition tags (
goto,reset,call,function,fork,ask,result) work unchanged. Their semantics live in the orchestrator, not in the backend. - Shell-script states. Shell, batch, and PowerShell states do not use any backend; they continue to run as plain subprocesses with zero token cost.
<ask>and human-in-the-loop. The orchestrator suspends the workflow to disk and resumes when input arrives. Independent of the backend.- Cross-workflow invocation.
<call-workflow>,<function-workflow>,<fork-workflow>,<reset-workflow>— independent of backend. (A called workflow may declare its own backend; raymond launches the appropriate backend per nested workflow.) - Per-workflow cost budget. The dollar budget is enforced at the orchestrator level. Raymond reads pi's per-turn cost by parsing the session JSONL file after each turn, then applies the same budget-overrides-transition rule as Claude.
- Crash recovery and
--resume. Raymond's persisted workflow state is backend-agnostic; resume continues to work. Each agent state record carries its backend-specific session id (a pi session UUID for pi, a Claude session id for Claude), and raymond passes the right one to the right backend on resume. ray lint,ray diagram,ray convert. Static analysis is over the workflow graph; the chosen backend has no effect.ray servedaemon. HTTP API, web UI, and input delivery all continue to work. The dashboard learns to display the active backend and per-agent backend session ids.<call>(stack frame that inherits parent context). Implemented by invoking pi with--fork <caller-session-id>, which branches a new session off the caller's so the callee starts with the caller's history. Same shape as Claude (--fork-sessionafter--resume <caller>); only the flag name changes. Important for cost accounting: pi's--forkcopies the caller's full message history into the new session file (verified empirically on pi v0.74). The pi backend reads the caller's prior cost before invoking pi and subtracts it from the post-turn read so the call only charges the caller for the new turn's spend; otherwise the caller's history would be re-charged on every<call>.<fork>(spawn a parallel agent). Despite the flag name overlap,<fork>is not related to pi's--fork(or Claude's--fork-session). It is a Unix-fork()-style operation that launches an additional independent agent within the workflow. Whether the child inherits any session history is decided at the orchestrator/transitions layer (the same way it's decided for Claude today); the pi backend just executes whatever session-id wiring the orchestrator hands it.<function>(stack frame with fresh context) and<reset>(replace current context). Both run pi with neither--sessionnor--fork, so the agent starts a brand-new pi session with no inherited history. There is no fork flag involved — the previous session is simply abandoned.<reset>additionally clears the agent's persisted session id so subsequent<goto>turns continue against the new session.--continue-and-fork(start from the user's most recent session in this cwd). Claude exposes this as-c --fork-session; pi has no atomic equivalent (its--sessionand--forkflags both require an explicit session id). The pi backend implements the same behavior by reading the session directory pi uses for this cwd (~/.pi/agent/sessions/<mangled-cwd>/by default, orbackend.options.session_dirif set), selecting the most-recently-modified*.jsonlfile, extracting the session id from its filename, and passing it to--fork. If the directory is empty the run fails at launch with a clear "no pi session found" error — the same shape Claude produces when there is nothing to continue from. Cost accounting works exactly as<call>does: the caller's prior cost is subtracted from the post-turn read so the forked turn is charged only for its new spend.
These behaviors continue to work but are wired differently under pi.
Raymond parses Claude's --output-format stream-json shape inside the
Claude backend (internal/backend/claude.go, emitClaudeStreamEvents).
Under the pi backend, a sibling implementation parses pi's --mode json
event stream instead. The event types raymond consumes from pi:
session— top-of-stream event carrying the session UUID ({"type":"session","id":"<uuid>", ...}). Raymond records this id on the agent state so the next turn can pass it to--sessionor--fork. (Earlier drafts of this spec expected the id onagent_start; pi v0.74 emits a bareagent_startand puts the id onsession. The pi backend reads fromsessionand falls back toagent_start.sessionIdfor forward-compat.)message_update(assistanttext_deltaevents) — drivesProgressMessageevents on the bus.tool_execution_start(withtoolName,args) — drivesToolInvocationevents.tool_execution_end(withresult,isError) — drivesErrorOccurredevents whenisErroris true.agent_end— terminal event; raymond uses it to know the turn is complete and to extract the assistant's final message text (which carries the transition tag raymond is looking for). The text lives atmessages[-1].content[i].textfor assistant role — not on a top-leveltextfield.
Other pi event types (turn_start, turn_end, message_start,
message_end, compaction_start, compaction_end, queue_update) are
read off the stream but produce no orchestrator-facing events. They may be
written to the per-state debug log if --debug-dir is set. In particular,
pi's automatic context compaction is assumed to be transparent to
raymond: the session id is unchanged across compaction, and the next
turn's --session <id> invocation should work as if compaction had not
happened.
Verification status (pi v0.74): session-id stability across normal multi-turn resume is confirmed (
workflows/pi_smoke_resumeexercises a 2-turn<goto>loop; thesessionevent reports the same UUID on both turns). Session-id stability across compaction is confirmed by source reading: bothagent-session.js's manualcompact()(line 1306) and the auto-compact path in_checkCompaction()(line 1543) funnel throughsessionManager.appendCompaction(...), which appends acompactionentry to the existing branch and never touchesthis.sessionIdorthis.sessionFile. Triggering compaction at runtime from--print --mode jsonisn't possible (/compactis TUI-only) and the auto-compact threshold is far past a smoke test, but the code path is unambiguous. Revisit if a workflow ever reports a session-id mismatch on resume.
The backend abstraction normalizes the consumed events into the same orchestrator-facing events the Claude path emits today, so the rest of raymond is unchanged.
Raymond's idle timeout (default 600 s, resets on each chunk received) and
total timeout apply to pi turns identically: any line on pi's stdout
resets the idle timer. The same ClaudeCodeTimeoutError-shaped error is
raised on timeout (renamed at the abstraction layer to a backend-neutral
AgentTimeoutError or similar — orchestrator-level naming is implementer's
choice).
Raymond invokes pi the same way it invokes claude: one pi process per
state turn. Each turn either resumes the agent's existing session
(--session <id> for <goto>), branches a new session off a caller's
history (--fork <caller-session-id> for <call>), or starts fresh (no
session flag, for <reset> / <function> / first turn). When the turn
completes (pi emits agent_end and exits), raymond reads cost/usage and
decides the next state. No long-lived pi process is held open between
turns.
This matches the Claude code path (InvokeStream per turn) and keeps
crash recovery simple: workflow state on disk plus the pi session JSONL
on disk are sufficient to resume after any failure.
Raymond uses pi's --mode json (per-turn event stream on stdout). Pi's
--mode rpc (bidirectional long-lived JSONL channel) is not used in
v1. Rationale:
--mode jsonmatches the per-turn invocation pattern raymond already uses for Claude; the existingInvokeStream-shaped abstraction maps directly.- The features
--mode rpcadds (steer,abort, queue management,get_session_stats) are not currently needed: raymond's cancellation is process-kill, raymond never queues prompts to a running agent, and cost/usage can be read from the session JSONL file at turn end. - One process per turn means pi's exit code is the natural failure signal, mirroring Claude's contract.
The protocol mode is an internal detail of the pi backend, not exposed to workflow authors.
Pi's --mode json event stream does not include per-event cost or token
counts. After each turn (when pi exits), raymond parses the session JSONL
file and sums per-assistant-message usage records to derive
total_cost_usd and token counts identical in shape to what Claude
reports. The session JSONL lives under pi's session storage (default
~/.pi/agent/sessions/<mangled-cwd>/<timestamp>_<id>.jsonl, or under
backend.options.session_dir if set); raymond locates the file by the
session id captured from the session event, matching by suffix because
pi prepends an ISO-timestamp to the filename. The cwd-to-directory
mangling pi performs (strip leading/trailing /, replace / with -,
wrap in --) is mirrored in internal/piwrap/piwrap.go.
The orchestrator's per-workflow cost budget is enforced from these reads exactly as it is for Claude.
By default raymond does not pass --session-dir; pi stores sessions in
its normal location (~/.pi/agent/sessions/<mangled-cwd>/), the same way
the existing Claude integration relies on Claude's normal session storage
under ~/.claude/.
Pi organizes session files under sub-directories keyed by the working
directory at session-creation time (with the cwd path mangled into a
flat dirname — see "Cost and token accounting" above). This is not a
new constraint for raymond: Claude Code's session storage has the same
property, and raymond already only allows the working directory to change
at points where the session is being abandoned anyway (<reset>,
<function>, <fork>, cross-workflow boundaries). Within a single
continuous session — <goto> loops, <call>/return — the cwd stays put,
so the cwd-keyed organization is invisible.
A workflow author may set backend.options.session_dir to relocate
sessions — for example to keep them with the workflow run state for
archival, or to share them with an interactive pi TUI. Raymond passes the
value through to pi's --session-dir flag verbatim.
The pi-backend equivalent of BuildClaudeCommand assembles a different flag
list:
- Always:
pi --mode json(and--session-dir <dir>only if the workflow setbackend.options.session_dir). - If model is set:
--model <value>(and optionally--provider <value>frombackend.options.provider). - If effort is set:
--thinking <translated value>. - For session continuation:
--session <session-id>to resume the agent's existing session (the<goto>case), or--fork <caller-session-id>to branch a new session from a caller's history (the<call>case). The first turn after<reset>or<function>passes neither flag, so pi starts a brand-new session. Pi's-c("most recent session") is not used — raymond always knows the exact session id it wants and passes it explicitly. - Tool allowlist derived from
--dangerously-skip-permissionsandbackend.options.tools(see "Launch flags" above). One of--tools,--no-tools, or--no-builtin-toolsmay apply, derived as follows:backend.options.no_tools: true⇒--no-tools;backend.options.no_builtin_tools: true⇒--no-builtin-tools; otherwise--tools <comma-list>per the Launch-flags table. - If declared:
--system-prompt/--append-system-prompt(currently unused by raymond; reserved for future use). - If declared: each
--extension <source>and--skill <path>frombackend.options. - The state's prompt body, delivered as a single trailing positional
argument. Raymond invokes pi via Go's
exec.Command, which passes argv as raw bytes to the child process — no shell interprets the prompt, so quotes, newlines, backticks, dollar signs, etc. cannot be misinterpreted. This is the same pattern raymond uses for Claude (ccwrap.goline 217, with tests atccwrap_test.go:47-65verifying the argv layout) and is robust by construction.
Raymond hardcodes a Claude-specific disallow list (EnterPlanMode,
ExitPlanMode, AskUserQuestion, NotebookEdit) so the agent does not enter
modes raymond doesn't drive. Pi has none of those tools, so the disallow list
is a no-op under the pi backend. The intent ("no plan mode, no notebooks, no
mid-state human prompts") is automatically satisfied by pi's smaller tool
surface.
Pi inherits the parent process's working directory (matching Claude). Raymond
strips the CLAUDECODE environment variable today (ccwrap.BuildClaudeEnv)
to prevent Claude from treating itself as nested inside another session. The
pi backend does not need to strip CLAUDECODE; if pi adopts an analogous
nested-session marker in the future, the backend abstraction is the right
place to handle it.
These are features that exist for the Claude backend but cannot be supported under pi as currently understood, or that have meaningful semantic differences the workflow author should know about.
-
Per-tool approval prompts (
--permission-mode acceptEdits). Pi has no per-call permission prompt model; safety lives in the static--toolsallowlist. Workflows that depended on Claude's mid-call accept-edit prompts to gate destructive tool calls have no equivalent under pi. The recommended migration is to declare a conservativebackend.options.toolsallowlist that omitsbash(and any other risky tools) for those states. -
Claude usage-limit detection. Raymond detects Claude's "hit your limit" / "out of extra usage" messages from the result stream (
internal/backend/claude.goclaudeLimitPatterns) and treats them as a special class of failure. Pi has no equivalent provider-level message in its event stream; provider rate limits surface as ordinarytool_execution_enderrors oragent_enderrors, and raymond classifies them as generic failures. -
Per-event cost reporting on the live event stream. Cost is read from the session JSONL after the turn ends, not from each
resultmessage during the turn as Claude does. The end-of-turn cost is identical; what is missing is intra-turn cost telemetry that some observers display in the dashboard. The dashboard will show—for in-flight cost on pi states until the turn completes. -
Claude-specific
model:values. A workflow that hardcodesmodel: opusonly makes sense against Claude. Under pi the workflow author must either use a value pi recognizes (a model id valid for the selected provider, with optionalprovider/idprefix) or omit the field and let pi pick its default. Raymond does not translateopus⇒ "anthropic/claude-opus-…" automatically; the field is passed through verbatim. -
Claude-specific tool names in
disallowed_toolsworkflow overrides. If a future feature lets workflows extend the hardcoded disallow list with their own entries, those entries are interpreted by Claude only. A pi workflow expresses the same intent throughbackend.options.tools(an allowlist). -
Agent-side MCP servers. Pi does not natively speak MCP. Its tool surface is its built-in tools plus its own extension (
--extension) and skill (--skill) mechanisms, which are pi-specific and not protocol-compatible with MCP. Workflows that depend on the agent calling tools exposed by an MCP server cannot run under pi unless an equivalent pi extension is available. (Raymond'sray servedaemon does not expose an MCP surface either, so there is no daemon-side equivalent to fall back on; see daemon-server.md.) -
The
effort: <Claude-specific level>vocabulary on per-state policies. Claude's--effortaccepts a different vocabulary than pi's--thinking. Values that overlap (low,medium,high) translate cleanly; other values produce a clear error from pi rather than a silent reinterpretation.
| Raymond feature | Claude backend | pi backend |
|---|---|---|
| State graph + transition tags | ✓ | ✓ (orchestrator-level) |
| Shell-script states | ✓ | ✓ (orchestrator-level) |
<ask> / human-in-the-loop |
✓ | ✓ (orchestrator-level) |
<fork> (spawn parallel agent) |
✓ | ✓ (orchestrator-level; not related to --fork) |
<call> (inherit caller context) |
✓ (--fork-session) |
✓ (--fork <caller-session-id>) |
<function> / <reset> (fresh context) |
✓ | ✓ (no --session or --fork flag) |
| Cross-workflow invocation | ✓ | ✓ (orchestrator-level) |
| Per-workflow cost budget | ✓ | ✓ (cost summed from session JSONL after each turn) |
--resume <run_id> after crash |
✓ | ✓ (pi session UUID persisted) |
ray lint / diagram / convert |
✓ | ✓ (orchestrator-level) |
ray serve daemon + web UI |
✓ | ✓ (UI shows pi session ids) |
--dangerously-skip-permissions |
✓ (acceptEdits / skip) | ✓ but different mechanism — controls tool allowlist |
--continue-and-fork |
✓ (-c --fork-session) |
✓ (raymond resolves the most-recently-modified file in the cwd's pi session dir, then --fork <id>) |
Per-state model: portability |
Claude vocabulary | pi vocabulary (use provider/id for clarity) |
Per-state effort: portability |
Claude vocabulary | pi --thinking vocabulary; common values (low/medium/high) overlap |
| Hardcoded tool disallow list | enforced | no-op (those tools don't exist on pi) |
| Live per-event cost | ✓ | end-of-turn only |
| Usage-limit-specific error class | ✓ | generic failure |
| MCP servers (any source) | ✓ (Claude is MCP-native) | ✗ — pi is not MCP-native; equivalent capability via pi extensions only |
A workflow author writing for pi specifically should:
- Declare
backend: pi(or the structured form) inworkflow.yaml. - If a specific model matters, set
model:to a pi-recognized value (provider/model-idform is least ambiguous). - Decide tool safety up front: declare
backend.options.toolswith the minimum set the workflow needs. Pi has no per-call permission prompts to fall back on — the allowlist is the only gate. - If the workflow integrates with external tools, do not assume MCP
is available — pi is not MCP-native. Express tool integrations as pi
extensions (
backend.options.extensions) or skills (backend.options.skills). A workflow whose external tools are only available as MCP servers cannot run under pi.
A workflow that is meant to run portably across both backends should:
- Avoid backend-specific
model:values (or rely on per-environment overrides from the launch CLI). - Use only
effort:values in the overlap (low,medium,high). - Not depend on Claude usage-limit detection or live per-event cost.
Resolved in the body of this spec: protocol mode (--mode json), cost data
path (post-turn JSONL parse), session storage (pi's default with optional
override). Status of the rest:
All resolved against pi v0.74. Session-id stability across compaction is
confirmed by reading pi's source — see the "Stream parsing" section's
verification-status note. End-to-end behavior of <call> (pi's --fork,
including the prior-cost subtraction) and <fork> (parallel agents with
fresh sessions) is covered by TestPiIntegration_RealPi_CallTransition
and TestPiIntegration_RealPi_ForkTransition. Windows cwd mangling
(piCwdDirName) remains unverified on a real Windows host; the cost-read
path degrades to a silent $0/turn there until someone with a Windows box
ports pi's actual mangling.
- System prompt usage. Raymond does not currently set a system prompt
for either backend. If a future orchestrator-level instructions feature
(injecting transition syntax reminders or tool-use guardrails as a
system prompt rather than baking them into every state file) lands, pi
already supports
--append-system-prompt; no further pi-specific work is required.