Cleepi

Autonomous SDD board for any repo. Triages tickets, drafts specs, runs the work in isolated worktrees, opens PRs. Driven by pi under the hood, so you bring your own model (Claude, Codex, Copilot, API keys — whatever you already pay for).

Status: pre-1.0. Not yet published to npm — see Local install while we get the package out the door.

Two-command setup

Requires Node 20+.

# 1. Install pi (the agent runtime)
npm i -g --ignore-scripts @earendil-works/pi-coding-agent

# 2. Run cleepi inside your project
cd /path/to/your/project
npx @cleepi/board@latest

That's it. The board opens at http://localhost:3721.

First run does two things you'll need to handle once:

• Sign in to a model. Run pi once in any directory and execute /login — pick Claude, ChatGPT, Copilot, or paste an API key. Pi remembers it; cleepi reuses it.
• (Optional) Wire Jira. Click ⚙️ in the board → Authenticate next to Atlassian → pick your site and project keys. Skip this if you just want the board for ad-hoc cards.

What you get

• Six-column board — Triage → Spec Review → Todo → In Progress → In Review → Done. Cards are SDD specs on disk (docs/<KEY>-slug/spec.md), not a hidden database. Everything is grep-able, git-able, PR-reviewable.
• Autonomous triage. Drop a rough idea or a Jira ticket; the agent drafts a spec, you review it, accept it.
• Isolated execution. Accepted specs run in their own git worktree on their own branch. No clobbering your working copy.
• PRs out the other end. When the agent's reviewer approves, cleepi opens a PR. Human merges.

Commands

cleepi                  # start the board (default port 3721)
cleepi --port 4000      # custom port
cleepi --no-open        # don't open browser (CI / headless)
cleepi --help

Configuration

Cleepi reads cleepi.json from the project root. The file is created on demand by the Settings modal — you don't need to write it by hand. If you prefer to, the shape is:

{
  "mcpServers": {
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1/mcp/authv2",
      "auth": "oauth",
      "lifecycle": "lazy"
    }
  },
  "jira": {
    "cloudId": "...",
    "siteUrl": "https://yourco.atlassian.net",
    "projectKeys": ["ABC"],
    "pollIntervalSec": 60
  },
  "triage": { "autoTrigger": false }
}

docs/ (your spec folder) is created the first time a spec is drafted.

Local install

Until @cleepi/board is on npm, run it from this checkout:

git clone <this-repo>
cd cleepi
pnpm install
pnpm build
node packages/board/dist/bin.js

Or in watch mode:

pnpm dev

Troubleshooting

"Authenticate" doesn't open a browser. Make sure pi is installed globally and on your PATH (which pi). Cleepi shells the OAuth flow through pi's MCP adapter, which uses the system open / xdg-open. Headless servers won't get a browser — that's a known limitation.

Port 3721 in use. cleepi --port 4000.

Board empty, no tickets showing. Either you haven't authenticated Jira yet (Settings → Atlassian), or your projectKeys don't match any open tickets. Try a Draft card to confirm the board works.

"No model configured". Run pi in any directory and /login. Cleepi can't pick a model for you.

Architecture

Four packages, one binary:

• @cleepi/core — TaskStore (reads spec.md frontmatter), config, types.
• @cleepi/engine — Triage + executor + worktree pool. Embeds pi via the SDK; never spawns it as a subprocess.
• @cleepi/dashboard — Express + SSE server, React board UI.
• @cleepi/board — Thin wrapper that boots engine + dashboard.

Forked from dustinbyrne/kb; see FORK.md for what changed.

License

ISC. See FORK.md for upstream attribution.