Passing extra launch flags to Claude Code / Pi seats

[mowat27]

Hi, I'm new to OpenRig and trying to work out how much control I have over how seats are launched. I asked the advisor.lead agent in my kernel rig how to do this. It read the installed package and gave me the findings below, which I'd like to check with people who know the project before I conclude there's a gap. Some of it is inference, so corrections are welcome.

What I'd like to be able to do

• Start Claude Code seats with additional flags such as --agent <name> and --append-system-prompt-file <file> on some seats and not others.
• Start pi seats with additional flags too - but mainly a set of extensions via -e.

What the agent found (OpenRig installed via npm; it read the installed package, not the repo source)

• The Claude launch command is built in claude-code-adapter.js. The only configurable parts it found are --model, --effort and the permission posture. --name, --session-id and --resume are set by OpenRig.
• The pi child args are built by buildPiChildArgs in pi-runner-protocol.js (--mode rpc, --session-dir, --name, trust flag, --model, --session/--fork). It found no passthrough for others.
• runtime_resources (for example claude_settings_fragment and claude_mcp_fragment) and startup.files cover a lot, but not these flags.
• Pi sets PI_CODING_AGENT_DIR per seat, so it assumed global ~/.pi extensions aren't loaded.

Questions

1. Is there a supported way to pass extra CLI args to a seat's runtime, for example a field on the member or profile? Am I missing it?
2. If not, what's the recommended way to get the effect of --append-system-prompt-file and --agent on a Claude seat? Are startup files or .claude/agents/ the intended route?
3. For pi, should extensions go in the seat's cwd/.pi/extensions? Is there a way to load shared ones?
4. Is per-member launch args something you'd consider, or does it conflict with how the runtime adapters work?

Environment: rig 0.6.5 (5ea35e9), macOS, herdr 0.9.1 as the terminal provider.

[KingEmma7]

I checked the source at your 5ea35e93 revision. The managed Claude launch builder and Pi runner arguments have no generic extra-argv input. The Pi runner also rejects unrecognised flags, so adding -e to the runner command itself does not forward it to Pi.

There are configuration routes for some of the effects you want:

• Claude --agent: Claude supports an agent setting, such as {"agent":"reviewer"}, with the named definition in .claude/agents/. OpenRig's claude_settings_fragment merges into <cwd>/.claude/settings.local.json. Declare the fragment in resources.runtime_resources and select its ID in the chosen profile's uses.runtime_resources. Seats sharing a cwd share that settings file; use separate working directories if their default agents must differ.

• Extra instructions: Use each seat's startup.files with delivery_hint: send_text for role/context instructions. The startup guide recommends this for seats sharing a directory. These arrive as messages after the harness is ready; they do not reproduce --append-system-prompt-file's system-prompt placement.

• Pi extensions: Your global-directory inference is correct. OpenRig sets PI_CODING_AGENT_DIR to <stateRoot>/<sessionName>/agent, typically under <OPENRIG_HOME>/state/pi. Pi's configuration uses that directory for user settings and extensions. You can put shared absolute paths in that seat's settings.json:

  {
    "extensions": ["/absolute/path/to/shared/extension.ts"]
  }

  The same syntax works in <cwd>/.pi/settings.json, and <cwd>/.pi/extensions/ is the project discovery location. Those project routes are subject to Pi's project-trust handling; OpenRig's conservative --no-approve posture can exclude project resources. The seat's agent-directory settings avoid depending on project discovery, and can point multiple seats at the same reviewed extension file.

I ran the exact OpenRig argument/environment functions locally to check the isolated directory and flag rejection. I have not launched native Claude/Pi seats or tested the settings projection end to end. A general per-member argv feature would need a maintainer decision; these are the existing configuration routes.

[mvschwarz]

Thanks, @mowat27, for checking with us before concluding there's a gap, and for separating what your agent read from what it inferred. Thanks also, @KingEmma7, for the source-linked answer. You're right that neither the Claude launch builder nor the Pi runner takes extra arguments.

1. Extra CLI args: no. 0.6.5 has no member or profile field for extra runtime arguments. Claude seats start with OpenRig's own flags only (permission mode, OpenRig's settings, model, effort, and resume or fork), and the managed Pi runner accepts its own fixed set of flags and exits with an "unknown flag" error on any other.
2. --agent and --append-system-prompt-file on Claude: both routes below apply per working folder, not per seat, so seats that share a folder share them. For different settings on different seats, give those seats different working folders.
   • --agent: declare the agent file as a subagents resource (OpenRig copies it to <cwd>/.claude/agents/), and add a claude_settings_fragment runtime resource with {"agent": "<name>"}, which OpenRig merges into <cwd>/.claude/settings.local.json. Claude's own help says --agent overrides the agent setting, so the setting makes the same choice from a file. Both resource types are in docs/reference/agent-spec.md.
   • --append-system-prompt-file: there's no system-prompt slot. The nearest options are a guidance resource, which OpenRig writes as a marked section into the folder's CLAUDE.md (or CLAUDE.local.md, if the rig sets managed_blocks) before the seat starts, so Claude loads it at start; or per-seat text through startup.files with delivery_hint: send_text, which arrives as the first message rather than in the system prompt.
3. Pi extensions (from Pi 0.87.1's docs; we don't know which Pi version you run): <cwd>/.pi/extensions/ loads only after Pi's project trust is granted. OpenRig starts Pi with an explicit --approve or --no-approve flag, and under --no-approve project extensions are skipped. Each seat gets its own Pi agent folder, so ~/.pi/agent/extensions isn't seen. For shared extensions, list their paths under extensions in the project's .pi/settings.json, which also needs trust. .pi/APPEND_SYSTEM.md adds per-folder instructions to Pi's system prompt, which is the Pi answer to the system-prompt half of question 2.
4. Per-member launch args: a fair ask, and in principle it doesn't conflict with how the runtime adapters work. The closest open work is Keep seat projection out of the seat's cwd: deliver skills, hooks, MCP and guidance through launch flags #875, an opt-in way to pass a seat's own files and settings at launch, Claude seats first, where we've said yes to the scope. Your --agent case and your Pi extensions via -e would be useful input there.

[mowat27]

Hi @mvschwarz and @KingEmma7

Thanks for the detailed responses. I'm new to openrig and still finding my way so I will spend a bit of time with these ideas and try them in some real situations before I give you any detailed feedback.

One thing I will be careful of this that --agent replaces the Claude Code system prompt with whatever you put in <agent>.md so that strategy would be fine for a truly standalone agent - e.g. a document summariser - but it might not be so good for a coding task.

The docs (https://code.claude.com/docs/en/sub-agents.md) say a custom agent's system prompt "replaces the default Claude Code system prompt entirely, the same way --system-prompt does." The CLI reference adds that this "drops all of the default prompt, including tool guidance and safety instructions."

[mvschwarz]

Thanks, @mowat27, for flagging that, and for quoting the docs. It's a fair caution for that route: as you quote, a custom agent's prompt replaces Claude Code's default system prompt, and the agent setting we suggested does the same thing from a file. So it suits a standalone agent better than a coding seat.

For a coding seat that needs extra instructions while keeping Claude Code's default prompt, the other two options from our earlier reply are the closer fit: a guidance resource, which OpenRig adds as a marked section to the CLAUDE.md in the seat's working folder before the seat starts, or per-seat startup.files with delivery_hint: send_text, which arrive as the first message. Both are in the agent spec reference.

Glad to hear how it goes when you try them in real situations.