Skip to main content
Version: Next

Install

Orion is a single static binary that supervises the Claude CLI, git, gh and the operating system's sandbox. Install it and the two toolkits it delegates to, then run orion doctor to check the machine is ready.

macOS and Linux​

brew install navjyotnishant/tap/orion

Windows​

scoop bucket add navjyotnishant https://github.com/navjyotnishant/scoop-bucket
scoop install orion

The OS sandbox Orion configures is macOS and Linux only. On Windows, orion doctor reports no supported OS sandbox and workspaces refuse to start, so run Orion under WSL2 or in a Linux VM.

From source​

git clone https://github.com/NjAIAgents/orion && cd orion
make test          # build, vet, gofmt and the full suite
make install       # to ~/.local/bin

make install puts the binary in $(PREFIX)/bin, where PREFIX defaults to ~/.local, and tells you if that directory is not on your PATH. Building needs only Go 1.25 or newer; there are no third-party modules.

Install nj-agents​

Orion delegates review, secret scanning, test and build verification, PR authoring and work decomposition to nj-agents. Those stages have no fallback, so orion doctor grades a missing toolkit as FAIL.

orion doctor --fix      # clones it if absent

If you intend to work on the toolkit, install it yourself:

git clone https://github.com/navjyotnishant/nj-agents
cd nj-agents && ./install.sh

Orion reads a global install and never writes to it; it updates only a clone it fetched itself. nj-agents and other toolkits covers how Orion finds the checkout and what it delegates.

Install the spec-kit CLI​

orion plan delegates four planning steps (constitution, spec, plan and analyze) to spec-kit and installs spec-kit into each project itself. You install only the CLI:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.4

Orion pins spec-kit to v1.0.4, because the skill names and markers it reads come from that release. orion doctor prints the installed version beside the pin. orion doctor --fix never clones spec-kit, since a clone does not install it.

Configure credentials (optional)​

orion config        # Jira, Slack, webhooks; secrets are not echoed
orion config show   # what is set, where from, masked

Both Jira and Slack are optional. Credentials covers getting the tokens and proving they work.

Run orion doctor​

orion doctor

Every check is graded OK, WARN or FAIL. FAIL blocks; WARN means reduced capability. The exit code is non-zero only when something FAILs, so orion doctor works as a CI gate. jira warns until you configure it, which you need only for tracker provisioning.

CheckWhat it proves
claude CLI, claude auththe binary Orion supervises exists, runs and is signed in
gitpresent, and user.name and user.email are set, or commits are unattributable
gh CLI, gh repo scopegh is present and its token can create a repository, not merely that you are logged in
nj-agentsthe toolkit is present and intact, resolved through the skill symlink to its clone root
os sandboxSeatbelt (macOS) or bubblewrap (Linux) is available
orion home, disk~/.orion (or ORION_HOME) is writable, and readable by you alone: it holds credentials, spend and full run transcripts
project config, branch model, hooksthis repository's orion.json loads, its work branch differs from its release branch, and the hooks are wired
attributioncommits will carry an attribution trailer (below)
jira, slack, slack audiencethe optional integrations are reachable, authenticated and pointed where you think
toolkit reach, spec-kit CLIshown only when relevant: what a supervised run will actually be able to call, and the specify CLI's version and features
A missing OS sandbox is a WARN, but nothing will run

os sandbox grades a missing sandbox as WARN so that doctor passes on a machine used only for planning, but the generated settings require the OS sandbox and every workspace refuses to start without it. Read that line even when the summary says "Ready".

Commit attribution​

Orion stamps each commit with an AI-Attribution trailer using whodunit's dun collector. attribution.enabled defaults to on. When dun is missing and attribution.auto_install is on (also the default), orion init offers to install it through Homebrew, Scoop or go install, asking first.

The doctor attribution check runs dun verify in your checkout and in the sandbox clone where agents commit. To drop the trailer, turn attribution off in orion.json.

Staying current​

status, doctor, watch, collect, work and init print one line when a newer release exists, naming the upgrade command for how this machine installed Orion:

update    orion v0.5.1 is available (you have v0.5.0)
          brew upgrade navjyotnishant/tap/orion

The check asks GitHub for the latest release of NjAIAgents/orion-releases. It is cached for 24 hours in ~/.orion/state/update.json and refreshed by a background process, so no command waits on it. With no network, nothing is printed and nothing fails. It never runs in hook mode, off a terminal, or when CI is set.

To silence it permanently, because you are pinned to a version on purpose:

export ORION_NO_UPDATE_CHECK=1

or add the same line to ~/.orion/config.env.

What changed in each release is in the release notes.

Next​