What is Wiggum?

Wiggum is an AI agent that plugs into any codebase and makes it ready for autonomous feature development — no configuration, no boilerplate.

It works in two phases. First, Wiggum itself is the agent: it scans your project, detects your stack, and runs an AI-guided interview to produce detailed specs, prompts, and scripts — all tailored to your codebase. Then it delegates the actual coding to Claude Code or any CLI-based coding agent, running an autonomous implement → test → fix loop until the feature ships.

Plug & play. Point it at a repo. It figures out the rest.

         Wiggum (agent)                    Coding Agent
  ┌────────────────────────────┐    ┌────────────────────┐
  │                            │    │                    │
  │  Scan ──▶ Interview ──▶ Spec ──▶  Run loops           │
  │  detect      AI-guided   .ralph/   implement         │
  │  80+ tech    questions   specs     test + fix        │
  │  plug&play   prompts     guides    until done        │
  │                            │    │                    │
  └────────────────────────────┘    └────────────────────┘
       runs in your terminal          Claude Code / any agent

🚀 Quick Start

npm install -g wiggum-cli

Then, in your project:

wiggum init                  # Scan project, configure AI provider
wiggum new user-auth         # AI interview → feature spec
wiggum run user-auth         # Autonomous coding loop

Or skip the global install:

npx wiggum-cli init

⚡ Features

🔍 Smart Detection — Auto-detects 80+ technologies: frameworks, databases, ORMs, testing tools, deployment targets, MCP servers, and more.

🎙️ AI-Guided Interviews — Generates detailed, project-aware feature specs through a structured 4-phase interview. No more blank-page problem.

🔁 Autonomous Coding Loops — Hands specs to Claude Code (or any agent) and runs implement → test → fix cycles with git worktree isolation.

✨ Spec Autocomplete — AI pre-fills spec names from your codebase context when running /run.

📥 Action Inbox — Review AI decisions inline without breaking your flow. The loop pauses, you approve or redirect, it continues.

📊 Run Summaries — See exactly what changed and why after each loop completes, with activity feed and diff stats.

📋 Tailored Prompts — Generates prompts, guides, and scripts specific to your stack. Not generic templates — actual context about your project.

🔌 BYOK — Bring your own API keys. Works with Anthropic, OpenAI, or OpenRouter. Keys stay local, never leave your machine.

🖥️ Interactive TUI — Full terminal interface with persistent session state. No flags to remember.

🎯 How It Works

1. Scan

wiggum init

Wiggum reads your package.json, config files, source tree, and directory structure. A multi-agent AI system then analyzes the results:

1. Planning Orchestrator — creates an analysis plan based on detected stack
2. Parallel Workers — Context Enricher explores code while Tech Researchers gather best practices
3. Synthesis — merges results, detects relevant MCP servers
4. Evaluator-Optimizer — QA loop that validates and refines the output

Output: a .ralph/ directory with configuration, prompts, guides, and scripts — all tuned to your project.

2. Spec

wiggum new payment-flow

An AI-guided interview walks you through:

| Phase | What happens | |-------|-------------| | Context | Share reference URLs, docs, or files | | Goals | Describe what you want to build | | Interview | AI asks 3–5 clarifying questions | | Generation | Produces a detailed feature spec in .ralph/specs/ |

3. Loop

wiggum run payment-flow

Wiggum hands the spec + prompts + project context to your coding agent and runs an autonomous loop:

implement → run tests → fix failures → repeat

Supports git worktree isolation (--worktree) for running multiple features in parallel.

🖥️ Interactive Mode

Running wiggum with no arguments opens the TUI — the recommended way to use Wiggum:

$ wiggum

| Command | Alias | Description | |---------|-------|-------------| | /init | /i | Scan project, configure AI provider | | /new <feature> | /n | AI interview → feature spec | | /run <feature> | /r | Run autonomous coding loop | | /monitor <feature> | /m | Monitor a running feature | | /sync | /s | Re-scan project, update context | | /help | /h | Show commands | | /exit | /q | Exit |

📁 Generated Files

.ralph/
├── ralph.config.cjs          # Stack detection results + loop config
├── prompts/
│   ├── PROMPT.md             # Implementation prompt
│   ├── PROMPT_feature.md     # Feature planning
│   ├── PROMPT_e2e.md         # E2E testing
│   ├── PROMPT_verify.md      # Verification
│   ├── PROMPT_review_manual.md  # PR review (manual - stop at PR)
│   ├── PROMPT_review_auto.md    # PR review (auto - review, no merge)
│   └── PROMPT_review_merge.md   # PR review (merge - review + auto-merge)
├── guides/
│   ├── AGENTS.md             # Agent instructions (CLAUDE.md)
│   ├── FRONTEND.md           # Frontend patterns
│   ├── SECURITY.md           # Security guidelines
│   └── PERFORMANCE.md        # Performance patterns
├── scripts/
│   └── feature-loop.sh       # Main loop script
├── specs/
│   └── _example.md           # Example spec template
└── LEARNINGS.md              # Accumulated project learnings

