> ## Documentation Index
> Fetch the complete documentation index at: https://wiggum.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless mode

> Run wiggum commands directly from your shell for CI, scripting, and agent integration.

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

## Commands

```bash theme={null}
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

<Note>
  In a TTY terminal, `wiggum monitor` and `wiggum agent` automatically open the TUI. Use `--stream` to force headless output.
</Note>

## Common headless workflows

### Generate spec from GitHub issue

```bash theme={null}
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

```bash theme={null}
wiggum run my-feature --worktree --review-mode merge
```

### Process GitHub backlog in CI

```bash theme={null}
wiggum agent --stream --review-mode merge --labels P0 --max-items 5
```

### Full pipeline in one script

```bash theme={null}
#!/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:

```bash theme={null}
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](/commands/init) for all available flags.