hamgoose

README.md

<div align="center">

<table align="center"><tr><td>

<pre>
 â–ˆâ–ˆâ–ˆâ–ˆâ–ˆ
â–‘â–‘â–ˆâ–ˆâ–ˆ
 â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ    â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ    â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ  â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ
 â–‘â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ  â–‘â–‘â–‘â–‘â–‘â–ˆâ–ˆâ–ˆ â–‘â–‘â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ  â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–‘â–‘   â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ
 â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ  â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ
 â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ  â–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆ  â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ â–‘â–‘â–‘â–‘â–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆâ–‘â–‘â–‘
 â–ˆâ–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–‘â–ˆâ–ˆâ–ˆ â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ â–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ  â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ â–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ
â–‘â–‘â–‘â–‘ â–‘â–‘â–‘â–‘â–‘  â–‘â–‘â–‘â–‘â–‘â–‘â–‘â–‘ â–‘â–‘â–‘â–‘â–‘ â–‘â–‘â–‘ â–‘â–‘â–‘â–‘â–‘  â–‘â–‘â–‘â–‘â–‘â–ˆâ–ˆâ–ˆ â–‘â–‘â–‘â–‘â–‘â–‘   â–‘â–‘â–‘â–‘â–‘â–‘  â–‘â–‘â–‘â–‘â–‘â–‘   â–‘â–‘â–‘â–‘â–‘â–‘
                                      â–ˆâ–ˆâ–ˆ â–‘â–ˆâ–ˆâ–ˆ
                                     â–‘â–‘â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ
                                      â–‘â–‘â–‘â–‘â–‘â–‘
</pre>

</td></tr></table>

