murmur spawn CLI command

Starts a new agent in a workspace. The agent provisions a VM, clones the current repository at the current branch, and begins working on the given task. In autonomous mode, the agent works independently and reports results. In interactive mode, it runs in a tmux session you connect to with murmur ssh. The current branch must be pushed to origin before spawning — the agent clones from the remote, not from your local working tree.

Synopsis

murmur spawn [flags] <slug> [prompt...]

The slug is a short identifier for this agent — it appears in status output, PR titles, and logs. The prompt is the task description: everything after the slug is joined into a single string. The prompt is required in autonomous mode and optional in interactive mode. When --flight is set, the slug is optional — it defaults to flight-<name>.

Arguments

Name	Type	Required	Description
`slug`	string	yes (unless `--flight` set)	Short identifier for the agent. Must be unique within the workspace. With `--flight`, defaults to `flight-<name>`.
`prompt`	string	autonomous	Task description. Required for autonomous mode, optional for interactive mode. All words after the slug are joined.
`-i`	bool	no	Interactive mode — the agent runs in a tmux session. Connect with `murmur ssh`. Default: `false`.
`--purpose`	string	no	One-sentence human-readable goal (max 240 chars). Shown in the dashboard.
`--agent`	string	no	Agent persona name (e.g. `programmer`, `architect`, `pm`).
`--model`	string	no	Model name (e.g. `claude-opus-4-8`, `gpt-5-4`). Overrides the value in `murmur.yaml` and the persona’s model — see Model Selection for the full precedence chain. Implies the backend.
`--backend`	string	no	Override the inferred backend. Usually unnecessary — set automatically from `--model`.
`--service-profile`	string	no	Spawn under this service profile (a borrow that requires the `service-profile.assume` permission). Overrides the `service_profile` default set in `murmur.yaml`.
`--repo`	string	no	Additional repo to clone. Format: `URL`, `URL=base`, or `URL=base:working`. Repeatable.
`--fork-from`	string	no	Fork from another agent’s session. Pass the source agent’s slug. The new agent starts with the source agent’s context. Use a distinct slug to avoid branch name conflicts.
`--resurrect`	bool	no	Restore context from a prior session for this slug. Mutually exclusive with `--force-new`. Default: `false`.
`--force-new`	bool	no	Start fresh even if a prior session exists for this slug. Mutually exclusive with `--resurrect`. Default: `false`.
`--append-system-prompt`	string	no	Text appended to the agent’s system prompt.
`--out`	string	no	Expected output artifact: `pr`, `push`, `respond`, or freeform text.
`--task`	string	no	Checklist item the agent must complete. Repeatable — pass multiple `--task` flags for a multi-step checklist.
`--tag`	string	no	Attach a tag by name for dashboard grouping and filtering. Repeatable, max 8. Each name must be a DNS-label slug (`[a-z0-9][a-z0-9-]{0,62}`); a name that does not yet exist is created automatically.
`--pilot`	bool	no	Run with the completion assessor loop, which verifies the agent’s work before marking the task complete. Default: `false`.
`--stream`	bool	no	Use the streaming backend (long-lived session). Default: `false`.
`--on-idle`	string	no	What happens when the agent finishes its task and has no follow-ups. Values: `sleep` (default), `terminate`, `keep-alive`.
`--dequeue-strategy`	string	no	How the agent processes queued follow-ups. Values: `auto` (default — up to five follow-ups of one kind per turn; manual follow-ups and auto-generated events never share a turn), `all`, `one`, `five`.
`--suppress-events`	string	no	GitHub event classes this agent ignores (never woken by), comma-separated: `ci` (CI results), `pr_comments` (PR comments and reviews). `none` forces full subscription, overriding a `suppress_events` default from `murmur.yaml` / `murmur.local.yaml`; empty inherits it. Suppressed events are still recorded on the agent’s timeline.
`--workspace`	string	no	Workspace name. Required if not set in `murmur.yaml`.
`--wait`	bool	no	Block until the agent is terminal or at rest (task finished, idle, or sleeping with nothing queued). Prints a one-line outcome and the agent’s status on exit. Default: `false`.
`--flight`	string	no	Flight name. Resolves the flight from the tenant catalog and spawns a pilot agent to execute it.
`--input`	string	no	Flight context input as `key=value`. Repeatable. Only valid with `--flight`.
`-e`	string	no	Forward an environment variable to the agent as a secret. `-e FOO` reads from your current environment; `-e FOO=bar` sets it explicitly. Repeatable. Names must match `[A-Z][A-Z0-9_]*`, cannot start with `MURMUR_`, and cannot be a credential name such as `GH_TOKEN`, `CLAUDE_TOKEN`, or `SIGNING_KEY` — those belong to the identity the agent runs as. Top-level spawns only — a child agent inherits its parent’s secrets, so a child request naming one is rejected rather than ignored. Works with `--service-profile` as well; only `GH_TOKEN` is left to the profile.
`--propose`	bool	no	Stage a `SpawnAction` change-request `PENDING` for review instead of spawning. Requires a service profile (`--service-profile` or the `service_profile` default in `murmur.yaml`) — a proposed spawn runs as the profile, never as you. Only the flags a `SpawnAction` carries are allowed: `--workspace`, `--service-profile`, `--agent`, `--model`, `--out`, `--tag`, `--on-idle` (`sleep` or `terminate`), `--purpose`, `--task`, `--reasoning-effort`, `--suppress-events`, `--dequeue-strategy`, `--suggest-terminate-mode`; any other flag fails loudly. Default: `false`.
`--rationale`	string	no	Rationale recorded on the change-request. Only with `--propose`.

