Cognitive safety layer for AI-assisted development
Deterministic behavior. Burnout protection. Built for neurodivergent brains.
Same signals → Same routing → Same behavior
You know the pattern:
Hyperfocus → ship fast → crash hard → forget where you were → start over
AI-assisted development makes this worse. You build at the speed of thought—until you can't think anymore. The AI doesn't know you're running on empty. It keeps generating, you keep accepting, and then you hit the wall.
Orchestra is the guardrail you can't build for yourself.
It sits between you and the AI, tracking what you can't track in the moment: your energy, your momentum, your approaching burnout. It adapts the AI's behavior to your actual capacity—not the capacity you wish you had.
| What you're experiencing | What Orchestra does |
|---|---|
| Depleted but pushing through | Blocks deep analysis, offers easy wins |
| Frustrated and spiraling | Empathy first, solutions second |
| Lost the thread | Resurfaces your goal and context |
| Hyperfocused for hours | Gentle checkpoint: "still good?" |
| In flow, shipping fast | Disappears. Stays out of your way. |
This isn't productivity software. It's cognitive sustainability.
Most tools optimize for output. Orchestra optimizes for sustainable output.
-
Your state overrides your requests. Ask for deep analysis while depleted? You get minimal. Safety gating isn't optional.
-
Emotional signals outrank task signals. Frustrated + exploring = empathy first. The routing priority is fixed: human needs before task completion.
-
Behavior is deterministic. Same input, same routing, every time. No more "why is the AI different today?" The uncertainty tax is gone.
-
Memory is external. Sessions persist. Context survives. You pick up where you left off, not where you vaguely remember being.
Built for brains that burn bright and need structure to fly.
pip install -e .orchestra install-hook
# Restart Claude CodeThat's it. Every message now passes through the cognitive engine.
Every message you send to Claude Code:
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: DETECT │
│ PRISM extracts signals: emotional > mode > domain > task │
└───────────────────────────┬─────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 2: CASCADE │
│ Safety gates + Cognitive Safety MoE routing (7 experts, first-match-wins) │
└───────────────────────────┬─────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: LOCK │
│ MAX3 bounded reflection + cognitive safety gating + deterministic checksum│
└───────────────────────────┬─────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 4: EXECUTE │
│ Claude generates response with locked parameters │
│ Anchor: [EXEC:a3f2b8|direct|Cortex|30000ft|standard] │
└───────────────────────────┬─────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PHASE 5: UPDATE │
│ RC^+xi convergence tracking → attractor basins │
└─────────────────────────────────────────────────────────────────────────────┘
Signals are routed to intervention experts in fixed priority order:
| Priority | Expert | Triggers | Response |
|---|---|---|---|
| 1 | Validator | frustrated, RED, caps | Empathy first, normalize |
| 2 | Scaffolder | overwhelmed, stuck | Break down, reduce scope |
| 3 | Restorer | depleted, ORANGE | Easy wins, rest is OK |
| 4 | Refocuser | tangent, distracted | Gentle redirect |
| 5 | Celebrator | task_complete | Acknowledge win |
| 6 | Socratic | exploring, what_if | Guide discovery |
| 7 | Direct | focused, flow | Minimal friction |
First match wins. If you're frustrated AND exploring, Validator (priority 1) takes precedence.
The system protects you from yourself:
| State | Max Thinking Depth |
|---|---|
energy=depleted |
minimal |
energy=low |
standard |
burnout>=ORANGE |
standard |
burnout=RED |
minimal |
energy=high |
ultradeep (if requested) |
Rule: Safety state ALWAYS overrides user requests. Can reduce depth, never increase.
# Dashboard
orchestra # Launch TUI dashboard
orchestra status # Show cognitive status
orchestra status --short # Minimal status line
# State management
orchestra set -b YELLOW # Set burnout level
orchestra set -e low # Set energy level
# Hook management
orchestra install-hook # Install Claude Code integration
orchestra uninstall-hook # Remove integration
# Shell integration
orchestra init bash # Get bash prompt config
orchestra init zsh # Get zsh prompt configSessions auto-reset after 2 hours of inactivity:
- Resets: exchange counts, session timing, momentum, tangent budget
- Preserves: focus_level, urgency, energy_level (user preferences)
- Clears burnout: If you were ORANGE/RED, you start fresh at GREEN
All state lives in ~/.orchestra/:
~/.orchestra/
├── state/
│ └── cognitive_state.json # 37 fields, all 5 phases
└── config/
└── orchestra.json # User preferences (future)
ThinkingMachines [He2025] compliance:
- FIXED evaluation order (5 phases, no reordering)
- FIXED signal priority (emotional > mode > domain > task)
- FIXED expert priority (Validator > Scaffolder > ... > Direct)
- LOCKED parameters before generation
- REPRODUCIBLE checksums (same input → same checksum)
pytest tests/test_cognitive_engine.py -vfrom orchestra import create_orchestrator
orchestrator = create_orchestrator()
result = orchestrator.process_message("help me implement this feature")
print(result.to_anchor()) # [EXEC:a3f2b8|direct|Cortex|30000ft|standard]
print(result.routing.expert) # Expert.DIRECT
print(result.convergence.epistemic_tension) # 0.05echo '{"user_prompt": "test"}' | python -m orchestra.hooksOrchestra/
├── src/orchestra/
│ ├── cognitive_orchestrator.py # 5-Phase NEXUS Pipeline
│ ├── expert_router.py # Cognitive Safety MoE (7 experts)
│ ├── parameter_locker.py # MAX3 + safety gating
│ ├── convergence_tracker.py # RC^+xi tracking
│ ├── prism_detector.py # Signal detection
│ ├── cognitive_state.py # State management
│ ├── dashboard_bridge.py # WebSocket sync
│ ├── websocket_server.py # Real-time dashboard
│ ├── hooks/
│ │ └── cognitive_hook.py # Claude Code hook
│ └── cli/
│ └── main.py # CLI entry point
├── tests/ # 766 tests (100% pass)
│ ├── test_cognitive_engine.py # Core orchestration
│ ├── test_parameter_locker.py # Safety gating
│ ├── test_otel_adapter.py # Observability
│ └── ... # Integration, chaos, resilience
└── pyproject.toml # v5.0.1
Orchestra is built for neurodivergent brains:
- Safety first - Emotional safety before productivity
- Ship over perfect - Working beats polished
- Protect momentum - Don't break flow unnecessarily
- External memory - Write it down, don't hold it in your head
- Recover without guilt - Rest is productive
| Document | Description |
|---|---|
| CHANGELOG | Version history and release notes |
| QUICKSTART | 2-minute setup guide |
| ARCHITECTURE | Technical deep-dive |
| CONTRIBUTING | Development guidelines |
| CITATIONS | Academic references |
# From PyPI
pip install cognitive-orchestra
# From source
git clone https://github.com/JosephOIbrahim/Orchestra.git
cd Orchestra
pip install -e .- USD composition semantics for cognitive state
- ThinkingMachines [He2025] for batch-invariance
MIT License - see LICENSE for details.
Orchestra v5.0.1 - Cognitive Engine for Claude Code
