Orca Bot Kit

A kit for running a small fleet of long-lived role bots on your own computer — a manager, developers, reviewers, a personal helper. Each bot keeps its identity, its rules, its skills and its sessions across restarts.

Orca is the host: a bot is an Orca project and a session is a tab, on Claude Code, Codex or Pi. The kit is an npm package with an obk command and a set of skills. You are meant to manage the fleet by talking to Bot Father, the first bot, whose skills call the CLI for you — not by editing files.

The design is in docs/prd/prd.md; the decisions with lasting consequences are in docs/adr/; what we know about Orca and the harnesses is in docs/tech-notes.md.

Start here

Paste this into any AI session that can run commands — a Claude Code or Codex session in a terminal, or anything else with a shell:

Set up Orca Bot Kit on this machine: get https://github.com/guwenqing/orca-bot-kit, then follow SETUP.md in it to the end.

It checks what your machine already has, tells you plainly about anything missing rather than installing it, asks you the only two things it cannot work out for itself — where your bots folder goes, and which harness Bot Father runs on — and leaves you talking to Bot Father, which is where everything after this happens.

SETUP.md is that page. It is written for the assistant rather than for you, so you do not have to read it; nothing in it is hidden from you either.

The rest of this README is the reference: what each command does, and why the kit is built the way it is. Reach for it when you want to know how something works, not to get started.

Reporting a problem

When the kit itself goes wrong (an obk command fails in a way its own message does not explain, or does something other than what it says), open an issue on this repository’s Issues page (the address package.json gives as bugs) with the form there. It asks for the command and its whole output, what you expected, obk health --json, and the versions of obk, Node, Orca and the harness. Take out anything private first: issues are public.

Bot Father is told the same thing. Tell it what went wrong and it gathers these details and, when you say so, files the issue or gives you the text to paste.

Status

Early. The CLI creates your bots folder, brings Bot Father up in Orca, creates bots and their sessions on any of the three harnesses, and builds each bot’s AGENTS.md from its charter and the rules it carries.

Install

Node.js >= 24.21.0, git, and Orca with at least one of Claude Code, Codex or Pi installed and configured. That line because the kit keeps writers out of each other’s way in a bot’s book with a SQLite write transaction, through Node’s own node:sqlite. That module is older than the 24 line; 24.21.0 is the first release measured here that loads it without an experimental warning on stderr,