Skip to main content
Headless mode runs wiggum commands directly without the TUI. Use this for CI pipelines, scripting, and integration with other agents.

​
Commands

wiggum init [options]              # Scan project, configure AI
wiggum new <name> [options]        # Create feature spec
wiggum run <name> [options]        # Run the Ralph loop
wiggum monitor <name> [options]    # Monitor a running loop
wiggum sync                        # Refresh codebase context
wiggum config set <key> <value>    # Manage settings
wiggum agent [options]             # Autonomous backlog processing

​
When to use headless mode

  • CI/CD pipelines — Run wiggum in automated workflows
  • Agent orchestration — Let other AI agents invoke wiggum programmatically
  • Scripting — Chain wiggum commands in shell scripts
  • Non-interactive terminals — Environments without TTY support
In a TTY terminal, wiggum monitor and wiggum agent automatically open the TUI. Use --stream to force headless output.

​
Common headless workflows

​
Generate spec from GitHub issue

wiggum new my-feature --auto --goals "Add user notifications endpoint" --issue #42
The --auto flag skips the interactive interview and generates a spec directly from the goals and issue context.

​
Run a Ralph loop with auto-merge

wiggum run my-feature --worktree --review-mode merge

​
Process GitHub backlog in CI

wiggum agent --stream --review-mode merge --labels P0 --max-items 5

​
Full pipeline in one script

#!/bin/bash
wiggum init --provider anthropic --yes
wiggum new my-feature --auto --goals "Add dark mode toggle" --issue #42
wiggum run my-feature --worktree --review-mode merge

​
Pass options inline

Headless mode accepts all configuration via flags instead of interactive prompts: 
wiggum init --provider anthropic --yes
wiggum new auth-flow --auto --goals "JWT auth middleware" --issue #42 --force
wiggum run auth-flow --worktree --cli codex --review-cli claude --max-iterations 15 --review-mode auto
wiggum agent --stream --labels P0,bug --max-items 3 --review-mode merge
See the commands reference for all available flags.