{"id":44803489,"url":"https://github.com/federiconeri/wiggum-cli","last_synced_at":"2026-03-09T17:29:48.307Z","repository":{"id":337654147,"uuid":"1137793021","full_name":"federiconeri/wiggum-cli","owner":"federiconeri","description":"AI agent that plugs into any codebase — scans your stack, generates specs through AI interviews, and runs Ralph loops.","archived":false,"fork":false,"pushed_at":"2026-03-03T16:23:50.000Z","size":2453,"stargazers_count":3,"open_issues_count":52,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T18:30:17.217Z","etag":null,"topics":["ai","ai-agent","autonomous-coding","claude-code","cli","codex","developer-tools","gemini-cli","loops","open-source","opencode","ralph-loop","spec-generation","typescript"],"latest_commit_sha":null,"homepage":"https://wiggum.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/federiconeri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T21:01:50.000Z","updated_at":"2026-03-02T17:17:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/federiconeri/wiggum-cli","commit_stats":null,"previous_names":["federiconeri/wiggum-cli"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/federiconeri/wiggum-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/federiconeri%2Fwiggum-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/federiconeri%2Fwiggum-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/federiconeri%2Fwiggum-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/federiconeri%2Fwiggum-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/federiconeri","download_url":"https://codeload.github.com/federiconeri/wiggum-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/federiconeri%2Fwiggum-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30304501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T14:33:48.460Z","status":"ssl_error","status_checked_at":"2026-03-09T14:33:48.027Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","autonomous-coding","claude-code","cli","codex","developer-tools","gemini-cli","loops","open-source","opencode","ralph-loop","spec-generation","typescript"],"created_at":"2026-02-16T14:14:13.075Z","updated_at":"2026-03-09T17:29:48.292Z","avatar_url":"https://github.com/federiconeri.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/logo.svg\" alt=\"WIGGUM\" width=\"650\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePlug into any codebase. Generate specs. Ship features while you sleep.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/wiggum-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/wiggum-cli?color=F8DB27\u0026labelColor=1a1a1a\u0026style=flat-square\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/wiggum-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/wiggum-cli?color=F8DB27\u0026labelColor=1a1a1a\u0026style=flat-square\" alt=\"downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/federiconeri/wiggum-cli/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/federiconeri/wiggum-cli/ci.yml?branch=main\u0026color=F8DB27\u0026labelColor=1a1a1a\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/federiconeri/wiggum-cli/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/federiconeri/wiggum-cli?color=F8DB27\u0026labelColor=1a1a1a\u0026style=flat-square\" alt=\"stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/federiconeri/wiggum-cli/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT%20+%20Commons%20Clause-F8DB27?labelColor=1a1a1a\u0026style=flat-square\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/wiggum-cli?color=F8DB27\u0026labelColor=1a1a1a\u0026style=flat-square\" alt=\"node\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#-how-it-works\"\u003eHow It Works\u003c/a\u003e ·\n  \u003ca href=\"https://wiggum.app\"\u003eWebsite\u003c/a\u003e ·\n  \u003ca href=\"https://wiggum.app/blog\"\u003eBlog\u003c/a\u003e ·\n  \u003ca href=\"https://wiggum.app/pricing\"\u003ePricing\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/federiconeri/wiggum-cli/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/817edf0c-a7aa-418f-bf85-499be520fd94\" width=\"800\" controls\u003e\u003c/video\u003e\n\u003c/p\u003e\n\n---\n\n## What is Wiggum?\n\nWiggum is an **AI agent** that plugs into any codebase and makes it ready for autonomous feature development — no configuration, no boilerplate.\n\nIt 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](https://docs.anthropic.com/en/docs/claude-code) or any CLI-based coding agent, running an autonomous **implement → test → fix** loop until the feature ships.\n\nPlug \u0026 play. Point it at a repo. It figures out the rest.\n\n```\n         Wiggum (agent)                    Coding Agent\n  ┌────────────────────────────┐    ┌────────────────────┐\n  │                            │    │                    │\n  │  Scan ──▶ Interview ──▶ Spec ──▶  Run loops           │\n  │  detect      AI-guided   .ralph/   implement         │\n  │  80+ tech    questions   specs     test + fix        │\n  │  plug\u0026play   prompts     guides    until done        │\n  │                            │    │                    │\n  └────────────────────────────┘    └────────────────────┘\n       runs in your terminal          Claude Code / any agent\n```\n\n---\n\n## 🚀 Quick Start\n\n```bash\nnpm install -g wiggum-cli\n```\n\nThen, in your project:\n\n```bash\nwiggum init                  # Scan project, configure AI provider\nwiggum new user-auth         # AI interview → feature spec\nwiggum run user-auth         # Autonomous coding loop\n```\n\nOr skip the global install:\n\n```bash\nnpx wiggum-cli init\n```\n\n---\n\n## ⚡ Features\n\n🔍 **Smart Detection** — Auto-detects 80+ technologies: frameworks, databases, ORMs, testing tools, deployment targets, MCP servers, and more.\n\n🎙️ **AI-Guided Interviews** — Generates detailed, project-aware feature specs through a structured 4-phase interview. No more blank-page problem.\n\n🔁 **Autonomous Coding Loops** — Hands specs to Claude Code (or any agent) and runs implement → test → fix cycles with git worktree isolation.\n\n✨ **Spec Autocomplete** — AI pre-fills spec names from your codebase context when running `/run`.\n\n📥 **Action Inbox** — Review AI decisions inline without breaking your flow. The loop pauses, you approve or redirect, it continues.\n\n📊 **Run Summaries** — See exactly what changed and why after each loop completes, with activity feed and diff stats.\n\n📋 **Tailored Prompts** — Generates prompts, guides, and scripts specific to your stack. Not generic templates — actual context about *your* project.\n\n🔌 **BYOK** — Bring your own API keys. Works with Anthropic, OpenAI, or OpenRouter. Keys stay local, never leave your machine.\n\n🖥️ **Interactive TUI** — Full terminal interface with persistent session state. No flags to remember.\n\n---\n\n## 🎯 How It Works\n\n### 1. Scan\n\n```bash\nwiggum init\n```\n\nWiggum reads your `package.json`, config files, source tree, and directory structure. A multi-agent AI system then analyzes the results:\n\n1. **Planning Orchestrator** — creates an analysis plan based on detected stack\n2. **Parallel Workers** — Context Enricher explores code while Tech Researchers gather best practices\n3. **Synthesis** — merges results, detects relevant MCP servers\n4. **Evaluator-Optimizer** — QA loop that validates and refines the output\n\nOutput: a `.ralph/` directory with configuration, prompts, guides, and scripts — all tuned to your project.\n\n### 2. Spec\n\n```bash\nwiggum new payment-flow\n```\n\nAn AI-guided interview walks you through:\n\n| Phase | What happens |\n|-------|-------------|\n| **Context** | Share reference URLs, docs, or files |\n| **Goals** | Describe what you want to build |\n| **Interview** | AI asks 3–5 clarifying questions |\n| **Generation** | Produces a detailed feature spec in `.ralph/specs/` |\n\n### 3. Loop\n\n```bash\nwiggum run payment-flow\n```\n\nWiggum hands the spec + prompts + project context to your coding agent and runs an autonomous loop:\n\n```\nimplement → run tests → fix failures → repeat\n```\n\nSupports git worktree isolation (`--worktree`) for running multiple features in parallel.\n\n---\n\n## 🖥️ Interactive Mode\n\nRunning `wiggum` with no arguments opens the TUI — the recommended way to use Wiggum:\n\n```bash\n$ wiggum\n```\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `/init` | `/i` | Scan project, configure AI provider |\n| `/new \u003cfeature\u003e` | `/n` | AI interview → feature spec |\n| `/run \u003cfeature\u003e` | `/r` | Run autonomous coding loop |\n| `/monitor \u003cfeature\u003e` | `/m` | Monitor a running feature |\n| `/sync` | `/s` | Re-scan project, update context |\n| `/help` | `/h` | Show commands |\n| `/exit` | `/q` | Exit |\n\n---\n\n## 📁 Generated Files\n\n```\n.ralph/\n├── ralph.config.cjs          # Stack detection results + loop config\n├── prompts/\n│   ├── PROMPT.md             # Implementation prompt\n│   ├── PROMPT_feature.md     # Feature planning\n│   ├── PROMPT_e2e.md         # E2E testing\n│   ├── PROMPT_verify.md      # Verification\n│   ├── PROMPT_review_manual.md  # PR review (manual - stop at PR)\n│   ├── PROMPT_review_auto.md    # PR review (auto - review, no merge)\n│   └── PROMPT_review_merge.md   # PR review (merge - review + auto-merge)\n├── guides/\n│   ├── AGENTS.md             # Agent instructions (CLAUDE.md)\n│   ├── FRONTEND.md           # Frontend patterns\n│   ├── SECURITY.md           # Security guidelines\n│   └── PERFORMANCE.md        # Performance patterns\n├── scripts/\n│   └── feature-loop.sh       # Main loop script\n├── specs/\n│   └── _example.md           # Example spec template\n└── LEARNINGS.md              # Accumulated project learnings\n```\n\n---\n\n## 🔧 CLI Reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ewiggum init [options]\u003c/code\u003e\u003c/summary\u003e\n\nScan the project, detect the tech stack, generate configuration.\n\n| Flag | Description |\n|------|-------------|\n| `--provider \u003cname\u003e` | AI provider: `anthropic`, `openai`, `openrouter` (default: `anthropic`) |\n| `-i, --interactive` | Stay in interactive mode after init |\n| `-y, --yes` | Accept defaults, skip confirmations |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ewiggum new \u0026lt;feature\u0026gt; [options]\u003c/code\u003e\u003c/summary\u003e\n\nCreate a feature specification via AI-powered interview.\n\n| Flag | Description |\n|------|-------------|\n| `--ai` | Use AI interview (default in TUI mode) |\n| `--provider \u003cname\u003e` | AI provider for spec generation |\n| `--model \u003cmodel\u003e` | Model to use |\n| `-e, --edit` | Open in editor after creation |\n| `-f, --force` | Overwrite existing spec |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ewiggum run \u0026lt;feature\u0026gt; [options]\u003c/code\u003e\u003c/summary\u003e\n\nRun the autonomous development loop.\n\n| Flag | Description |\n|------|-------------|\n| `--worktree` | Git worktree isolation (parallel features) |\n| `--resume` | Resume an interrupted loop |\n| `--model \u003cmodel\u003e` | Claude model (`opus`, `sonnet`) |\n| `--max-iterations \u003cn\u003e` | Max iterations (default: 10) |\n| `--max-e2e-attempts \u003cn\u003e` | Max E2E retries (default: 5) |\n| `--review-mode \u003cmode\u003e` | `manual` (stop at PR), `auto` (review, no merge), or `merge` (review + merge). Default: `manual` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ewiggum monitor \u0026lt;feature\u0026gt; [options]\u003c/code\u003e\u003c/summary\u003e\n\nTrack feature development progress in real-time.\n\n| Flag | Description |\n|------|-------------|\n| `--interval \u003cseconds\u003e` | Refresh interval (default: 5) |\n| `--bash` | Use bash monitor script |\n\n\u003c/details\u003e\n\n---\n\n## 🔌 AI Providers\n\nWiggum requires an API key from one of these providers:\n\n| Provider | Environment Variable |\n|----------|---------------------|\n| Anthropic | `ANTHROPIC_API_KEY` |\n| OpenAI | `OPENAI_API_KEY` |\n| OpenRouter | `OPENROUTER_API_KEY` |\n\nOptional services for deeper analysis:\n\n| Service | Variable | Purpose |\n|---------|----------|---------|\n| [Tavily](https://tavily.com) | `TAVILY_API_KEY` | Web search for current best practices |\n| [Context7](https://context7.com) | `CONTEXT7_API_KEY` | Up-to-date documentation lookup |\n\nKeys are stored in `.ralph/.env.local` and never leave your machine.\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003e🔍 Detection Capabilities (80+ technologies)\u003c/h2\u003e\u003c/summary\u003e\n\n| Category | Technologies |\n|----------|-------------|\n| **Frameworks** | Next.js (App/Pages Router), React, Vue, Nuxt, Svelte, SvelteKit, Remix, Astro |\n| **Package Managers** | npm, yarn, pnpm, bun |\n| **Testing** | Jest, Vitest, Playwright, Cypress |\n| **Styling** | Tailwind CSS, CSS Modules, Styled Components, Emotion, Sass |\n| **Databases** | PostgreSQL, MySQL, SQLite, MongoDB, Redis |\n| **ORMs** | Prisma, Drizzle, TypeORM, Mongoose, Kysely |\n| **APIs** | REST, GraphQL, tRPC, OpenAPI |\n| **State** | Zustand, Jotai, Redux, Pinia, Recoil, MobX, Valtio |\n| **UI Libraries** | shadcn/ui, Radix, Material UI, Chakra UI, Ant Design, Headless UI |\n| **Auth** | NextAuth.js, Clerk, Auth0, Supabase Auth, Lucia, Better Auth |\n| **Analytics** | PostHog, Mixpanel, Amplitude, Google Analytics, Plausible |\n| **Payments** | Stripe, Paddle, LemonSqueezy |\n| **Email** | Resend, SendGrid, Postmark, Mailgun |\n| **Deployment** | Vercel, Netlify, Railway, Fly.io, Docker, AWS |\n| **Monorepos** | Turborepo, Nx, Lerna, pnpm workspaces |\n| **MCP** | Detects MCP server/client configs, recommends servers based on stack |\n\n\u003c/details\u003e\n\n---\n\n## 📋 Requirements\n\n- **Node.js** \u003e= 18.0.0\n- **Git** (for worktree features)\n- An AI provider API key (Anthropic, OpenAI, or OpenRouter)\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or another coding agent (for `wiggum run`)\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\ngit clone https://github.com/federiconeri/wiggum-cli.git\ncd wiggum-cli\nnpm install\nnpm run build\nnpm test\n```\n\n---\n\n## 📖 Learn More\n\n- [What Is Wiggum CLI?](https://wiggum.app/blog/what-is-wiggum-cli) — Overview of the autonomous coding agent\n- [What Is the Ralph Loop?](https://wiggum.app/blog/what-is-the-ralph-loop) — Deep dive into the Ralph loop methodology\n- [Wiggum vs Bash Scripts](https://wiggum.app/blog/wiggum-vs-ralph-wiggum-scripts) — Why spec generation matters\n- [Roadmap](https://wiggum.app/roadmap) — What's coming next\n- [Changelog](https://wiggum.app/changelog) — Release history\n\n---\n\n## 📄 License\n\n**MIT + Commons Clause** — see [LICENSE](LICENSE).\n\nYou can use, modify, and distribute Wiggum freely. You may **not** sell the software or a service whose value derives substantially from Wiggum's functionality.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built on the \u003ca href=\"https://ghuntley.com/ralph/\"\u003eRalph loop technique\u003c/a\u003e by Geoffrey Huntley\n\u003c/p\u003e\n","funding_links":[],"categories":["Ecosystem"],"sub_categories":["GateGuard — Fact-Forcing PreToolUse Gate"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedericoneri%2Fwiggum-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffedericoneri%2Fwiggum-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedericoneri%2Fwiggum-cli/lists"}