██████╗  ██████╗ ██╗     ███████╗███╗   ███╗
  ██╔════╝ ██╔═══██╗██║     ██╔════╝████╗ ████║
  ██║  ███╗██║   ██║██║     █████╗  ██╔████╔██║
  ██║   ██║██║   ██║██║     ██╔══╝  ██║╚██╔╝██║
  ╚██████╔╝╚██████╔╝███████╗███████╗██║ ╚═╝ ██║
   ╚═════╝  ╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝

"Ruby's son is a doctor, and you're letting a computer write your code?"

Golem is an autonomous coding loop that implements features while you watch (or grab coffee). Define your specs, kick off the loop, and let it work through your task list—implementing, testing, simplifying, and committing along the way.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ITERATION 3  │  9 tasks remaining
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

▶ Step 1: Implement
  ✓ Added user authentication endpoint
  ✓ Tests passing (14 passed)
  ✓ Committed: feat(auth): add login endpoint

▶ Step 2: Simplify
  ✓ Flattened nested conditionals
  ✓ Tests passing (14 passed)
  ✓ Committed: refactor: simplify auth logic

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ITERATION 4  │  8 tasks remaining
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                         YOU                                     │
│                                                                 │
│   "I need user auth, a REST API for tasks, and filtering"      │
│                              │                                  │
│                              ▼                                  │
│                  ┌────────────────────┐                         │
│                  │ claude             │  ← Interactive          │
│                  │   → /golem:spec    │    conversation         │
│                  └────────────────────┘                         │
│                              │                                  │
│                              ▼                                  │
│                      .golem/specs/*.md                          │
│                              │                                  │
├──────────────────────────────┼──────────────────────────────────┤
│                         GOLEM                                   │
│                              │                                  │
│                              ▼                                  │
│                    ┌────────────────┐                           │
│                    │ golem run plan │  ← Analyzes specs         │
│                    └────────────────┘    vs. codebase           │
│                              │                                  │
│                              ▼                                  │
│               .golem/IMPLEMENTATION_PLAN.md                     │
│                              │                                  │
│                              ▼                                  │
│                   ┌─────────────────┐                           │
│                   │ golem run build │  ← Autonomous loop        │
│                   └─────────────────┘                           │
│                              │                                  │
│            ┌─────────────────┼─────────────────┐                │
│            ▼                 ▼                 ▼                │
│     ┌────────────┐   ┌────────────┐   ┌────────────┐           │
│     │ Implement  │ → │    Test    │ → │  Simplify  │ → Commit  │
│     └────────────┘   └────────────┘   └────────────┘     │     │
│            ▲                                             │     │
│            └─────────────── Loop ────────────────────────┘     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Installation

# npm
npx golem-cc

# pnpm
pnpm dlx golem-cc

# yarn
yarn dlx golem-cc

# bun
bunx golem-cc

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

Quick Start

# 1. Initialize in your project
cd my-project
golem --init

# 2. Define what you're building (interactive)
claude
> /golem:spec
> exit

# 3. Generate the task list
golem run plan

# 4. Let it rip
golem run build

The Loop

Each iteration runs two separate sessions with fresh context:

Step 1: Implement

• Picks the next task from .golem/IMPLEMENTATION_PLAN.md
• Implements the feature/fix
• Runs tests until they pass
• Updates the plan
• Commits

Step 2: Simplify

• Analyzes the code just written
• Removes AI artifacts (unnecessary comments, dead code)
• Flattens nested logic
• Improves naming
• Runs tests to verify no regressions
• Commits

Then it loops. Fresh context each time. No degradation.

Commands

CLI Commands

| Command | Description | |---------|-------------| | golem --init | Initialize golem in current project | | golem run plan | Create implementation plan from specs | | golem run build | Run the autonomous build loop | | golem simplify | Run code simplifier on demand | | golem status | Show progress |

Slash Commands (inside Claude)

| Command | Description | |---------|-------------| | /golem:spec | Build specs through guided conversation | | /golem:plan | Create implementation plan | | /golem:build | Run build loop (single iteration) | | /golem:simplify | Run code simplifier | | /golem:status | Show project status | | /golem:help | Show all commands |

Options

golem run build --iterations 10    # Stop after 10 tasks
golem run build --no-simplify      # Skip simplification step

Project Structure

After running golem --init:

my-project/
└── .golem/
    ├── prompts/              # Loop instructions (customizable)
    │   ├── PROMPT_build.md
    │   └── PROMPT_plan.md
    ├── agents/               # AI agent definitions
    │   ├── spec-builder.md
    │   └── code-simplifier.md
    ├── specs/                # Your requirements (one file per topic)
    │   ├── authentication.md
    │   └── task-api.md
    ├── AGENTS.md             # Test/build/lint commands
    └── IMPLEMENTATION_PLAN.md  # Generated task list

Writing Specs

Specs are simple markdown files describing what you want:

# Authentication

## Purpose
User authentication for the API.

## Requirements

### Must Have
- Email/password registration
- JWT-based sessions with refresh tokens
- Password hashing with bcrypt

### Should Have
- Password reset via email

### Must Not
- Store plain text passwords
- Allow unlimited login attempts

## Acceptance Criteria
- [ ] POST /auth/register creates user
- [ ] POST /auth/login returns JWT
- [ ] Invalid credentials return 401
- [ ] Tokens expire after 24 hours

Backpressure

The loop uses your test suite as a quality gate. Configure in .golem/AGENTS.md:

# Operational Guide

## Commands

### Testing
\`\`\`bash
npm test
\`\`\`

### Type Checking
\`\`\`bash
npm run typecheck
\`\`\`

### Linting
\`\`\`bash
npm run lint
\`\`\`

If tests fail, it fixes and retries. If they pass, it moves on. Your tests are the contract.

Philosophy

Fresh context beats accumulated context. Each iteration starts clean. No confusion from previous work bleeding in.

Tests are the spec. The loop trusts passing tests. Write good tests, get good code.

Simplification is not optional. AI-written code tends toward verbosity. The simplifier pass keeps it clean.

You steer via specs, not prompts. Change what you want by editing .golem/specs/*.md, not by micromanaging the AI.

Based On

• Ralph Wiggum Playbook by Clayton Farr — the autonomous loop methodology
• Code Simplifier from Anthropic — the simplification patterns

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated

License

MIT