by vdaubry
Coding agent orchestration for engineering teams — shipped as a spec plus a working reference implementation.
# Add to your Claude Code skills
git clone https://github.com/vdaubry/bottegabottega is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by vdaubry. Coding agent orchestration for engineering teams — shipped as a spec plus a working reference implementation. It has 76 GitHub stars.
bottega's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/vdaubry/bottega" and add it to your Claude Code skills directory (see the Installation section above).
bottega is primarily written in TypeScript. It is open-source under vdaubry on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh bottega against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
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
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 & 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;
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, …). 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.
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".
SPEC.md: "Read SPEC.md and build this."core/ for a minimal working tool; add whichever
extra/ features fit your team.You don't have to use the reference's stack (TypeScript / React / Express / SQLite). The spec describes behavior; build it however you like.
The reference app lives in reference/, and all commands below run
from there.
npm install -g pnpm@11Notes
- 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.
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
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:
pnpm onboarding runs in two steps and is idempotent — re-running it is safe and
skips completed steps:
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.
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:
extra/ features, better
explanations, or fixes to the core/ docs. Open a PR that touches SPEC.md,
core/, or extra/.extra/ spec here rather than as reference code.In short: grow the spec, fix the reference, fork for everything else.
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.
As we were working on this, a bunch of orchestration tools emerged. Variants of the same workflow we were converging on.
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 dev box. 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 box 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.