init - Wiggum

wiggum init [options]

Scans your project and generates a .ralph/ directory with configuration, prompts, guides, and scripts tailored to your codebase.

What happens

The init process has six phases:

Scanning

Wiggum runs parallel detectors across your project to identify your tech stack. Detects 80+ technologies including:

Core — Framework, package manager, testing (unit + E2E), styling
Data — Database, ORM, API layer
Frontend — State management, UI components, form handling
Services — Auth, analytics
Infra — Hosting, CI/CD, MCP servers

Each detection includes a confidence score (0-100).

Provider selection

Choose your AI provider: Anthropic, OpenAI, or OpenRouter.

API key

Enter your API key. Wiggum saves it to .ralph/.env.local (gitignored) so you don’t need to re-enter it.

Model selection

Pick models for each purpose:

Planning model (e.g. Opus) — Handles spec generation, architectural decisions, and verification
Implementation model (e.g. Sonnet) — Handles the coding loop

AI analysis

Wiggum runs an agentic analysis of your codebase, producing structured context:

Entry points and key files
Directory purposes
Build, dev, test, lint commands
Naming conventions
Project-specific implementation guidelines

File generation

Creates the .ralph/ directory with all configuration, prompts, guides, and scripts.

Flags

--provider

string

default:"anthropic"

AI provider to use. Options: anthropic, openai, openrouter.

-i, --interactive

boolean

default:"false"

Stay in interactive TUI mode after init completes.

-y, --yes

boolean

default:"false"

Accept all defaults and skip confirmation prompts.

Output

Creates the .ralph/ directory:

.ralph/
├── ralph.config.cjs          # Stack detection + loop config
├── .env.local                # API keys (gitignored)
├── .context.json             # Codebase analysis results
├── prompts/
│   ├── PROMPT.md.tmpl             # Implementation prompt
│   ├── PROMPT_feature.md.tmpl     # Planning phase prompt
│   ├── PROMPT_e2e.md.tmpl         # E2E testing prompt
│   ├── PROMPT_verify.md.tmpl      # Verification prompt
│   ├── PROMPT_review_manual.md.tmpl  # Manual review prompt
│   ├── PROMPT_review_auto.md.tmpl    # Auto review prompt
│   └── PROMPT_review_merge.md.tmpl   # Auto-merge review prompt
├── guides/
│   ├── AGENTS.md             # Agent instructions
│   └── ...                   # Project-specific guides
├── scripts/
│   ├── feature-loop.sh       # The Ralph loop engine
│   └── ralph-monitor.sh      # Monitoring script
├── specs/
│   └── _example.md           # Example spec template
└── LEARNINGS.md              # Accumulated project learnings

See configuration for details on each file and setting.

Examples

wiggum
# then type /init in the TUI

wiggum init --provider anthropic --yes

To rescan your project after changes without repeating the full init flow, use wiggum sync.

​What happens

​Flags

​Output

​Examples

What happens

Flags

Output

Examples