> The `brunch` npm package name was previously used by a different project, a web app build tool: https://github.com/brunch/brunch
> From version `5.0.0` onwards, it is used by a new, entirely new project, an AI-guided spec elicitation tool: https://github.com/hashintel/brunch
> The two projects are completely unrelated. `4.0.2` is the latest and last version of the web app build tool.

> The new project is under development and is immature. We do not yet recommend using it.
> It starts at version `5.0.0` to avoid confusion with the old project, rather than because of its maturity.

# Brunch

Brunch is an AI-guided spec elicitation tool that turns a rough project idea into a structured specification through a multi-phase interview. It runs locally, keeps workspace state in a project-scoped SQLite database, and opens a browser UI for working through grounding, design, requirements, and acceptance criteria.

## Run Brunch

Brunch requires Node 22+ and an Anthropic API key.

Create a `.env` file in the project directory where you want to use Brunch:

```bash
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
```

Then launch it in that directory:

```bash
npx brunch
```

Brunch will create or reuse the local `.brunch/` workspace for that project, start the web UI, and open it in your browser.

If you prefer a global install:

```bash
npm install -g brunch
brunch
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | Yes | Anthropic API key |
| `ANTHROPIC_MODEL` | No | Interviewer model override |
| `OBSERVER_MODEL` | No | Observer model override |
| `BRUNCH_PORT` | No | Port for the local web server |

## Help

```bash
npx brunch --help
```

## For Contributors

Development setup, architecture notes, fixture workflows, release steps, and internal planning docs live in [CONTRIBUTING.md](https://github.com/hashintel/brunch/blob/main/CONTRIBUTING.md).