berth

# Berth - plan, execute, verify

**One command. Fully built features. Ship your code.**

Berth is a Go CLI tool that orchestrates autonomous AI coding workflows using Claude Code. It combines GSD's structured planning, Ralph's fresh-context execution, Beads' git-backed task memory, and a Knowledge Graph MCP for deep code understanding -- no other workflow tool has all four.

```
   ┌───────────────────────────────────────┐
   │               berth                   │
   │  Smart AI Workflows for Claude Code   │
   ├───────────────────────────────────────┤
   │                                       │
   │  berth run "add OAuth with Google"    │
   │                                       │
   │  * Understand -- interview + graph    │
   │  * Plan -------- beads + deps         │
   │  * Execute ----- fresh process        │
   │    |-- bt-a1 [x]  configure OAuth     │
   │    |-- bt-a2 [x]  login button        │
   │    |-- bt-a3 [~]  OAuth callback      │
   │    '-- bt-a4 [ ]  integration tests   │
   │  * Report ------ 2/4 complete         │
   │                                       │
   └───────────────────────────────────────┘
```

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.23+-00ADD8?logo=go&logoColor=white)](https://go.dev/)
[![Status](https://img.shields.io/badge/Status-Early_Development-orange)]()
[![Claude Code](https://img.shields.io/badge/Built_for-Claude_Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)

<!-- TODO: Add demo GIF showing `berth run` with progress display -->
<!-- Record with asciinema or ttygif once the CLI is functional -->

---

## Key Features

- **Fresh context per task** -- every bead gets a clean 200k context window. No context rot. No degraded output.
- **Knowledge Graph MCP** -- AST-parsed code understanding via ts-morph. Claude knows who calls a function before changing its signature.
- **3+1 retry with structured recovery** -- 3 blind retries, 1 diagnostic retry, then Pause with Choices: hint, rescue, skip, or abort. Never silently fails.
- **Beads task memory** -- dependency graphs, close reasons, mid-run task injection. State is queryable, not stuffed into context.
- **Accumulated learnings** -- every session teaches the next one. Your codebase's quirks are remembered across runs.
- **One command** -- `berth run "your feature"`, come back to atomic commits and a PR.

---

## Table of Contents

- [Quick Start](#quick-start)
- [The Problem](#the-problem)
- [How Berth Solves It](#how-berth-solves-it)
- [How It Works](#how-it-works)
- [Architecture](#architecture)
- [Compared To](#compared-to)
- [Knowledge Graph MCP](#knowledge-graph-mcp)
- [Git Workflow](#git-workflow)
- [Configuration](#configuration)
- [State Persistence](#state-persistence)
- [Design Philosophy](#design-philosophy)
- [Inspired By](#inspired-by)
- [Contributing](#contributing)
- [License](#license)

---

## Quick Start

### Prerequisites

- Go 1.23+ (for building from source) or pre-built binary
- [Beads](https://github.com/steveyegge/beads) (`bd`) CLI installed
- Claude Code CLI installed and authenticated
- Node.js 20+ (for Knowledge Graph MCP)
- Git 2.25+

### Install

```bash
# Install from npm (downloads platform-specific Go binary)
npm install -g @berthdev/berth

# Or build from source
git clone https://github.com/user/berth.git
cd berth
make build
```

### Usage

```bash
# Initialize in your project
berth init

# Run a feature
berth run "add user authentication with JWT"

# That's it. Come back to commits and a PR.
```

### Other Commands

```bash
berth status                    # Show current run progress
berth add "fix the logout bug"  # Inject a task mid-run
berth report                    # Show last run results
berth pr                        # Create PR from current run branch
berth resume                    # Resume an interrupted run
```

---

## The Problem

Claude Code is extraordinary for small tasks. But ask it to build a full feature across a large codebase and things fall apart:

- **Context rot** -- output quality degrades as the context window fills. A fresh Claude at 10% is a different animal than a tired Claude at 80%.
- **Hallucination at scale** -- Claude invents imports, references wrong modules, generates plausible code that does not compile.
- **Incomplete features** -- writes the endpoint but skips the validation, implements the happy path and leaves TODOs for edge cases.
- **No memory** -- every session starts from zero. You re-explain the same codebase quirks every time.
- **Finnicky on large projects** -- cannot hold the full architecture in context, makes changes that conflict with existing patterns.

These are symptoms of trying to do too much in a single context window without external structure.

---

## How Berth Solves It

Berth wraps Claude Code in four phases. You see one command in, commits out. Internally:

### 1. Understand
Berth interviews you about the feature via a structured loop: Claude generates questions as JSON, Berth presents them in the terminal, you answer. It queries the Knowledge Graph to understand what already exists. Decisions are locked in `requirements.md`.

Three input modes:
- **Description** (default): `berth run "add OAuth"` -- Berth interviews you
- **PRD file**: `berth run --prd tasks/feature.md` -- Claude reads the PRD, asks only clarifying questions
- **Skip**: `berth run "add OAuth" --skip-understand` -- no interview, straight to planning

### 2. Plan
The feature is broken into beads (tasks) managed by [Beads](https://github.com/steveyegge/beads). Each bead has a description, files to touch, code context from the Knowledge Graph, verification commands, and dependencies. The plan is presented for your approval before execution.

### 3. Execute
For each bead, Berth spawns a fresh Claude process with only what it needs: the bead definition, pre-embedded Knowledge Graph data, and accumulated learnings. It implements, verifies (typecheck, lint, test, build), and commits on success. Failures trigger the 3+1 retry strategy, then Pause with Choices if still stuck.

### 4. Report
Summary of what was built, bead close reasons, commits, stuck beads with failure details, and a PR if configured. Learnings saved for next session.

---

## How It Works

### The Understand Phase

Berth does not start coding immediately. It runs a structured interview loop:

1. **What does the codebase look like?** It queries the Knowledge Graph for file structure, exports, imports, and type relationships relevant to your request.

2. **What do you want?** Claude generates questions as structured JSON. Berth presents them in the terminal with numbered options. You pick an option or type a custom answer. If you are unsure, pick "Help me decide" and Berth spawns a focused explanation call.

3. **Is anything ambiguous?** For complex or vague requests, Claude first decomposes the request into sub-features, asks you to confirm scope, then asks per-feature questions. For simple requests, it asks 3-5 targeted questions and moves on.

The interview ends automatically when Claude signals it has enough information. Results are written to `.berth/runs/<run>/requirements.md`.

### The Plan Phase

The feature is decomposed into beads -- each one a focused task with:
- **Description**: What to implement, in concrete terms
- **Files**: Which files will be created or modified
- **Context**: What already exists in those files (from the Knowledge Graph)
- **Verification**: Commands that prove the task is done (beyond the default pipeline)
- **Dependencies**: Which beads must complete first

The plan is presented for your approval. You can approve, reject with feedback (triggers re-planning), or view full details before deciding. Once approved, beads are created via the `bd` CLI and execution begins.

### The Execute Phase

This is the core engine. For each bead in dependency order:

1. **Spawn fresh Claude process** (no accumulated conv

[truncated…]