[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-85181":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":10,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},85181,"bottega","vdaubry\u002Fbottega","vdaubry","Coding agent orchestration for engineering teams — shipped as a spec plus a working reference implementation.","",null,"TypeScript",54,3,1,8,0,37.81,"MIT License",false,"main",[22,23,24,25,26,27,28,29,30],"agent-orchestration","ai-agents","claude-code","code-review","codex","coding-agent","llm","opencode","spec-driven-development","2026-06-15 10:05:20","# Bottega\n\nBottega 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.\n\nBottega ships as a specification plus a working reference implementation.\n\nIt 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).\n\nThe 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.\n\nIt 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.\n\nSee the demo:\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F2594371e-e4ae-4cc3-a8e8-05f4d98d74bd\n\nWant 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](https:\u002F\u002Fvdaubry.github.io\u002Fbottega-launch\u002F)\n\n## How it works\n\nBottega replicates a normal dev workflow as a loop of specialised agents, with a\nhuman at both ends.\n\n```mermaid\nflowchart TD\n    H1[\"Human — define the task\"]:::human\n    H1 --> PLAN[\"Planning agent\u003Cbr\u002F>fills the plan template\"]\n    PLAN --> APPROVE[\"Human — review & approve the plan\"]:::human\n    APPROVE --> IMPL[\"Implementation agent\"]\n    IMPL --> REVIEW[\"Adversarial code-review agent — reviews the code, runs the test scenarios, and verifies the goal\"]\n    REVIEW -->|\"incomplete, goal not met, or errors\"| IMPL\n    REVIEW -->|\"matches the plan, goal met\"| PR[\"Open the PR, keep CI green\"]\n    PR --> H2[\"Human — review the PR on GitHub\"]:::human\n    H2 -->|\"leaves comments\"| HOOK[\"GitHub webhook\"]\n    HOOK --> FEEDBACK[\"PR-feedback agent\u003Cbr\u002F>addresses comments, keeps CI green\"]\n    H2 -->|\"approves\"| MERGE[\"Merge\"]:::done\n\n    classDef human fill:#fff1d6,stroke:#e0962f,stroke-width:1px,color:#5c3d0a;\n    classDef done fill:#e7f6ec,stroke:#3f9d63,stroke-width:1px,color:#143524;\n```\n\n## A spec-first project\n\n**The specification is the product.** This project ships specs so you can build\nyour own version of the tool.\n\nA complete, working implementation is provided in [`reference\u002F`](reference). \n\nEvery team will probably want a different flavor: point\nyour preferred coding agent at this repository, explain your requirements, and\nbuild your own version.\n\n- **[`SPEC.md`](SPEC.md)** is the entry point: a short master index.\n- **[`core\u002F`](core)** specifies the universal orchestration engine — the\n  `planning → (implementation ⇄ review loop) → pull request`.\n- **[`extra\u002F`](extra)** specifies opinionated, optional features (the Kanban\n  board, different harness integrations, multi-user auth, …). Pick the ones you want;\n  skip the rest.\n- **[`reference\u002F`](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\n  canonical version.\n\nRead the spec for **what to build and why**; read `reference\u002F` for **one\nway it was solved**. Where the two ever disagree, the spec wins.\n\n### Why spec-first\n\nMost of the value we get out of this tool is easy to implement. The core is a tight orchestration\nloop and nothing more. \nDifferent teams will want different things: support for Gemini, adding a compliance agent in the loop, tasks sourced from Jira or Notion instead of a\nkanban board.\n**Fork it and build your own.**\n\nContributions are most welcome in the form of additional specs — see \"How to Contribute\".\n\n## Build your own\n\n1. Clone or fork this repo.\n2. Point a coding agent at [`SPEC.md`](SPEC.md): *\"Read SPEC.md and build this.\"*\n3. Implement all of [`core\u002F`](core) for a minimal working tool; add whichever\n   [`extra\u002F`](extra) features fit your team.\n4. Swap the opinionated parts for your own — replace the board with a Jira sync,\n   add a harness the reference doesn't ship, change the agent prompts.\n\nYou don't have to use the reference's stack (TypeScript \u002F React \u002F Express \u002F\nSQLite). The spec describes behavior; build it however you like.\n\n## Running the reference implementation\n\nThe reference app lives in [`reference\u002F`](reference), and all commands below run\nfrom there.\n\n### Stack\n\n- React 18 + Vite + Tailwind (frontend)\n- Node.js + Express + WebSocket (backend)\n- SQLite (better-sqlite3) for metadata and message storage\n\n### Prerequisites\n\n- **Node.js** 18+ (tested on Node 20 and 22)\n- **pnpm** 11 — install with `npm install -g pnpm@11`\n- **At least one agent runtime** — install whichever provider(s) you plan to\n  use:\n  - **Claude Code**\n  - **Codex**\n  - **OpenCode**\n\n> **Notes**\n> - Each provider's SDK is a thin wrapper around its CLI, which Bottega spawns\n>   as a subprocess — so the runtime must be installed on the host.\n> - You don't need to pre-authenticate Claude Code or Codex; Bottega's built-in\n>   OAuth flow handles login on first use.\n\n### Getting started\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvdaubry\u002Fbottega.git\ncd bottega\u002Freference        # the reference implementation lives here\nnpm install -g pnpm@11      # skip if pnpm 11 is already installed\npnpm install\ncp .env.example .env\n```\n\nOpen `.env` and set `JWT_SECRET` to a random secret:\n\n```bash\nopenssl rand -hex 64        # paste the output as JWT_SECRET in .env\n```\n\nThen run the interactive setup and start the server:\n\n```bash\npnpm onboarding     # creates your admin account and seeds a sample project\npnpm dev\n```\n\n- Frontend: http:\u002F\u002Flocalhost:5173\n- Backend:  http:\u002F\u002Flocalhost:3001\n\n### Connecting a provider\n\nBefore your first chat or agent run, Bottega shows a blocking **Connect a\nprovider** modal — you must connect at least one of Claude Code, Codex, or\nOpenCode. Credentials are stored per user, so each teammate connects their own Claude\u002FCodex\u002FOpenCode account. Each provider\nauthenticates differently:\n\n- **Claude Code \u002F Codex** — click **Authenticate**, open the generated URL in\n  your browser, authorize, then paste the returned code back into the app. No\n  API key needed; it uses your subscription via OAuth.\n- **OpenCode** — paste a Zen API key (from\n  [opencode.ai\u002Fzen](https:\u002F\u002Fopencode.ai\u002Fzen)) into the panel.\n\n### Onboarding wizard\n\n`pnpm onboarding` runs in two steps and is idempotent — re-running it is safe and\nskips completed steps:\n\n1. **Create an admin account.** Prompts for username and password, stored as a\n   bcrypt hash. The first user is automatically granted admin.\n2. **Seed a sample project.** Copies\n   [`examples\u002Flanding-page\u002F`](reference\u002Fexamples\u002Flanding-page) to\n   `~\u002Fbottega-examples\u002Flanding-page\u002F`, initializes a git repo there, and adds it\n   to your dashboard with one pending task. This gives you something concrete to\n   point your agent at on your first conversation.\n\nIf you'd rather start from your own repo, skip `pnpm onboarding`, run `pnpm dev`,\nregister an admin via the web UI, and add a project pointing at any git repo on\nyour machine.\n\n## How to Contribute\n\nBottega is built to be forked. **The most valuable thing you can do is build your\nown version**, and we'd love to hear about what you make — come say hello in\n[Discussions](https:\u002F\u002Fgithub.com\u002Fvdaubry\u002Fbottega\u002Fdiscussions).\n\nContributions back to *this* repository are welcome, with one guideline that\nkeeps the project small:\n\n- **Spec changes — encouraged.** New or improved spec files are the\n  contributions we most want: clarifications, new `extra\u002F` features, better\n  explanations, or fixes to the `core\u002F` docs. Open a PR that touches `SPEC.md`,\n  `core\u002F`, or `extra\u002F`.\n- **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. \n  We'll review changes that correct a defect or bring the reference back in line with the spec. \n  New features can be proposed as a new `extra\u002F` spec here rather than as reference code.\n\nIn short: **grow the spec, fix the reference, fork for everything else.**\n\n## Get in touch\n\nQuestions, ideas, feedback, or want to share what you built? **[GitHub\nDiscussions](https:\u002F\u002Fgithub.com\u002Fvdaubry\u002Fbottega\u002Fdiscussions)** is the place — you\ndon't need a bug or a technical problem to start a thread, just say hi.\n\nPlease keep **[Issues](https:\u002F\u002Fgithub.com\u002Fvdaubry\u002Fbottega\u002Fissues)** for bug\nreports and spec PRs (see [How to Contribute](#how-to-contribute)); everything\nelse belongs in Discussions.\n\n## Yet another orchestration tool\n\nAs we were working on this, a bunch of orchestration tools emerged. Variants of the same workflow we were converging on.\n\n- [Conductor](https:\u002F\u002Fwww.conductor.build\u002F), by Melty Labs (YC S24).\n- [GasTown](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fgastown), by Steve Yegge.\n- [gstack](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgstack), by Garry Tan.\n- [SpecKit](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fspec-kit), by GitHub.\n- [Symphony](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fsymphony), by OpenAI.\n\nThere is a lot of overlap with what we built. For us, this is a huge confirmation that we were on the right path.\n\nWhere Bottega differs:\n\n**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 dev box. \nIt supports multiple concurrent users out of the box. \nSide benefit 1: sandboxing autonomous agents on a remote server was easier for us than sandboxing them on each laptop.\nSide benefit 2: a lot of non-technical people use it internally.\nSide benefit 3: because it's always-on, reacting to GitHub is trivial: a PR review posted on GitHub fires a webhook at the box and kicks off a fresh agent run to address the comments. No laptop needs to be awake.\n\n**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.\n\n**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. \nSide benefit: easy to onboard the whole product team.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",2,"2026-06-15 02:30:14","CREATED_QUERY"]