Output

On success, prints the spawned agent’s slug and a summary of follow-up commands:

Spawned: fix-auth

  To get the status of the task:                murmur status fix-auth
  To kill the task:                             murmur kill fix-auth
  To send a follow-up:                          murmur queue add fix-auth "additional context"

In interactive mode, an additional line shows how to connect:

  To SSH into the VM:                           murmur ssh fix-auth

When --wait is set, the command blocks until the agent is terminal or at rest, then prints a one-line outcome (wait ended: …) and the agent’s full status (same format as murmur status).

Examples

Spawn an autonomous agent

murmur spawn fix-auth Fix the JWT expiry validation in the auth middleware

Spawned: fix-auth

  To get the status of the task:                murmur status fix-auth
  To kill the task:                             murmur kill fix-auth
  To send a follow-up:                          murmur queue add fix-auth "additional context"

Spawn in interactive mode

murmur spawn -i explore-api

Spawned: explore-api

  To get the status of the task:                murmur status explore-api
  To kill the task:                             murmur kill explore-api
  To send a follow-up:                          murmur queue add explore-api "additional context"
  To SSH into the VM:                           murmur ssh explore-api

Connect with murmur ssh explore-api to interact with the agent directly.

Spawn with a persona

murmur spawn --agent architect design-review Review the database schema for the new billing tables

The --agent flag selects an agent persona — a predefined configuration that shapes the agent’s behavior and system prompt.

Override the repo and base branch

murmur spawn --repo https://github.com/acme/frontend=main fix-styles Update button styles to match the new design system

By default, the agent clones the repo and branch you are currently on. Use --repo to add additional repos or override the base branch. The format is URL=base or URL=base:working.

Spawn in a specific workspace

murmur spawn --workspace backend fix-auth Fix the JWT expiry validation

If your murmur.yaml already sets a workspace, you can omit --workspace.

Fork from another agent

murmur spawn --fork-from fix-auth add-tests Write tests for the auth middleware changes

The new agent starts with all the context from the fix-auth agent’s session. Always use a distinct slug when forking to avoid branch name conflicts.

Resurrect a previous session

murmur spawn --resurrect fix-auth Continue where you left off on the auth fix

Restores the agent’s prior context for the fix-auth slug. If a previous session is still shutting down, the command waits for it to finish before spawning.

Wait for completion

murmur spawn --wait fix-auth Fix the JWT expiry validation

The command blocks until the agent is terminal or at rest — under the default on_idle: sleep policy a finished agent rests rather than completing — then prints the outcome and the agent’s full status.

Forward environment variables

murmur spawn -e API_KEY -e DATABASE_URL=postgres://localhost/mydb fix-auth Fix the auth middleware

-e API_KEY reads the value from your current shell environment. -e DATABASE_URL=postgres://localhost/mydb sets it explicitly. The agent receives these as environment variables on its VM. Values are encrypted by the server before they reach the agent’s VM. To give a whole subtree the same variable, set it on the top-level spawn: children inherit their parent’s secrets. Which identity the agent runs as is independent of this — a spawn under a service profile delivers -e values beside the profile’s own credentials, and only GH_TOKEN is left to the profile’s minted GitHub token.

Execute a flight

murmur spawn --flight billing-migration --input customer_id=acme

Resolves the billing-migration flight from the tenant catalog and spawns a pilot agent to execute it. The slug defaults to flight-billing-migration. Pass --input to provide context variables the flight expects.

Spawn with a task checklist

