Bottega

Bottega is a multi-agent orchestration tool for engineering teams who want an "AI sandwich" approach: Human at the start & the end, AI in the middle.

Bottega ships as a specification plus a working reference implementation.

It runs as a web UI, is team-first (multi-user), and remote-first (you can run it locally, but it's designed to run on a server).

The tool aims to replicate a typical dev workflow: plan, implement, run the QA scenarios that define the goal, loop until that goal is met (the Ralph Wiggum loop), respond to PR comments on GitHub, etc.

It supports Claude Code, Codex, and OpenCode so you can mix and match models on the same task. For example, use Opus for planning, Sonnet for implementation, Codex for code review, and an open-source model to manage the PR (monitor the CI, fix conflicts), etc.

See the demo:

https://github.com/user-attachments/assets/2594371e-e4ae-4cc3-a8e8-05f4d98d74bd

Want to see how we use it in practice? We share our experience after shipping our 1000th user story with this tool on a production codebase (a large Rails monolith) launch post

How it works

Bottega replicates a normal dev workflow as a loop of specialised agents, with a
human at both ends.

flowchart TD
    H1["Human — define the task"]:::human
    H1 --> PLAN["Planning agent<br/>fills the plan template"]
    PLAN --> APPROVE["Human — review &amp; approve the plan"]:::human
    APPROVE --> IMPL["Implementation agent"]
    IMPL --> REVIEW["Adversarial code-review agent — reviews the code, runs the test scenarios, and verifies the goal"]
    REVIEW -->|"incomplete, goal not met, or errors"| IMPL
    REVIEW -->|"matches the plan, goal met"| PR["Open the PR, keep CI green"]
    PR --> H2["Human — review the PR on GitHub"]:::human
    H2 -->|"leaves comments"| HOOK["GitHub webhook"]
    HOOK --> FEEDBACK["PR-feedback agent<br/>addresses comments, keeps CI green"]
    H2 -->|"approves"| MERGE["Merge"]:::done

    classDef human fill:#fff1d6,stroke:#e0962f,stroke-width:1px,color:#5c3d0a;
    classDef done fill:#e7f6ec,stroke:#3f9d63,stroke-width:1px,color:#143524;

Explore: review a plan as an interactive page

A plan is a long markdown file, and it is the one thing a human has to read
carefully before the agents start. Explore makes that review easier: an
agent reads the plan and the code it cites, then writes a self-contained,
interactive HTML page for it — phase cards with click-to-detail, an animated
flowchart of the request path, or a clickable architecture map of the modules
involved.

The page is shown next to a read-only view of the repository. Click any file
reference in it and the source opens beside it, at the right line. Keep
chatting with the agent to refine the page ("redo this as an architecture
diagram"), or ask it a question and watch it open and highlight the code that
answers it.

There is no diagram format behind this: the agent authors a complete HTML
document, and Bottega displays it in a sandboxed iframe. See
extra/explore.md.

Epics: features bigger than one task

Some features don't fit in one task. An epic is a layer on top of tasks that
takes a functional specification all the way to one final pull request:

functional spec ─▶ architecture ─▶ technical spec ─▶ stories ─▶ spec review
                                                                     │
        ┌────────────────────────────────────────────────────────────┘
        ▼
orchestrator: each ticket, in order ─▶ plan ─▶ implement ⇄ review ─▶ PR
                                       ─▶ PR reviewer: review, fix, merge
        │
        ▼
final PR ─▶ QA on the whole feature ─▶ a human merges

• Framing is a conversation. Four stages, each one conversation with an
  agent that writes documents you approve: an architecture document, a
  technical specification, the list of tickets, and a consistency review of all
  of it. Stages are forward-only, and the approved documents are the only thing
  handed from one stage to the next.
• Implementation is unattended. An orchestrator agent drives each ticket
  through the normal task pipeline exactly as a human would — it starts
  planning, answers the planner's questions from the specification, reviews and
  approves the plan. A separate PR-reviewer agent then checks the pull request
  against the specification, fixes what it finds, and merges it into the epic's
  feature branch. You are called back only on escalation.
• Tasks stay agnostic. A ticket is an ordinary task. The task layer imports
  nothing from the epic layer: epics act through the same API the UI uses and
  listen to task events. Ticket-level agents cannot tell whether a human or the
  orchestrator is on the other side.

See extra/epics.md.

A spec-first project

The specification is the product. This project ships specs so you can build
your own version of the tool.

A complete, working implementation is provided in reference/.

Every team will probably want a different flavor: point
your preferred coding agent at this repository, explain your requirements, and
build your own version.

• SPEC.md is the entry point: a short master index.
• core/ specifies the universal orchestration engine — the
  planning → (implementation ⇄ review loop) → pull request.
• extra/ specifies opinionated, optional features (the Kanban
  board, different harness integrations, multi-user auth, Explore, Epics, …).
  Pick the ones you want; skip the rest.
• reference/ is one complete, working implementation. It's the implementation we use daily internally, with our own set of preferences. It's a citation for the spec, not the
  canonical version.

Read the spec for what to build and why; read reference/ for one
way it was solved. Where the two ever disagree, the spec wins.

Why spec-first

Most of the value we get out of this tool is easy to implement. The core is a tight orchestration
loop and nothing more.
Different teams will want different things: support for Gemini, adding a compliance agent in the loop, tasks sourced from Jira or Notion instead of a
kanban board.
Fork it and build your own.

Contributions are most welcome in the form of additional specs — see "How to Contribute".

Build your own

1. Clone or fork this repo.
2. Point a coding agent at SPEC.md: "Read SPEC.md and build this."
3. Implement all of core/ for a minimal working tool; add whichever
   extra/ features fit your team.
4. Swap the opinionated parts for your own — replace the board with a Jira sync,
   add a harness the reference doesn't ship, change the agent prompts.

You don't have to use the reference's stack (TypeScript / React / Express /
SQLite). The spec describes behavior; build it however you like.

Running the reference implementation

The reference app lives in reference/, and all commands below run
from there.

Stack

• React 18 + Vite + Tailwind (frontend)
• Node.js + Express + WebSocket (backend)
• SQLite (better-sqlite3) for metadata and message storage

Prerequisites

• Node.js 18+ (tested on Node 20 and 22)
• pnpm 11 — install with npm install -g pnpm@11
• At least one agent runtime — install whichever provider(s) you plan to
  use:
  • Claude Code
  • Codex
  • OpenCode

Notes

• Each provider's SDK is a thin wrapper around its CLI, which Bottega spawns
  as a subprocess — so the runtime must be installed on the host.
• You don't need to pre-authenticate Claude Code or Codex; Bottega's built-in
  OAuth flow handles login on first use.

Getting started

git clone https://github.com/vdaubry/bottega.git
cd bottega/reference        # the reference implementation lives here
npm install -g pnpm@11      # skip if pnpm 11 is already installed
pnpm install
cp .env.example .env

Open .env and set JWT_SECRET to a random secret:

openssl rand -hex 64        # paste the output as JWT_SECRET in .env

Then run the interactive setup and start the server:

pnpm onboarding     # creates your admin account and seeds a sample project
pnpm dev

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

Connecting a provider

Before your first chat or agent run, Bottega shows a blocking Connect a
provider modal — you must connect at least one of Claude Code, Codex, or
OpenCode. Credentials are stored per user, so each teammate connects their own Claude/Codex/OpenCode account. Each provider
authenticates differently:

• Claude Code / Codex — click Authenticate, open the generated URL in
  your browser, authorize, then paste the returned code back into the app. No
  API key needed; it uses your subscription via OAuth.
• OpenCode — paste a Zen API key (from
  opencode.ai/zen) into the panel.

Onboarding wizard

pnpm onboarding runs in two steps and is idempotent — re-running it is safe and
skips completed steps:

1. Create an admin account. Prompts for username and password, stored as a
   bcrypt hash. The first user is automatically granted admin.
2. Seed a sample project. Copies
   examples/landing-page/ to
   ~/bottega-examples/landing-page/, initializes a git repo there, and adds it
   to your dashboard with one pending task. This gives you something concrete to
   point your agent at on your first conversation.

If you'd rather start from your own repo, skip pnpm onboarding, run pnpm dev,
register an admin via the web UI, and add a project pointing at any git repo on
your machine.

How to Contribute

Bottega is built to be forked. The most valuable thing you can do is build your
own version, and we'd love to hear about what you make — come say hello in
Discussions.

Contributions back to this repository are welcome, with one guideline that
keeps the project small:

• Spec changes — encouraged. New or improved spec files are the
  contributions we most want: clarifications, new extra/ features, better
  explanations, or fixes to the core/ docs. Open a PR that touches SPEC.md,
  core/, or extra/.
• Reference implementation — bug fixes only. The reference is the tool we chose to use; you're welcome to use it if you share our preferences. It's not intended to accumulate features and become a bloated, one-size-fits-all tool.
  We'll review changes that correct a defect or bring the reference back in line with the spec.
  New features can be proposed as a new extra/ spec here rather than as reference code.

In short: grow the spec, fix the reference, fork for everything else.

CI on your PR

The Unit Tests workflow is path-filtered. A PR whose every changed file is
prose — SPEC.md, README.md, core/, extra/, reference/docs/ — runs no
CI at all, so seeing zero checks on a spec-only PR is expected, not a failure.
Touch a single source file and the full suite runs as usual.

One exception worth knowing: markdown under
reference/server/constants/prompts/ is not documentation. Those files are
agent templates loaded at runtime, and their text is asserted by the test
suite, so editing them does trigger CI.

Get in touch

Questions, ideas, feedback, or want to share what you built? GitHub
Discussions is the place — you
don't need a bug or a technical problem to start a thread, just say hi.

Please keep Issues for bug
reports and spec PRs (see How to Contribute); everything
else belongs in Discussions.

Yet another orchestration tool

As we were working on this, a bunch of orchestration tools emerged. Variants of the same workflow we were converging on.

• Conductor, by Melty Labs (YC S24).
• GasTown, by Steve Yegge.
• gstack, by Garry Tan.
• SpecKit, by GitHub.
• Symphony, by OpenAI.

There is a lot of overlap with what we built. For us, this is a huge confirmation that we were on the right path.

Where Bottega differs:

Remote-first and multi-player. While you can run it on your laptop, Bottega is remote-first by design — we run it on a shared server.
It supports multiple concurrent users out of the box.
Side benefit 1: sandboxing autonomous agents on a remote server was easier for us than sandboxing them on each laptop.
Side benefit 2: a lot of non-technical people use it internally.
Side benefit 3: because it's always-on, reacting to GitHub is trivial: a PR review posted on GitHub fires a webhook at the server and kicks off a fresh agent run to address the comments. No laptop needs to be awake.

Multi-harness. Bottega drives Claude Code, Codex, and OpenCode behind one interface, so you can assign a different model to each role on the same task.

Minimalist UX. The core ideas are super simple: we are just recreating the typical web developer workflow. And we wanted the tool to reflect that simplicity.
Side benefit: easy to onboard the whole product team.

License

MIT — see LICENSE.