🔧 CLI Reference

Scan the project, detect the tech stack, generate configuration.

| Flag | Description | |------|-------------| | --provider <name> | AI provider: anthropic, openai, openrouter (default: anthropic) | | -i, --interactive | Stay in interactive mode after init | | -y, --yes | Accept defaults, skip confirmations |

Create a feature specification via AI-powered interview.

| Flag | Description | |------|-------------| | --ai | Use AI interview (default in TUI mode) | | --provider <name> | AI provider for spec generation | | --model <model> | Model to use | | -e, --edit | Open in editor after creation | | -f, --force | Overwrite existing spec |

Run the autonomous development loop.

| Flag | Description | |------|-------------| | --worktree | Git worktree isolation (parallel features) | | --resume | Resume an interrupted loop | | --model <model> | Model id override (applied per CLI; Codex defaults to gpt-5.3-codex) | | --cli <cli> | Implementation CLI: claude or codex | | --review-cli <cli> | Review CLI: claude or codex | | --max-iterations <n> | Max iterations (default: 10) | | --max-e2e-attempts <n> | Max E2E retries (default: 5) | | --review-mode <mode> | manual (stop at PR), auto (review, no merge), or merge (review + merge). Default: manual |

For loop models:

• Claude CLI phases use defaultModel / planningModel (defaults: sonnet / opus).
• Codex CLI phases default to gpt-5.3-codex across all phases.

Track feature development progress in real-time.

| Flag | Description | |------|-------------| | --interval <seconds> | Refresh interval (default: 5) | | --bash | Use bash monitor script |

🔌 AI Providers

Wiggum requires an API key from one of these providers:

| Provider | Environment Variable | |----------|---------------------| | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | OpenRouter | OPENROUTER_API_KEY |

Optional services for deeper analysis:

| Service | Variable | Purpose | |---------|----------|---------| | Tavily | TAVILY_API_KEY | Web search for current best practices | | Context7 | CONTEXT7_API_KEY | Up-to-date documentation lookup |

Keys are stored in .ralph/.env.local and never leave your machine.

| Category | Technologies | |----------|-------------| | Frameworks | Next.js (App/Pages Router), React, Vue, Nuxt, Svelte, SvelteKit, Remix, Astro | | Package Managers | npm, yarn, pnpm, bun | | Testing | Jest, Vitest, Playwright, Cypress | | Styling | Tailwind CSS, CSS Modules, Styled Components, Emotion, Sass | | Databases | PostgreSQL, MySQL, SQLite, MongoDB, Redis | | ORMs | Prisma, Drizzle, TypeORM, Mongoose, Kysely | | APIs | REST, GraphQL, tRPC, OpenAPI | | State | Zustand, Jotai, Redux, Pinia, Recoil, MobX, Valtio | | UI Libraries | shadcn/ui, Radix, Material UI, Chakra UI, Ant Design, Headless UI | | Auth | NextAuth.js, Clerk, Auth0, Supabase Auth, Lucia, Better Auth | | Analytics | PostHog, Mixpanel, Amplitude, Google Analytics, Plausible | | Payments | Stripe, Paddle, LemonSqueezy | | Email | Resend, SendGrid, Postmark, Mailgun | | Deployment | Vercel, Netlify, Railway, Fly.io, Docker, AWS | | Monorepos | Turborepo, Nx, Lerna, pnpm workspaces | | MCP | Detects MCP server/client configs, recommends servers based on stack |

📋 Requirements

• Node.js >= 18.0.0
• Git (for worktree features)
• An AI provider API key (Anthropic, OpenAI, or OpenRouter)
• A supported coding CLI for loop execution: Claude Code and/or Codex CLI

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

git clone https://github.com/federiconeri/wiggum-cli.git
cd wiggum-cli
npm install
npm run build
npm test

📖 Learn More

• What Is Wiggum CLI? — Overview of the autonomous coding agent
• What Is the Ralph Loop? — Deep dive into the Ralph loop methodology
• Wiggum vs Bash Scripts — Why spec generation matters
• Roadmap — What's coming next
• Changelog — Release history

📄 License

MIT + Commons Clause — see LICENSE.

You can use, modify, and distribute Wiggum freely. You may not sell the software or a service whose value derives substantially from Wiggum's functionality.