Skip to content
Boboddy
boboddy.dev

Quickstart

By the end you’ll have a pipeline built around one of your own work items, running on your machine. It takes about ten minutes in one terminal session; the browser only comes in for sign-in, setup the terminal can’t finish, and the pipeline graph.

Before you start

Section titled “Before you start”
  • A git repository with an origin remote.
  • Node.js or Bun.
  • Claude Code, Codex, or GitHub Copilot — or an API key from any AI provider.

Details are in Installation. Steps that work inside your code run in a container, so the run may also need Docker — see Runtime.

  1. Install the CLI

    Terminal window
    npm i -g @boboddy/cli

    Prefer Bun? See Installation.

  2. Link your repo

    From anywhere inside your repository:

    Terminal window
    boboddy init
    terminal
    ◇  Repository: ~/my-repo [0s]
    ●  Remote: git@github.com:you/my-repo.git
    ●  Not signed in to https://app.boboddy.dev. Starting sign-in…
    ◇  Signed in as you@example.com [14s]
    ◇  Requirements verified [1s]
    ◇  No project found for this repository yet [0s]
    ◇  Create Boboddy project “my-repo” from GitHub you/my-repo?
    │  Yes
    ◇  Created project “my-repo” [4s]
    ◇  No devcontainer yet [0s]
    ▲  Boboddy runs every step inside your project's devcontainer, and this repository does not have one yet. Nothing to do: `boboddy pipelines design` will write a `.devcontainer/devcontainer.json` during the session, and your first pipeline run is what verifies it builds.
    ◇  No AI provider connected yet [0s]
    ●  The pipeline designer runs on OpenCode and connects it to a model the first time it starts — nothing to do now.
    ◆  Design your first pipeline now?
    │  ● Yes / ○ No

    init signs you in, then finds or creates the project for this repo. The one decision is Create Boboddy project … from GitHub? — say yes, and your issues keep syncing in as work items. If it isn’t asked, init opens a pre-filled page in your browser; finish creating the project there (see Create a project).

    The notices need nothing from you. Answer yes to Design your first pipeline now?.

  3. Pick a work item

    terminal
    ┌   Boboddy pipeline designer
    ●  Logs → ~/.boboddy/logs/worker-2026-10-07T15-04-12-123Z.log
    ◆  Signed in as you@example.com
    ◇  3 work item(s) [1s]
    ◆  What should this pipeline handle? (Ctrl+C to cancel)
    │  ● Checkout crashes when a coupon is applied twice (github)
    │  ○ Add CSV export to the orders page (github)
    │  ○ Flaky test: cart total rounding (github)
    │  ○ Search for a different item…
    │  ○ + Paste a link/id, or describe a new one…
    └
    ◆  Designing for “Checkout crashes when a coupon is applied twice”

    The designer builds every pipeline around one real work item — its interview asks how this item should be handled — so pick something typical. Not listed? Search, paste a ticket link, or describe one in a sentence.

  4. Connect your AI tool

    The designer runs on a Boboddy-managed OpenCode runtime that needs its own connection to a model. First it lists the MCP servers and skills your repository defines, for the designer to offer your steps. The first time, it then names the AI tools it finds and hands you OpenCode’s provider menu.

    terminal
    ◆  Scaffolded the pipeline builder directory
    ●  Installing pipeline builder dependencies…
    ◆  Dependencies installed
    ◇  Listed the tools of 1 of 1 MCP server(s) [4s]
    ◆  Found 1 MCP server(s) and 2 skill(s) in this repository
    ◇  AI runtime ready [41s]
    ●  Connect an AI provider
    ●  The designer runs on OpenCode, which needs its own connection to a model.
    ●  This is one-time: the same connection runs your pipeline steps later.
    ●  You have Claude Code. In the picker choose "Anthropic" and paste an API key from console.anthropic.com — a Claude Pro/Max subscription can't be reused here.
    └  Opening the provider connection…

    Connect the tool you already have:

    You have In the menu, pick
    Claude Code Anthropic, then paste an API key from console.anthropic.com — a Claude Pro/Max subscription can’t be reused here
    GitHub Copilot GitHub Copilot, then GitHub.com (Public) (or GitHub Enterprise), and enter the device code at github.com/login/device
    Codex OpenAI, then Sign in with ChatGPT to use your ChatGPT subscription (or API key)
    None of these Any provider (Anthropic is recommended), then follow the prompts — see OpenCode’s Connecting providers

    It’s one-time: the same connection runs your steps later. Boboddy never reads those tools’ credentials. Already exported a key such as ANTHROPIC_API_KEY? This step is skipped.

  5. Talk to the designer

    terminal
    ┌   Boboddy pipeline designer
    ●  Logs → ~/.boboddy/logs/worker-2026-10-07T15-04-12-123Z.log
    ◆  AI provider ready (anthropic)
    ◇  Studio running at http://localhost:51234 [0s]
    └  Starting the designer… The graph is in your browser; the designer is in this terminal.

    Your terminal becomes the designer, and your browser opens the studio: a live graph of the pipeline that redraws every time the designer saves a file.

    The pipeline studio: the pipeline picker in the top bar, the graph of the pipeline’s states in the centre, and the validation issues panel on the right.

    The designer reads your repository first, then interviews you about the item you picked, one question at a time:

    • What should come out the other end? What you’d need to see to trust it. Most people accept the default.
    • What can the agent reach? A running copy of the app, and which of your repository’s MCP servers to use. “Nothing but the repository” is a fine answer.
    • What must never be touched? Production writes, customer data, anything that sends email or charges money.

    It adapts the default pipeline to your answers and writes the default pipeline assignment that routes new items to it. With no .devcontainer/devcontainer.json, it writes one (Runtime). For a secret it asks only the variable name; you put the value in .boboddy/.env (Secrets).

    Finally it typechecks and runs boboddy pipelines push, which always asks for permission. Say yes: that’s the moment your pipeline reaches Boboddy. Then quit the designer with /exit.

  6. Run it

    As the designer closes, it runs every step’s health checks, then asks whether to run it on your work item now:

    terminal
    ┌   Run it
    ●  Logs → ~/.boboddy/logs/worker-2026-10-07T15-04-12-123Z.log
    ◇  Health checks passed [1m 48s]
    ◇  Run your new pipeline on “Checkout crashes when a coupon is applied twice” now?
    │  Yes
    ◇  Run queued [0s]
    ●  A failed run — a step, or the devcontainer build — is something to take back to the designer: run `boboddy pipelines design` again and tell the agent what happened. The edit loop is the repair loop.
    └  Starting the worker…

    Say yes. It queues the run and starts a worker in the same terminal:

    terminal
    ┌   Boboddy worker
    ●  Logs → ~/.boboddy/logs/worker-2026-10-07T15-04-12-123Z.log
    ●  Using source branch: main
    ●  Project <project-id> · concurrency 1
    ◆  Worker ready (<worker-id>)
    ●  Claimed 1 task
    ◇  task <task-id> starting devcontainer… [0s]
    ◆  task <task-id> Running postCreateCommand... · 9s
    ◇  Task <task-id> succeeded (2m 26s) [2m 16s]
    ●  Claimed 1 task
    ◇  task <next-task-id> starting devcontainer… [0s]

    The worker polls until you press Ctrl+C. If the check or a step fails, run boboddy pipelines design again and tell the designer what happened. Said no? See Run a pipeline on any work item.

  7. Watch it in the dashboard

    Open your project in the dashboard, go to the Executions tab, and select the run. The run page shows the pipeline graph and each step’s status. Select a step for its logs and evidence: Output holds its result, such as the investigation report, and Artifacts its files. View trace opens a Playwright trace of the reproduction.

    That evidence is the point: you check the agent’s work instead of redoing it.

What you have now

Section titled “What you have now”
  • Directorymy-repo/
    • Directory.boboddy/
      • boboddy.jsonc the project, as owner/slug
      • .env.example secret variable names, only if a step needs any
      • Directorypipeline-builder/
        • bug-pipeline.ts the pipeline and its steps
        • default-pipeline-assignment.ts
        • package.json
        • …
    • Directory.devcontainer/
      • devcontainer.json written by the designer if you had none

Commit .boboddy/ and .devcontainer/; the builder’s .gitignore already skips node_modules/, push.ts, and lockfiles. Never commit .boboddy/.env.

Next

Section titled “Next”

Rather write pipelines by hand? Start from boboddy pipelines init.