How to actually get an agent session running, in whichever of the three supported runtimes fits — and what Elephant/Goldfish means once it's up.
This page is a walkthrough, not a source of truth. flme-agents/README.md's "Starting a new instance" section is the single source for each agent's exact kickoff text; this page just explains how to use it. If anything here disagrees with README.md or CLAUDE.md, those win.
Via the remote-device bridge. The original mode. No direct git-write (routes through a local CLI session), and a Cowork session can't message other agent sessions directly — Jake relays by hand.
A regular claude session running directly in the agent's home repo on Jake's Mac. Full git access, and can address other local sessions directly via cross-session messaging (ListAgents/SendMessage).
/desktopA local CLI session moved into the Desktop app. Same session, same identity — still reachable by cross-session messaging as long as it stays local rather than being sent to Cloud.
An agent's identity and mandate don't change based on which runtime a given session is running under — see flme-agents/CLAUDE.md's "Starting or resuming an agent instance" for the full record.
Within either local-CLI runtime (2 or 3 above), a session plays one of two roles — this is a role, not a fourth runtime:
STATE.md as its first action, maintains it, is who other sessions and Jake address by the agent's plain name (Sam, Wren, Nora, Sage).<Name>-GF (append 2, 3, ... for more than one at once, e.g. Wren-GF2). Never reads STATE.md. Takes a fully self-contained task from its Elephant or from Jake and executes it — file writes, git commits, even STATE.md updates — so the Elephant's own context stays spent on coordination, not execution.Not every agent needs a Goldfish. Sam and Nora (when running local-CLI) have explicitly decided against one — they already have direct git/file access, so there's nothing to offload. Wren (WRENS-GF) and Sage (SAGE-GF) use one because their Elephant is Cowork-based or wants to keep coordination context separate from execution.
scripts/start-agent.shThe single entry point, from flme-agents:
scripts/start-agent.sh <agent-name> # launch, Elephant
scripts/start-agent.sh <agent-name> --gf [N] # launch, Goldfish
scripts/start-agent.sh <agent-name> [--gf [N]] --print # print only
scripts/start-agent.sh --list # list known agentsWithout --print, it resolves the agent's folder and kickoff prompt from README.md, cds into that folder, and runs claude --name <Name> <prompt> — a real, correctly-named session in one command.
| Goal | Command |
|---|---|
| Start Sam as a local session | scripts/start-agent.sh Sam |
| Start Wren's goldfish | scripts/start-agent.sh Wren --gf |
| Start a second goldfish for Wren | scripts/start-agent.sh Wren --gf 2 |
| Get Nora's Cowork paste text | scripts/start-agent.sh Nora --print |
| See all known agent names | scripts/start-agent.sh --list |
/rename <Name> as part of the initial prompt text. That doesn't work — Claude Code's CLI treats the whole multi-line string as the argument to /rename itself, so the session ends up named SAM You're Sam, the Release Coordinator. Read STATE.md — ... (the entire kickoff prompt swallowed into the name), not actually sent as a message. Fixed by using claude's own -n/--name <name> flag instead, which sets the display name directly at launch. If you ever see a session with a name that looks like a whole sentence, that's this bug — /rename is not the tool for scripted session naming.
start-agent.sh can't launch a Cowork Project directly — that's a claude.ai concept, not something a terminal claude process execs into. For Cowork, run it with --print and copy the output:
scripts/start-agent.sh <agent-name> --print (add --gf if starting a goldfish).This is exactly what the retired scripts/agent-prompt.py used to do on its own — folded into start-agent.sh --print instead of keeping two separate scripts.
Once a local-CLI session (Elephant or Goldfish) is running, any other local session can reach it directly — no need to relay through Jake:
ListAgents — see which named sessions are currently live.SendMessage — send a message to one by name (or by the disambiguating ref ListAgents shows if two sessions share a name).This is what let Sage message Sam, Wren's WRENS-GF, and Nora directly on 2026-08-23 and get each one's own STATE.md updated in its own voice — the cross-agent coordination this whole model exists to unlock. Cowork sessions can't be reached this way; only local-CLI sessions (runtimes 2 and 3 above) are addressable.