JSPM

Plug into any codebase. Generate specs. Ship features while you sleep.

Quick Start · How It Works · Website · Issues

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, Codex, 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 / Codex

🚀 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.

📋 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:

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

📁 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 + 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

🔌 AI Providers

Wiggum requires an API key from one of these providers:

Optional services for deeper analysis:

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

📋 Requirements

• Node.js >= 18.0.0
• Git (for worktree features)
• An AI provider API key (Anthropic, OpenAI, or OpenRouter)
• Claude Code or another coding agent (for wiggum run)

🤝 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

📄 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.

Built on the Ralph loop technique by Geoffrey Huntley