StaffOS turns every Claude Code session into a verified engineering record — intent, files touched, tests run, risks found, decisions made, and the human review required.
AI coding agents are becoming the worker. The hard part is no longer writing code — it's trusting, reviewing, governing, and remembering what the agent did.
A normal dashboard says "Claude Code ran." StaffOS says "Claude Code made this change, with this risk level, these tests, these missing checks, and this documentation requirement."
Every session on a branch produces a living Run Passport — a structured, versioned record that answers the questions a reviewer actually asks:
| 🎯 Intent | What was the goal? |
| 📂 Files touched | What was inspected and changed? |
| 🧪 Test evidence | What passed, what failed, what wasn't run? |
| Deterministic rules — auth/payments/infra = high | |
| ✅ Missing checks | The gaps to close before merge |
| 👤 Human review | Is sign-off required? |
| 📝 Documentation | ADRs, decision logs, and PR summaries to save |
Passports mutate as work continues and capture immutable version snapshots at each milestone, giving a clear timeline of how a change matured.
StaffOS is deliberate about when it spends tokens (configurable, see below):
| Mode | What it does | Model |
|---|---|---|
| Passive | Records events, builds the timeline. No LLM call. | — |
| Smart Summary | Summarises the session and extracts review gaps. | Claude Haiku 4.5 |
| Full Council | Six personas (Staff Eng, SRE, Security, PM, Devil's Advocate, Writing Coach) review the change. | Claude Opus 4.8 |
Risk level always stays deterministic (spec §15). The LLM enriches the narrative and findings; it never overrides the rules. Only metadata is sent — file paths, categories, test summaries — never your source code. No API key? Every mode degrades gracefully to deterministic heuristics.
Claude Code ─▶ Claude Code hooks ─▶ StaffOS connector ─▶ Ingestion API
│ │
│ ▼
│ Run event store
│ │
▼ ▼
Web dashboard ◀─ Documentation engine ◀─ Passport generator ◀─ Risk engine
Everything is scoped to a Project (a repo) → Workstream (a branch) → sessions, events, passport, council reviews, documents, and memory. On merge, knowledge promotes to the project's permanent knowledge base. Zero cross-project leaking.
# 1. Install dependencies and prepare the database
bin/setup # or: bundle install && bin/rails db:prepare db:seed
# 2. Run the app
bin/dev # http://localhost:3000
# 3. (optional) Enable AI reviewers
export ANTHROPIC_API_KEY=sk-ant-...cli/staffos login # enter your endpoint + project token
cli/staffos init # writes .staffos.yml and installs Claude Code hooks
# ...use Claude Code normally — events are captured automatically...
cli/staffos passport # see the latest passport for your branch
cli/staffos disconnect # remove credentials and hooksinit installs HTTP hooks (SessionStart, UserPromptSubmit, pre/post tool
use, Stop) into .claude/settings.json. Claude Code POSTs each event to
StaffOS, which routes it to the right Workstream by branch.
| Environment variable | Purpose | Default |
|---|---|---|
ANTHROPIC_API_KEY |
Enables Smart Summary + Full Council. Unset → heuristics. | — |
STAFFOS_SUMMARY_MODEL |
Model for smart summaries | claude-haiku-4-5 |
STAFFOS_COUNCIL_MODEL |
Model for council reviews | claude-opus-4-8 |
The key can also live in Rails encrypted credentials under anthropic.api_key.
bin/rails test # full suite (Minitest)
COVERAGE=false bin/rails test # skip coverage instrumentationThe suite covers the risk engine, passport generation, the AI council's heuristic fallback, the document generator, the model layer, the Claude Code hook ingestion API, and the authenticated UI flows. Coverage is measured with SimpleCov and reported in CI.
| Workflow | Runs | Does |
|---|---|---|
CI (ci.yml) |
every push & PR | Minitest + coverage, RuboCop (Omakase), Brakeman, bundler-audit, importmap audit |
Deploy (deploy.yml) |
push to main |
Kamal deploy, gated on KAMAL_REGISTRY_PASSWORD — skips cleanly until you wire a server |
Rails 8.1 · Hotwire (Turbo + Stimulus) · Tailwind CSS · PostgreSQL · Solid Queue/Cache/Cable · Devise · Anthropic Ruby SDK · Kamal · Minitest + SimpleCov
app/services/ risk_scorer · passport_generator · council_runner
document_generator · llm_client
app/controllers/api/ Claude Code hook ingestion (v1)
cli/staffos local connector CLI
db/ schema, migrations, seed data
test/ services · models · integration (API + UI)
SPEC.md the full product brief