Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Headless Mode

Use swarmie prompt for non-interactive runs in scripts, CI, and automation.

For persistent API/SSE access by external systems, use swarmie server (headless API-only server) instead of swarmie prompt.

Primary sources:

  • CLI args: crates/cli/src/cli.rs
  • Runtime behavior: crates/cli/src/cmd/oneshot.rs
  • API server command: crates/cli/src/cmd/server.rs (run_headless)

API-only server for integrations

Use this when you want a long-running HTTP endpoint without launching the web UI:

swarmie server
swarmie server --hostname 0.0.0.0 --port 4200
swarmie server --password "secret" --cors https://client.example.com

Key behavior:

  • Default bind address is 0.0.0.0 for external access.
  • SPA routes are disabled in this mode (API-only surface).
  • Password resolution follows --password, then SWARMIE_SERVER_PASSWORD (used as first-run auth bootstrap password).

Basic usage

swarmie prompt "Summarize this repository"

Prompt input rules:

  • swarmie prompt "...": uses argument text
  • swarmie prompt -: reads stdin
  • swarmie prompt with no arg: reads stdin

Key flags

swarmie prompt "Check TODOs" --model sonnet --provider openai
swarmie prompt - --json < prompt.txt
swarmie prompt "Apply patch" --dangerously-bypass-approvals
swarmie prompt "Analyze" -C /path/to/workspace
swarmie prompt "Review changes" --worktree
swarmie prompt "Apply in main tree" --worktree --worktree-result apply
swarmie prompt "Queue via stash" --worktree --worktree-result stash

Behavior details:

  • --json emits JSONL with event debug payloads ({"event":"..."})
  • Without --json, assistant text is streamed as plain output
  • In non-interactive mode, permission requests are denied unless --dangerously-bypass-approvals is set
  • --worktree runs the session in a temporary git worktree under .swarmie/worktrees/
  • --worktree-result commit keeps the worktree and branch, then prints the preserved path
  • --worktree-result apply removes the worktree and applies staged changes to the main tree
  • --worktree-result stash does apply, then git stash push to keep the main tree clean

Worktree edge cases

  • -C/--cd changes which repository is validated and where the worktree is created.
  • If the target working tree is dirty, Swarmie auto-stashes before creating the worktree.
  • Concurrent --worktree sessions are isolated by unique session IDs and per-session branches.
  • If teardown fails, Swarmie prints a warning and leaves cleanup for manual follow-up.

Worktree workflows

CI pipeline with preserved artifacts

Use commit (default) so CI can inspect the preserved worktree path and branch after the run.

swarmie prompt "Generate migration plan" --worktree --json > events.jsonl

Exploratory prompts without touching current tree

Use stash to safely queue results while keeping your working tree clean.

swarmie prompt "Prototype refactor options" --worktree --worktree-result stash

Review-then-apply pattern

Use apply to bring staged changes back into your main tree for immediate review.

swarmie prompt "Prepare patch for review" --worktree --worktree-result apply
git diff --staged

CI/CD example

name: swarmie-headless
on: [workflow_dispatch]
 
jobs:
  run-agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Swarmie prompt
        run: |
          cat <<'PROMPT' | swarmie prompt - --json > swarmie-events.jsonl
          Review crates/core/src for error handling gaps and propose fixes.
          PROMPT
      - name: Upload events
        uses: actions/upload-artifact@v4
        with:
          name: swarmie-events
          path: swarmie-events.jsonl

Only use --dangerously-bypass-approvals in trusted, controlled environments.