Orbital Command

The orchestration layer for Claude Code.

The control layer that turns scattered Claude Code sessions into a coordinated engineering operation. Full visibility across every project. Enforced consistency every dispatch. Living documents from idea to production.

18 skills | 33 hooks | 6 agents | 13 quality gates | 4 workflow presets

Install

npm install -g orbital-command
orbital

1. Install -- adds the orbital CLI to your PATH
2. Run orbital -- the setup wizard configures Orbital globally (~/.orbital/), then launches the dashboard
3. Add your first project -- the dashboard opens with an Add Project modal. Point it at a git repo and Orbital scaffolds hooks, skills, agents, and workflow config into the project
4. Onboarding walkthrough -- the dashboard guides you through the board, dispatch, and key concepts

Prerequisites

• Node.js >= 18
• Claude Code installed and available as claude on your PATH
• iTerm2 (macOS) -- required for dispatching Claude Code sessions. Orbital opens named, categorized terminal tabs -- one per dispatched scope -- so you can watch sessions in parallel and step in at any time. The dashboard will prompt you to install and open iTerm2 before allowing dispatch.
• C++ compiler for the better-sqlite3 native module:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential (apt install build-essential)

What You Get

After adding a project, Orbital scaffolds these into your repo:

.claude/
  orbital.config.json       # Project configuration
  hooks/                    # 33 lifecycle hook scripts
  skills/                   # 18 skill definitions (slash commands)
  agents/                   # 6 agent team definitions
  config/                   # Workflow config and presets
scopes/
  _template.md              # Scope document template
  planning/                 # One directory per workflow column
  ...

No cloud. No accounts. No lock-in. Scopes are markdown. Events are JSON. Config is JSON. Everything is inspectable, diffable, version-controlled. Stop using Orbital tomorrow -- your work is still files in your repo.

Dashboard

The dashboard runs at http://localhost:4444 and manages all your registered projects from a single view.

Core Concepts

Scopes

Scopes are the unit of work. Each scope is a markdown file with YAML frontmatter stored in scopes/<column>/. Moving a scope between columns on the board physically moves the file between directories.

---
id: 42
title: "Add user authentication"
status: implementing
category: feature
priority: high
effort_estimate: "1-4H"
blocked_by: [41]
---

Each scope document has three parts: Dashboard (status, progress, next actions), Specification (requirements, phases, success criteria -- locked after planning), and Process (exploration log, decisions, implementation notes). An Agent Review section captures findings from automated analysis.

Workflow Engine

The workflow engine defines your Kanban columns, allowed transitions, branching strategy, and lifecycle hooks. Four presets ship out of the box -- switch any time via the Workflow Visualizer or edit .claude/config/workflow.json directly.

Dispatch

When you dispatch a scope from the board, Orbital validates the transition, resolves the skill command for that edge (e.g., /scope-implement), and spawns a Claude Code session in an iTerm2 tab. Hooks fire during the session and write JSON events to .claude/orbital-events/. The server watches that directory, ingests events into SQLite, and pushes real-time updates to the dashboard via Socket.io.

If the dashboard is offline, events queue as files and get ingested on next launch. Sprint dispatch resolves dependencies via topological sort and launches scopes in parallel across iTerm2 tabs with staggered intervals.

How It Works

The core loop

Everything in Orbital is scope-driven. A scope is a living markdown document -- not a throwaway plan, but a persistent record that carries spec, phases, progress, review results, and decisions with the work from idea to production. Scopes live as files in your repo (scopes/<column>/NNN-title.md), tracked in git alongside your code.

The dashboard presents these scopes as cards on a Kanban board. Each column maps to a stage in your workflow. When you drag a card to the next column, Orbital does the rest -- it validates the transition against the workflow DAG, resolves the skill command wired to that edge (e.g., /scope-implement), and auto-dispatches a Claude Code session in an iTerm2 tab to execute it. The scope document is the session's instructions. Hooks fire throughout, writing JSON events back to the dashboard in real time.

The result: you manage work by moving cards. Orbital handles the orchestration -- which skill to run, which hooks to fire, which agents to invoke, which gates to check. Every dispatch follows the same system, in the same order, through the same gates.

End-to-end flow (Default preset)

Icebox → Planning → Backlog → Implementing → Review → Completed → Main

1. Create -- Run /scope-create in a Claude Code session. Orbital scaffolds a scope document in scopes/planning/ with a structured template: specification, phases, success criteria, and process sections.

2. Plan -- Fill in the specification. The scope lives in planning/ while requirements are defined. Once the spec is solid, drag the card to Backlog. The spec locks -- no more changes to requirements from here.

3. Implement -- Drag to Implementing. Orbital auto-dispatches /scope-implement in an iTerm2 tab. The session picks up the scope document and executes its phases end-to-end. Hooks track the session, log commits, and enforce rules throughout.