murmur spawn --task "Add input validation" --task "Write unit tests" --task "Update the README" fix-auth Improve the auth middleware

Each --task flag adds a checklist item the agent tracks and completes.

Tag an agent

murmur spawn --tag release-blocker --tag backend fix-auth Fix the JWT expiry validation

Each --tag attaches a tag for grouping and filtering in the dashboard. A tag name that does not yet exist is created automatically.

Propose a spawn for review

murmur spawn --propose --service-profile infra-bot --rationale "nightly dep bump" \
    bump-deps Update all Go dependencies and open a PR

created change-request cr-a1b2c3 for spawn of bump-deps (pending review)

Nothing spawns yet: the command stages a SpawnAction change-request PENDING for review. A reviewer’s approval (for example murmur change-request approve) executes the spawn under the infra-bot service profile — the agent acts as the profile, never as the proposer or approver. Proposing needs change-request.create plus workspace.read; approval needs service-profile.assume on the profile.

Errors

Code	Meaning	What to do
`ALREADY_EXISTS`	An agent with this slug is already running.	Send a follow-up with `murmur queue add`, or use `--force-new` to replace the running agent.
`INVALID_ARGUMENT`	A flag value is invalid (e.g. unknown dequeue strategy, invalid secret name).	Check the error message for the specific flag and correct the value.
`UNAUTHENTICATED`	Identity token is missing or expired.	Run `murmur auth` or check your `murmur.local.yaml` configuration.
`branch not found on origin`	The current git branch has not been pushed to `origin`.	Push your branch with `git push -u origin HEAD` and retry.
`--workspace is required`	No workspace is configured.	Pass `--workspace` or set the workspace in `murmur.yaml`.
`description required for autonomous mode`	No prompt was provided for an autonomous spawn.	Add a task description after the slug, or use `-i` for interactive mode.
`--resurrect and --force-new are mutually exclusive`	Both flags were passed.	Use one or the other.
`flag-like argument ... after the first positional`	A flag was placed after the slug. Flag parsing stops at the first positional, so the flag would silently fold into the description instead of applying.	Move all flags before the slug. To spawn a description containing literal dash-prefixed words, pass `--` before the positionals.
`--rationale only applies with --propose`	`--rationale` was passed on a direct spawn, which creates no change-request.	Add `--propose`, or drop `--rationale`.
`... cannot be used with --propose`	A flag a `SpawnAction` change-request cannot express (e.g. `--repo`, `--wait`, `-e`) was passed with `--propose`.	Drop the flag — a proposed spawn carries only the slug, description, workspace, service profile, persona, model, expected output, tags, idle behavior, purpose, task checklist, reasoning effort, suppressed event classes, dequeue strategy, and suggest-terminate mode.
`--service-profile is required with --propose`	A proposed spawn is service-profile-owned; no profile was given and `murmur.yaml` sets no default.	Pass `--service-profile`, or set `service_profile` in `murmur.yaml`.

Agents — what agents are and how they work
Workspaces — the workspace that agents run in
Agent personas — predefined agent configurations
Tags — labels for grouping and filtering agents
Flights — multi-step flight plans
murmur status — check an agent’s current state
murmur ls — list running agents
murmur kill — cancel a running agent
murmur wait — block until an agent reaches a target phase
murmur queue add — send a follow-up message to a running agent
murmur ssh — connect to an interactive agent’s tmux session

Getting Started

Core Concepts

Guides

murmur spawn CLI command

Synopsis

Arguments

Output

Examples

Spawn an autonomous agent

Spawn in interactive mode

Spawn with a persona

Override the repo and base branch

Spawn in a specific workspace

Fork from another agent

Resurrect a previous session

Wait for completion

Forward environment variables

Execute a flight

Spawn with a task checklist

Tag an agent

Propose a spawn for review

Errors

​Synopsis

​Arguments

​Output

​Examples

​Spawn an autonomous agent

​Spawn in interactive mode

​Spawn with a persona

​Override the repo and base branch

​Spawn in a specific workspace

​Fork from another agent

​Resurrect a previous session

​Wait for completion

​Forward environment variables

​Execute a flight

​Spawn with a task checklist

​Tag an agent

​Propose a spawn for review

​Errors

​Related

Synopsis

Arguments

Output

Examples

Spawn an autonomous agent

Spawn in interactive mode

Spawn with a persona

Override the repo and base branch

Spawn in a specific workspace

Fork from another agent

Resurrect a previous session

Wait for completion

Forward environment variables

Execute a flight

Spawn with a task checklist

Tag an agent

Propose a spawn for review

Errors

Related