Research: bunny architecture for native remote execution

[ahoward]

Problem

Bunny's dark factory shells out to claude CLI for builder steps (specify, plan, implement) and gemini CLI for adversary steps (challenge, test-gen, verify). On a claude --remote cloud VM, the agent IS Claude — so shelling out to claude CLI is recursive and redundant.

How should bunny's architecture adapt to run natively inside a remote Claude Code session?

Key insight

On a remote VM, Claude is the host agent. It reads CLAUDE.md, understands the workflow, and can do the "claude steps" directly (writing specs, plans, implementations). Only the gemini steps need to shell out. This means the pipeline splits naturally:

Step	Local mode	Remote mode
specify	shell out to claude	agent writes spec directly
challenge	shell out to gemini	shell out to gemini
plan	shell out to claude	agent writes plan directly
tasks	shell out to claude	agent writes tasks directly
test-gen	shell out to gemini	shell out to gemini
implement	shell out to claude	agent writes code directly
verify	shell out to gemini	shell out to gemini
retro	shell out to claude	agent writes retro directly

Research questions

Architecture

• Should bunny detect it's running inside a remote session and switch behavior? Or should there be an explicit --remote-mode flag?
• Can the structured output schemas (spec, plan, tasks, retro) be reused as direct prompts to the host agent instead of CLI calls?
• Should bny remote build "desc" be a new command that composes the right prompt and calls claude --remote?

Auth & credentials

• Gemini API keys: how do they reach the cloud sandbox? Environment variables? Secrets manager? Network proxy?
• GitHub auth: the cloud VM uses a proxy — does this work with bunny's branch creation and PR workflow?
• Are there other credentials the pipeline needs (npm, bun, etc.)?

Parallel execution

• Can bny next --parallel N launch N independent claude --remote sessions for different roadmap items?
• How do parallel builds coordinate? Separate branches? Lock files? Race conditions on bny/state.md?
• What's the token budget impact of running multiple full pipelines simultaneously?

Adversary isolation

• Could builder (claude) and adversary (gemini) run on truly separate VMs?
• Communication only through git artifacts (specs, test files) — no shared process memory
• Does this improve adversarial quality or just add complexity?

Environment setup

• Cloud VMs have bun pre-installed — can we bun run bin/bny.ts directly?
• Or should the setup script download the compiled binary from GitHub releases?
• What goes in the remote session's setup script? (./dev/setup, gemini CLI install, env vars)

Prompt engineering

• What's the optimal prompt for claude --remote to run a bny pipeline?
• Should it be a single big prompt or should bunny compose it from templates?
• How much of CLAUDE.md + roadmap + guardrails should be included vs. discovered by the agent?

Possible approaches

A. Thin wrapper — bny remote

New command that composes a prompt and calls claude --remote. The remote agent reads CLAUDE.md and runs steps manually. Bunny itself doesn't change — the remote agent just follows instructions.

B. Dual-mode pipeline

Bunny detects the execution environment. In remote mode, claude-steps become inline prompt execution (no shell-out). Gemini steps still shell out. Same binary, different code path.

C. Agent protocol

Bunny exposes its pipeline as a structured protocol (JSON task descriptions). Any agent (local claude, remote claude, gemini, human) can pick up tasks and execute them. Remote execution becomes just another consumer of the protocol.

Related

• Explore --environment remote for isolated dark factory work #14 — Explore --environment remote for isolated dark factory work
• [012] agent continuity — durable build state so Claude can drive a full MVP across sessions #13 — Durable build state via bny/state.md

[ahoward]

Research Findings: Native Remote Execution

Current Architecture (summary)

The pipeline already has clean separation:

• Claude steps (specify, plan, tasks, implement, retro): all go through call_claude() or spawn_async(["claude", "-p", ...]) in src/lib/spawn.ts
• Gemini steps (challenge, test-gen, verify): all go through spawn_async(["gemini", "-p", ...])
• Agent env scrubbing: scrub_agent_env() already strips CLAUDECODE, CLAUDE_CODE_*, CLAUDE_AGENT_*, GEMINI_CLI* before subprocess spawn
• Build state: durable markdown table at bny/state.md, survives session disconnects
• In-process dispatch: bin/bny.ts routes ALL commands through a Record<string, CommandFn> — no subprocess for bny subcommands

Recommendation: Approach B (Dual-Mode Pipeline)

Why not A (thin wrapper)? The remote agent would need to re-discover the pipeline by reading CLAUDE.md. Fragile — the agent might skip steps, invent its own, or lose state.

Why not C (agent protocol)? Over-engineered for the current state. The pipeline is linear with known steps. A task queue adds complexity without clear benefit yet.

Why B? The architecture already isolates claude steps behind call_claude(). In remote mode, those calls become direct prompt execution (the host agent IS claude). Gemini steps still shell out. Same pipeline, one code path swap.

