Orra

Directive & intelligence layer over Claude Code's Agents View.

You: (just open Claude Code)

Orra: Morning. Yesterday's first move was: pick back up on JWT refresh.
      Today's situation:
      • Due today: AUTH-142 (in_progress, worktree auth-refactor)
      • Ready to land: billing-fix — PR approved, mergeable
      • Needs attention: onboarding — blocked (claude attach abc1234f)
      Recommended first action: triage onboarding (30s), then JWT.
      What's your plan for today?

You: focus is JWT, ship by 4pm.

Orra: Got it. I'll align suggestions to that. Spawning a background
      agent to rebase the 2 stale worktrees while you work — they'll
      be ready when you come back to them.

Orra is the standing orchestrator — the directive/intelligence/memory layer that rides on
Claude Code's Agents View. The Agents View tells you
"row 3 is waiting." Orra reads what row 3 is waiting on, runs a directive to handle it,
keeps the memory layer, and reports a condensed picture.

What it is

Orra is not a worktree manager or a process supervisor — Claude Code's Agents View handles
that. Orra is the layer on top: morning briefing, a heartbeat-driven directive pack, the
.orra/memory/ layer, PR shepherding, Linear deadline tracking, and per-worktree cost tracking.
It runs as a persistent claude --bg background agent so the heartbeat never needs re-arming.

Requires Claude Code ≥ 2.1.x with the Agents View enabled.

Three capabilities:

Awareness — orra_scan joins the daemon roster ($CLAUDE_CONFIG_DIR/jobs/)
with git worktree list, PR data, and custom providers. Classifies status
(ready_to_land, needs_attention, in_progress, idle, stale) and pre-computes
per-agent summaries so you never re-parse transcripts.
Learning — a markdown memory layer under .orra/memory/. Daily notes, commitments,
per-worktree notes, and weekly retros persist across sessions. Directives like
morning-briefing and shutdown-ritual maintain it for you.
Coordination — orra_spawn wraps claude --bg; spawned sessions appear in
claude agents. orra_kill calls claude stop/claude rm. Blocked agents surface as
needs_attention with a claude attach <id> hint.

Architecture

                    ┌─────────────────────────────────────────────┐
                    │  Claude Code Agents View (the substrate)     │
                    │  - supervisor daemon                         │
                    │  - claude --bg / agents / attach / stop / rm │
                    │  - native git worktrees (--worktree)         │
                    │  - WorktreeCreate / WorktreeRemove hooks     │
                    └───────────────▲─────────────────────────────┘
                                    │ on-disk state + CLI shell-out
                    ┌───────────────┴─────────────────────────────┐
                    │  Orra (the intelligence + directive layer)   │
                    │                                              │
                    │  MCP server (11 tools):                      │
                    │    orra_scan / orra_inspect  ← classified    │
                    │       view: daemon roster ⨝ git worktree     │
                    │       list ⨝ PR ⨝ pipeline ⨝ providers      │
                    │    orra_spawn  → wraps claude --bg           │
                    │    orra_kill   → claude stop / claude rm     │
                    │    orra_rebase → bg spawn w/ rebase task     │
                    │    orra_directive / orra_tick / orra_resume  │
                    │       / orra_checkpoint / orra_cache_write   │
                    │    orra_setup  (bootstrap)                   │
                    │                                              │
                    │  Persona: orchestrator.md                    │
                    │    runs as a persistent claude --bg session  │
                    │    (`claude --bg --agent orchestrator        │
                    │     --name orra`)                            │
                    │                                              │
                    │  State (files only):                         │
                    │    .orra/memory/  .orra/directives/          │
                    │    .orra/spawns/  .orra/state/               │
                    └──────────────────────────────────────────────┘

Install

Option A — as a Claude Code plugin (recommended)

# From a local clone (until the plugin marketplace is available)
claude --plugin-dir /path/to/orra-mcp

This registers the orchestrator agent, the /orra command, and the orra-mcp
MCP server in one step.

Option B — as a standalone MCP server

claude mcp add orra -- npx orra-mcp

Quick start

1. Scaffold the project

In any Claude session, run:

"run orra_setup"

This creates .orra/config.json, installs the orchestrator agent at
.claude/agents/orchestrator.md, merges the Orra MCP server entry into .mcp.json,
writes a sample WorktreeCreate hook to .claude/hooks/worktree-create.sh, and
scaffolds the memory layer. Idempotent.

2. Install the directive pack

"install all orra directives"

Copies the full directive library (10 directives) into .orra/directives/. Each
declares its own "lane" so they compose without conflict.

3. Start the orchestrator

orra
# or: claude --bg --agent orchestrator --name orra

The orra bin ensures the orchestrator is running as a named background agent.
To talk to it: claude attach orra.

A day with Orra

Morning — awareness

The morning-briefing directive fires automatically on session start. It calls orra_scan,
reads yesterday's daily note, checks commitments.md, and composes the picture.

Side tasks — delegation

While you work, auto-remediator notices stale worktrees and spawns bg agents via
orra_spawn (claude --bg) to rebase them. They appear in claude agents. Results show
up in the next orra_scan. You never had to stop.

End of day — memory

shutdown-ritual writes .orra/memory/daily/<today>.md with shipped/open/first-move
sections. Tomorrow's morning-briefing reads this and starts you exactly where you left off.

Writing your own directive

Directives are markdown files in .orra/directives/ that the orchestrator reads each tick.

---
heartbeat:
  cadence: 15m
---
## Directive Title
...
### Heartbeat invocation
(what to check each tick)

YAML frontmatter is optional. session_start: auto + once_per: day + resets_at: "HH:MM"
opts into auto-run at session start. See docs/directives.md.

Tools (11)

Tool	Purpose
`orra_scan`	Scan all worktrees. Daemon roster ⨝ git ⨝ PR ⨝ providers → classified view with pre-computed summaries.
`orra_inspect`	Deep dive on one worktree — commit log, markers, conflict prediction, transcript tail.
`orra_kill`	Stop (`claude stop`) or remove (`claude rm`) a bg agent + optional PR cleanup.
`orra_rebase`	Rebase a worktree branch onto latest main (spawns a bg agent).
`orra_setup`	Scaffold `.orra/` + install orchestrator agent + WorktreeCreate hook. Idempotent.
`orra_directive`	Manage directives (add, list, remove, install shipped ones).
`orra_spawn`	Spawn a bg agent via `claude --bg`. Sessions visible in `claude agents`.
`orra_resume`	Restore session state after `/compact`.
`orra_tick`	Heartbeat dispatcher — runs due directives.
`orra_checkpoint`	Write session state to disk for compact survival.
`orra_cache_write`	Write a subagent digest into the session cache.

Requirements

Node.js 20+
Claude Code CLI ≥ 2.1.x with Agents View enabled
A git repository

Development

git clone https://github.com/bjornj12/Orra-mcp.git
cd Orra-mcp
npm install
npm run build
npm test

Local development against a real project

npm run link:dev     # builds + globally links this worktree as orra-mcp
# after source changes:
npm run build       # symlink already targets dist/, no re-link needed
# when done:
npm run unlink:dev && npm i -g orra-mcp   # restore published version

Bugs and feature requests

Please open an issue.
For security vulnerabilities, see SECURITY.md.

License

MIT

Orra-mcp