**ðŸ¦† Factory-Droid-style Mission orchestration for [Goose](https://github.com/block/goose)**

[![PyPI version](https://img.shields.io/pypi/v/hamgoose?color=neon)](https://pypi.org/project/hamgoose/)
[![Python versions](https://img.shields.io/pypi/pyversions/hamgoose?color=blue)](https://img.shields.io/pypi/pyversions/hamgoose)
[![PyPI downloads](https://img.shields.io/pypi/dm/hamgoose?color=green)](https://img.shields.io/pypi/dm/hamgoose)
[![npm version](https://img.shields.io/npm/v/@cooked-ham/hamgoose?color=cb3837)](https://www.npmjs.com/package/@cooked-ham/hamgoose)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Goose extension](https://img.shields.io/badge/Goose-extension-841697?logo=goose&logoColor=white)](https://goose-docs.ai)
[![Code style: deterministic core](https://img.shields.io/badge/core-deterministic-orange)](#why-its-different)

[![GitHub stars](https://img.shields.io/github/stars/cooked-ham/hamgoose?style=social)](https://github.com/cooked-ham/hamgoose/stargazers)

**Type a goal â†’ get a structured plan â†’ approve â†’ watch isolated workers build it, get validated, get corrected â€” until it's done and proven.**

</div>

```
USER GOAL â†’ ANALYSIS â†’ STRUCTURED PLAN â†’ FEATURES + DEPS + MILESTONES â†’ APPROVAL
  â†’ DEPENDENCY-AWARE EXECUTION (isolated workers) â†’ REAL CODE
  â†’ SCRUTINY + USER-FACING VALIDATION â†’ AUTOMATIC CORRECTION
  â†’ FINAL VALIDATION â†’ MISSION COMPLETED âœ…
```

hamgoose is a genuine Goose **extension** â€” a standalone stdio MCP server on the
official `mcp`/`FastMCP` model, not a recipe, todo wrapper, or delegation
prompt. **Code enforces the orchestration mechanics; models do the semantic
reasoning.**

---

## ðŸ“– Contents

- [âœ¨ Features](#-features)
- [ðŸš€ Quickstart](#-quickstart)
- [ðŸŽ¯ The walkthrough](#-the-walkthrough)
- [ðŸ—ï¸ How it works](#ï¸-how-it-works)
- [ðŸ“¦ Install](#-install)
- [ðŸ› ï¸ The lifecycle (tools)](#ï¸-the-lifecycle-tools)
- [ðŸ—„ï¸ Where state lives](#ï¸-where-state-lives)
- [ðŸ§ª Development](#-development)
- [ðŸ“š Docs](#-docs)
- [ðŸ“œ License](#-license)

---

## âœ¨ Features

| | |
|---|---|
| ðŸš¦ **Approval gate** | Nothing is implemented until *you* approve the plan |
| ðŸï¸ **Isolated leaf workers** | Each feature runs in its own `goose` subprocess inside a Git worktree â€” no nested delegation, crash containment, real diffs |
| ðŸ•¸ï¸ **Dependency-aware scheduling** | A DAG of features with path-overlap conflict detection and a hard concurrency cap (your provider's limits, enforced in code) |
| ðŸ” **Two validators** | *Scrutiny* distrusts the worker's claims and inspects diff + tests; *user-testing* exercises the app from the user's perspective |
| ðŸ” **Automatic correction** | Failed validation becomes corrective features; the bounded loop repeats until the milestone passes |
| ðŸ§¯ **Crash recovery** | Atomic JSON state + append-only event log â€” kill Goose mid-mission, reopen, it reconciles and continues |
| ðŸ“¡ **Live progress** | Long calls stream MCP progress notifications, and the guided flow runs in short visible bursts â€” you always see movement, never a silent wait |
| ðŸ§ **Steering & replanning** | Change course mid-mission without losing completed work |
| ðŸ” **Secrets redacted** | Every persisted artifact scrubbed of keys, tokens, credentials |
| ðŸª¶ **Per-repo state** | Lives in `<repo>/.goose/hamgoose/` â€” nothing global, trivially git-ignored |

## ðŸš€ Quickstart

**Node** â€” via npm:

```bash
npm i -g @cooked-ham/hamgoose
hamgoose register
```

**Python** â€” via pip:

```bash
pip install git+https://github.com/cooked-ham/hamgoose.git   # Python 3.11+
hamgoose register
```

**Either world, one shot (no install):** `npx @cooked-ham/hamgoose register`

> [!TIP]
> That's the whole install â€” two commands, no repo wiring, no config surgery.
> Pick **one** channel (npm *or* pip); both provide the same `hamgoose` command.
> Uninstall: `hamgoose unregister` + `npm uninstall -g @cooked-ham/hamgoose`
> (or `pip uninstall -y hamgoose`).

## ðŸŽ¯ The walkthrough

Then, in **any** repository you're working in:

```text
$ goose
You:   /prompt start_mission
goose: What's the goal?
You:   Migrate the auth module from session cookies to JWT.
goose: Any rules or constraints? (concurrency, provider/model, git, validation)
You:   My provider only allows 3 concurrent agents at a time.
goose: Plan: 2 milestones, 6 features, workers capped at 3 concurrent. Approve?
You:   Approve.
goose: MS01 1/3 â€¦ passed scrutiny â€¦ MS02 2/3 â€¦
       âœ… Mission COMPLETED â€” changes on branch mission/base with per-feature commits.
```

Rules are recorded **verbatim** on the mission (visible in every status and
plan view), translated into execution config ("max 3 concurrent" â†’
`max_concurrent_workers: 3`), and handed to **every worker** as context.
Mid-mission you can just say *"pause"*, *"don't touch config files"*, or
*"replan around X"* â€” steering and replanning never lose completed work.

> [!NOTE]
> No slash command? Just say **"start a hamgoose mission"** in plain English.
> `/prompt start_mission` runs the guided setup; plain English does the same thing.

## ðŸ—ï¸ How it works

```mermaid
flowchart LR
    U["ðŸ‘¤ You<br/>goal + rules"] --> G["Goose session"]
    G <-->|MCP stdio| H["ðŸ¦† hamgoose<br/>orchestrator<br/>(deterministic code)"]
    H -->|isolated goose run| W1["Worker F001<br/>ðŸŒ³ worktree"]
    H -->|isolated goose run| W2["Worker F002<br/>ðŸŒ³ worktree"]
    H --> V["ðŸ” Validators<br/>scrutiny + user-test"]
    W1 -->|merge + commit| R[("repo<br/>mission/base")]
    W2 -->|merge + commit| R
```

```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> ANALYZING
    ANALYZING --> PLANNING
    PLANNING --> AWAITING_APPROVAL
    AWAITING_APPROVAL --> RUNNING : approve
    RUNNING --> PAUSED
    RUNNING --> BLOCKED
    PAUSED --> RUNNING : resume
    BLOCKED --> RUNNING : resolve + resume
    RUNNING --> VALIDATING
    VALIDATING --> RUNNING : corrective work
    VALIDATING --> COMPLETED : all pass âœ…
    CREATED --> CANCELLED
    AWAITING_APPROVAL --> CANCELLED
    RUNNING --> FAILED
    COMPLETED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]
```

**Why it's different from "just let the agent do it":** the orchestrator is
*deterministic code* â€” state machines, DAG scheduling, retries, Git
bookkeeping, persistence are enforced, not hoped for. The LLM only does what
LLMs are good at: understanding intent and writing code. A confused model
can't corrupt the mission state, skip the approval gate, or double-dispatch
a feature. See [ARCHITECTURE_REPORT.md](ARCHITECTURE_REPORT.md) for the full
design analysis.

## ðŸ“¦ Install

Requires `goose` (â‰¥ 1.40) on your PATH and `git` (for Git missions).

| Option | For | Command |
|---|---|---|
| **1. From GitHub** â | Everyone | `pip install git+https://github.com/cooked-ham/hamgoose.git` then `hamgoose register` |
| **2. Goose's own menu** | No extra commands | `goose configure` â†’ **Extensions â†’ Add Extension** â†’ STDIO / `hamgoose` / `hamgoose` |
| **3. From a clone** | Contributors | `git clone â€¦ && cd hamgoose && uv venv .venv && uv pip install -p .venv -e .` then `hamgoose register` |
| **4. Per-run** | One-off experiments | `goose run -t "..." --with-extension "hamgoose:python -m hamgoose"` |
| **5. npm (Node world)** | Node-first machines | `npm i -g @cooked-ham/hamgoose` then `hamgoose register` â€” or one-shot: `npx @cooked-ham/hamgoose register` |

> [!IMPORTANT]
> Pin a release once tags exist:
> `pip install "git+https://github.com/cooked-ham/hamgoose.git@v0.1.2"`.

<details>
<summary>ðŸ”§ What registration writes (manual option)</summary>

```yaml
# config.yaml â€” path printed by `goose info`
extensions:
  hamgoose:
    enabled: true
    type: stdio
    name: hamgoose
    description: Mission orchestration for Goose
    cmd: hamgoose
    args: []
```

</details>

## ðŸ› ï¸ The lifecycle (tools)

| Operation | Tool |
|---|---|
| Create + analyze repo (guided setup) | `mission_create(goal, rules?, config?)` |
| Generate the plan (approval gate) | `mission_plan(mission_id)` |
| Approve & start | `mission_approve(mission_id)` |
| Execute the control loop (resumable) | `mission_run(mission_id, max_steps?)` |
| Pause / resume | `mission_pause` / `mission_resume` |
| Steer (priority / guidance) | `mission_steer(instruction, feature_id?, priority?)` |
| Replan (new constraint) | `mission_replan(instruction)` |
| Retry a feature / validate now | `mission_retry_feature` / `mission_validate(kind)` |
| Cancel | `mission_cancel` |
| Read status / plan / events / list | `mission_status` / `mission_plan_view` / `mission_events` / `mission_list` |

**Resources** (read): `mission://{id}/status|plan|events|features|milestones|validation`
**Prompts** (list with `/prompts`, run with `/prompt <name>`): `start_mission` (guided setup) Â· `plan_mission` Â· `resume_mission` Â· `validate_milestone`

## ðŸ—„ï¸ Where state lives

```
<repo>/.goose/hamgoose/<mission-id>/
â”œâ”€â”€ mission.json     # canonical atomic state
â”œâ”€â”€ mission.yaml     # human-readable mirror
â”œâ”€â”€ plan.md          # plan mirror
â”œâ”€â”€ events.jsonl     # append-only event log
â”œâ”€â”€ workers/         # redacted worker transcripts
â”œâ”€â”€ validation/      # validation reports
â”œâ”€â”€ worktrees_base/  # mission/base worktree (merged result)
â””â”€â”€ worktrees/<F>    # per-feature worktrees
```

Your current branch is **never modified** â€” `mission/base` accumulates the
merged, validated result for you to merge. Add `/.goose/hamgoose/` to your
repo's `.gitignore`.

## ðŸ§ª Development

```bash
git clone https://github.com/cooked-ham/hamgoose.git && cd hamgoose
uv venv .venv
uv pip install -p .venv -e ".[dev]"
.venv/bin/python -m pytest -m "not realgoose"   # fast, deterministic (no LLM)
.venv/bin/python -m pytest -m "realgoose"       # real Goose + LLM (slower)
```

## ðŸ“š Docs

- [ARCHITECTURE_REPORT.md](ARCHITECTURE_REPORT.md) â€” design decisions & compliance analysis
- [ARCHITECTURE.md](ARCHITECTURE.md) â€” component architecture
- [MISSION-LIFECYCLE.md](MISSION-LIFECYCLE.md) â€” state machines & control loop
- [CONFIGURATION.md](CONFIGURATION.md) â€” config reference, registration, known limitations
- [TESTING.md](TESTING.md) â€” test strategy
- [WINDOWS.md](WINDOWS.md) â€” Windows gotchas & hardening notes (cmd, cp1252, CRLF, tree kills, pipe hang, pytest temp)
- [FIX_PLAN.md](FIX_PLAN.md) â€” the v0.1.8 hardening fix plan & implementation record (HG-01â€¦HG-17)
- [remainingwork_hamgoose.md](remainingwork_hamgoose.md) â€” the original failure evidence from 5 missions
- [PUBLISHING.md](PUBLISHING.md) â€” PyPI release runbook

## ðŸ“œ License

MIT â€” see [LICENSE](LICENSE).

---

<div align="center">

**Built on [Goose](https://github.com/block/goose) Â· [MCP](https://modelcontextprotocol.io) Â· ðŸ¦†**

</div>

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-09-08 19:10 across 19 tools

Disambiguation4/5

The tools map cleanly to lifecycle stages (create/plan/approve/run/pause/resume/steer/replan/cancel) and read-only views (status/events/readiness/plan_view). A few control-loop actions like mission_run, mission_resume, and mission_steer could be confused, but their descriptions clarify the differences.

Naming Consistency4/5

All tools share the mission_ prefix and use lower_snake_case, but the pattern mixes bare verbs (mission_run, mission_pause), noun-like resources (mission_status, mission_events), and compound verb_noun forms (mission_retry_feature, mission_apply_suggestions). This is readable and predictable, though not as uniform as a strict verb_noun convention.

Tool Count3/5

At 19 tools, the surface is on the heavy side for an MCP server. Most tools are individually justified by mission lifecycle needs, but a few niche helpers like mission_apply_suggestions and mission_gc, plus several status-like queries, could plausibly be consolidated.

Completeness5/5

The toolset covers the full mission lifecycle: create, plan, approve, run, pause, resume, steer, replan, cancel, plus status/events/readiness/plan_view and manual retry/completion/validation paths. There are no obvious dead ends for the stated purpose, and external-completion and cleanup workflows are included.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers