Install and setup

Orgabot's local MVP targets macOS. Everything below runs from the repo root of your clone; each block is standalone, so the (cd … && …) subshell form leaves you back at the root.

Before you start: Orgabot is in first beta. Known limitations states plainly what it does not do yet, including which setup steps still need a terminal and which workflow terminals hold rather than complete.

Already have registered projects, organizations, connectors, or mission history? Use Upgrade an existing installation instead of repeating first-run setup.

Requirements

• macOS, with Node 22+ and npm (the framework pins a version in framework/.nvmrc).
• git. The GitHub CLI gh is required only for the optional owner-credential solo path; organization-owned GitHub App setup does not require a personal gh login.
• The claude CLI installed and logged in; it is the default worker. Without it, run missions with --mock.
• Optional: terminal-notifier for clickable notifications, ngrok for live GitHub state.

1. Install

git clone https://github.com/MattSenter/orgabot.git && cd orgabot
(cd framework && npm install)
bash orgabot-skills/install.sh
(cd framework && npm run orgabot -- doctor)

There is no root `package.json`: the dependencies live in framework/.

Recent npm versions may end the install with an allow-scripts warning naming esbuild and fsevents. That is expected and safe. It matters only because esbuild's postinstall fetches the binary tsx needs, and every npm run orgabot command runs the TypeScript sources through tsx. If the script really was blocked, doctor fails immediately with a missing-esbuild error; (cd framework && npm rebuild esbuild) fixes it.

orgabot doctor checks the local runtime, the ~/.orgabot/config.json pointer, registered projects, configured durability and connector readiness, and optional facilities such as terminal-notifier. It reports a missing gh login as a solo delivery limitation rather than making organization-owned GitHub App setup invalid, and it self-heals the config pointer.

The CLI is orgabot. The older orka name is kept as an alias binary and an alias npm script, so every command on this site also runs as orka … / npm run orka -- …. Nothing you already have scripted stops working.

Other legacy names, all still read. The rename widened every read set rather than narrowing it, so nothing in an existing setup has to be edited:

Setting both spellings of one variable to different values is refused rather than resolved silently, because an opt-in flag that quietly stopped working is worse than an error. Identical values are fine, which is what an operator mid-transition has.

The built-in workflow definition ids and the --orka-project flag are not renamed and never will be. The ids are pinned onto journal events permanently, so renaming one detaches every run whose journal already carries it, silently and with nothing to catch it. All twelve are frozen: orka.default, orka.release, orka.conversational, orka.interactive_task, orka.troubleshooting, orka.research_report, orka.review_audit, orka.issue_creation, orka.issue_management, orka.control, orka.external_operation and orka.baseline.

2. Set up AskOrgabot

AskOrgabot is Orgabot's built-in Help Desk assistant, reachable from the dashboard and via orgabot assistant. It is configured once per machine, before any organization exists:

(cd framework && npm run orgabot -- assistant set <provider> <model> --key <api-key>)
(cd framework && npm run orgabot -- assistant status)

OpenRouter works as an API-key provider with a namespaced model id, for example anthropic/claude-sonnet-4. AskOrgabot is not required to run missions (the solo path works without it), but a configured assistant can answer questions during everything that follows.

3. Start the resumable first-run journey

Start the supported local stack and open its localhost dashboard:

(cd framework && npm run orgabot -- up)   # dashboard + selected durability + services; http://127.0.0.1:4317

The full-page journey resumes safely after a refresh or GitHub round trip. It walks durability, Orgabot AI, organization, defaults, org chart, GitHub, project, verification, issue source, and first mission in that order. Safe draft choices are persisted; credentials and connector secrets are not. You can still create another organization later from the organization switcher.

4. Connect GitHub

Orgabot connects GitHub as a GitHub App, not as your personal login. In local auto-created or bring-your-own mode, the App private key stays in your protected credential store. In an isolated hosted deployment, the published App key stays inside its shared broker, which performs bounded requests without returning the key or installation token. Every mode preserves repository-and-permission scoping, and local-only operation remains supported.

(cd framework && npm run orgabot -- connector connect github-app <org> --app-id <id> --installation <id>)

See Connectors and tools for grants, scopes, and the three places a permission can be clamped.

5. Map a project

A project is a registered repo, optionally with a sub-path and a verify command:

(cd framework && npm run orgabot -- project add <repo-path> [--workdir <subdir>] [--name <n>] [--verify "<cmd>"])
(cd framework && npm run orgabot -- project list)

You can do the same from the dashboard: Repositories → Add repository registers a repo already on this machine or clones one from GitHub into ~/.orgabot/repos/<owner>/<repo>, then walks you through the detected profile before saving it. See Adding a repository.

The --verify command is the optional independent gate Orgabot runs for every mission on that project. When it is set (or a test suite is auto-detected), pass/fail is exit-code evidence and a red run blocks merge. When it is unset and nothing is detected, verification is skipped with honest evidence and does not block open-PR or merge; review and autonomy policy still apply. Set a verify command when you want Orgabot to machine-check before ship.

A brand-new repo with zero commits cannot run a mission. Make an initial commit and push main first.

6. Run your first mission

Continue in Your first mission.

Where state lives

All runtime state lives under ~/.orgabot/ (override with ORGABOT_HOME, or the older ORKA_HOME, which is still read):

Run against an isolated state directory with orgabot --home <dir>, which is useful for blank-slate testing. orgabot reset wipes an isolated home and refuses the default ~/.orgabot (and the older ~/.orka).

An install that already has a ~/.orka/ directory keeps using it in place: it is resolved after ~/.orgabot/ and never merged with it, so an existing machine needs no migration and no edit. Nothing moves the directory implicitly.