4. Review -- Drag to Review. Orbital auto-dispatches /scope-post-review, which fans out the agent team. Red team (Attacker, Chaos) probes for vulnerabilities and failure modes. Blue team (Frontend Designer) checks UX. Green team (Architect, Rules Enforcer) validates structure and standards. Findings flow back to the dashboard in real time.

5. Fix -- If agents found issues, /scope-fix-review executes all findings. /scope-verify runs the formal review gate -- spec compliance, test results, 13 quality gates. The scope moves to Completed when everything passes.

6. Ship -- Drag to Main. Orbital auto-dispatches /git-main, which pushes or creates a PR. Done.

What ties it together

• Skills define what happens at each transition (the prompt Claude Code receives)
• Hooks define what runs automatically during each session (33 lifecycle scripts)
• Agents define who reviews the work (6 agents across 3 teams)
• Gates define what must pass before a transition is allowed (13 quality checks)
• The workflow DAG wires all of these together -- which skill fires on which edge, which hooks attach, which agents trigger, what confirmation level is required

All of this is config-driven and editable via the visual DAG editor in the dashboard.

Event bus

Hooks write JSON events to .claude/orbital-events/ during sessions. The server watches this directory, ingests events into SQLite, and pushes real-time updates to the dashboard via Socket.io. If the dashboard isn't running, events queue as files and get picked up on next launch. No daemon required.

Sprints

For batch work, group multiple scopes into a sprint. The orchestrator resolves dependencies via topological sort, organizes scopes into execution layers, and dispatches them in parallel across iTerm2 tabs with staggered intervals.

Skills

Skills are slash commands invoked in Claude Code sessions. Installed as markdown files in .claude/skills/.

Scope Lifecycle

Git Operations

Testing & Sessions

Agents

Six agents organized into three teams. Auto-triggered by hooks during scope transitions or invoked manually via /scope-pre-review.

Agents run in three modes, configured per-transition in the workflow: Quick (relevant agents only), Full (all agents), Security (red team focus).

Quality Gates

Thirteen automated checks that block or allow scope transitions. Reported by hooks and displayed in the Guards view with trend charts and override tracking.

Hooks

Hooks are shell scripts in .claude/hooks/ that fire automatically during Claude Code lifecycle events. They're registered in .claude/settings.local.json and triggered at these points:

Hooks communicate through the file-based event bus. When something significant happens, the hook writes a JSON event to .claude/orbital-events/. The server watches, ingests into SQLite, and pushes updates to the dashboard. Events queue naturally when the server is offline.

CLI Reference

The bare orbital command is the primary entry point -- it detects context and shows the right options.

Core

Template Management

Project Management

Other

Configuration

Project configuration lives at .claude/orbital.config.json. Edit directly or use orbital config.

{
  "projectName": "My Project",
  "serverPort": 4444,

  "terminal": {
    "adapter": "auto"        // "auto" | "iterm2" | "subprocess" | "none"
  },

  "claude": {
    "executable": "claude",
    "flags": ["--dangerously-skip-permissions"]
  },

  "commands": {
    "typeCheck": "npm run typecheck",
    "lint": "npm run lint",
    "build": "npm run build",
    "test": "npm run test"   // null = disabled
  }
}

Environment Variables

FAQ

Can I use this without Claude Code?

No. Orbital is purpose-built for Claude Code. Hooks, skills, agents, and session tracking all depend on Claude Code's lifecycle events and CLI.

Do I need to keep the dashboard running?

No. Hooks write events as JSON files regardless of whether the server is running. Events queue up and get ingested when you next launch.

How do I customize the workflow?

Open the Workflow Visualizer (/workflow in the dashboard). Add or remove columns, create transitions, attach hooks, set confirmation levels. Or edit .claude/config/workflow.json directly.

What if I don't have iTerm2?

The dashboard requires iTerm2 for dispatch -- it will show a modal prompting you to install or open it before any session can launch. iTerm2 lets Orbital open named, categorized terminal tabs (one per dispatched scope) so you can watch multiple sessions run in parallel and step into any of them. There is a "subprocess" terminal adapter in the config for headless/scripting use cases, but the dashboard UI expects iTerm2.

How do sprints work?

Sprints group multiple scopes for batch execution. The orchestrator resolves dependencies via topological sort, organizes scopes into execution layers, then dispatches them in parallel across iTerm2 tabs.

How do I add my own agents?

Create a markdown file in .claude/agents/<team>/ following the existing agent format. Add the agent to the agents array in orbital.config.json. Agents are dispatched as independent Claude Code sessions with the markdown file as their system prompt.

How do I reset everything?

orbital uninstall removes all Orbital artifacts. Your scopes/ directory and event history are preserved.

npm install
npm run dev:local

npm run release             # patch bump
npm run release -- minor    # minor bump
npm run release -- major    # major bump

See CHANGELOG.md for version history.

Contributing

Open an issue first for large changes. Fork, npm install, npm run dev:local, validate with npm run validate before submitting.

License

MIT

GitHub | npm