Design: Remote Mode Detection

Remote mode = CLAUDECODE env var is set (or explicit --remote flag)

When running inside claude --remote, the CLAUDECODE=1 sentinel is set. Currently scrub_agent_env() strips it before subprocess calls. Instead:

1. Check at startup: const is_remote = !!process.env.CLAUDECODE
2. Claude steps: if is_remote, skip subprocess and return prompt + instructions as structured output that the host agent executes directly
3. Gemini steps: always shell out (scrubbed env), same as today
4. Ralph retries: work the same — fn() returns exit code regardless of mode

Implementation Sketch

The key change is in src/lib/spawn.ts:

export function is_remote_mode(): boolean {
  return process.env.CLAUDECODE === "1" || process.argv.includes("--remote")
}

export function call_claude(prompt: string, root: string): string | null {
  if (is_remote_mode()) {
    // In remote mode, we ARE claude. Write the prompt to a known location
    // and return a sentinel that tells the host agent to execute it.
    // The host agent reads CLAUDE.md and knows the protocol.
    return null  // Signal: "you do this step"
  }
  // Normal: shell out to claude CLI
  return call_claude_subprocess(prompt, root)
}

But there's a subtlety: in remote mode, call_claude() can't return the LLM's response because the host agent hasn't generated it yet. The pipeline needs to yield control.

The Real Problem: Control Flow

Local mode is synchronous: call_claude() → get response → write file → next step.

Remote mode is cooperative: the host agent needs to do the work (write the spec, plan, code), not just receive a prompt. This means:

Option B1: Pipeline yields at each claude step. Build state tracks progress. The host agent runs bny build, it executes up to the first claude step, writes the prompt to specs/{feature}/step-prompt.md, updates state to "awaiting_claude", and exits. The host agent reads the prompt, does the work, then runs bny build again — it resumes from the next step.

bny build "auth"  → creates feature, writes specify-prompt.md, exits 42
host agent        → reads prompt, writes spec.md
bny build         → resumes, runs challenge (gemini), writes plan-prompt.md, exits 42
host agent        → reads prompt, writes plan.md
bny build         → resumes, runs test-gen (gemini), writes implement-prompt.md, exits 42
host agent        → reads prompt, implements code
...

Exit code 42 = "step complete, awaiting host agent". State machine in bny/state.md tracks position.

Option B2: Pipeline emits instructions inline. Instead of exiting, the pipeline writes structured instructions to stdout that the host agent follows. This is closer to Approach C but lighter.

{"action": "write_file", "path": "specs/001-auth/spec.md", "prompt": "You are writing a feature specification..."}

The host agent reads these, executes them, and feeds results back via stdin or file.

Auth & Credentials (Remote)

• Gemini API key: must be injected as GEMINI_API_KEY env var in the remote session. claude --remote supports --environment for this. Alternatively, the remote setup script exports it.
• GitHub auth: claude --remote uses a proxy for git operations. gh CLI works if the proxy is configured. Branch creation/PR workflow should work — test this.
• Bun: pre-installed on cloud VMs. bun run bin/bny.ts works directly.

Parallel Execution

• Feasible: bny next --parallel N could launch N claude --remote sessions on different branches.
• Coordination: each session works on a separate feature branch. No shared state conflict — bny/state.md is per-feature (can be extended to bny/state/{feature}.md).
• Token budget: each session is independent. The --effort flag already caps iterations/budget.
• Risk: parallel PRs may conflict on shared files. Git merge handles this. Worst case: one PR needs rebase.

Adversary Isolation

• Not worth it yet. Builder and adversary already communicate only through files (specs, tests). Separate VMs add latency without improving adversarial quality.
• Future: if adversarial quality matters more, gemini could run on its own VM with read-only access to the git repo. But this is premature.

Recommended Next Steps

1. Prototype B1 (yield-at-claude-step) on a branch. Small change: build.ts checks is_remote_mode() before each claude step, writes prompt file, updates state, exits 42.
2. Test with claude --remote: verify gemini CLI works in cloud sandbox, verify branch creation works through proxy.
3. Document the remote protocol: what the host agent should do at each yield point.
4. Defer parallelism: get single-session remote working first.

Files That Change

File	Change
src/lib/spawn.ts	Add is_remote_mode(), modify call_claude() to yield
src/build.ts	Check remote mode at each claude step, write prompt files, handle exit 42
src/lib/state.ts	Add awaiting_claude step status
bin/bny.ts	Handle exit 42 (not an error)
CLAUDE.md	Document remote mode protocol for host agent

~200 lines of changes. No new dependencies.

[ahoward]

Subprocess sandboxing is now tracked in #16 — session isolation, env allowlisting, and cleanup are prerequisites for remote mode.