exoprotocol 0.2.1

Repo-native governance kernel for ExoProtocol

(/)(°,,°)(/)

ExoProtocol

Governance kernel for multi-agent development. Treats AI-agent sessions the way an OS treats processes — with enforceable scope, lifecycle control, audit trails, and crash recovery. Everything lives in your git repo.

Why

When multiple AI agents vibe-code on the same repo, things go wrong silently: scope collisions, forgotten context, ungoverned commits, duplicated work. ExoProtocol gives each agent session a ticket, a scope fence, and a paper trail — without leaving git.

Install

pip install exoprotocol

Quickstart

# 1. One-shot setup (init + compile + adapters + hooks + gitignore)
exo install

# 2. Dispatch a ticket
exo next --owner your-name

# 3. Start a governed session
EXO_ACTOR=agent:claude exo session-start \
  --ticket-id TICKET-001 \
  --vendor anthropic --model claude-code \
  --context-window 200000 \
  --task "implement the feature described in the ticket"

# 4. Finish the session
EXO_ACTOR=agent:claude exo session-finish \
  --summary "implemented feature, added tests" \
  --set-status review

Session start generates a bootstrap prompt with governance rules, scope constraints, sibling awareness, and operational learnings from prior sessions. Session finish runs drift detection (scope compliance, file budget, boundary violations), feature tracing, and writes a closeout memento.

Spec-to-gates traceability

# .exo/requirements.yaml
requirements:
  - id: REQ-AUTH-01
    title: "User authentication"
    acceptance:
      - ACC-AUTH-LOGIN     # User can log in with email/password
      - ACC-AUTH-LOCKOUT   # Account locks after 5 failed attempts

# tests/test_auth.py
# @acc: ACC-AUTH-LOGIN
def test_login_with_valid_credentials():
    ...

exo trace-reqs --check-tests  # verifies every acceptance criteria has a test

Requirements declare acceptance criteria. Tests annotate which criteria they verify with @acc: comments (language-agnostic). trace-reqs --check-tests cross-references the manifest against test annotations — untested criteria and orphan annotations are flagged as errors. The spec becomes the gate.

Agent handoff

# Agent A hands off to Agent B
EXO_ACTOR=agent:claude-opus exo session-handoff \
  --to agent:claude-sonnet --ticket-id TICKET-001 \
  --summary "Built API endpoints" --next-step "Write tests"

# Agent B starts — handoff context auto-injected into bootstrap
EXO_ACTOR=agent:claude-sonnet exo session-start --ticket-id TICKET-001 ...

Claude Code hooks

exo hook-install --all   # session lifecycle + enforcement + git pre-commit

Installs all six hook types:

• SessionStart/SessionEnd — auto-start/finish governed sessions with bootstrap injection
• PreToolUse (Bash) — gate git commit/git push on exo check
• PreToolUse (Write|Edit) — block writes outside ticket scope (real enforcement, not advisory)
• PostToolUse (Write|Edit) — auto-format Python files + budget tracking with warnings
• Notification — audit trail logging to .exo/audit/notifications.jsonl
• Stop — session hygiene warning before agent stops
• Git pre-commit — runs exo check before every commit

Parallel instances get unique actor IDs via CLAUDE_ENV_FILE, so multiple Claude Code windows can work on different tickets without session clashes. Auto-branch creates exo/<ticket-id> branches on session-start.

Agent adapters

exo adapter-generate                    # all targets
exo adapter-generate --target codex     # OpenAI Codex
exo adapter-generate --target claude    # CLAUDE.md
exo adapter-generate --target ci        # GitHub Actions workflow

Generates governance-aware config for Claude Code (CLAUDE.md), Cursor (.cursorrules), AGENTS.md, OpenAI Codex (codex.md), and CI (.github/workflows/exo-governance.yml). All adapters reflect the current governance state — deny patterns, budgets, checks, lifecycle commands, and active intent provenance with scope boundaries.

SDK integrations

# OpenAI Agents SDK
from exo.integrations.openai_agents import ExoRunHooks
hooks = ExoRunHooks(repo=".", ticket_id="TKT-...", actor="agent:openai")
result = await Runner.run(agent, hooks=hooks)

pip install exoprotocol[openai-agents]  # OpenAI Agents SDK
pip install exoprotocol[claude]         # Claude Code hooks (auto-installed)

What session-start does

When an agent session starts, ExoProtocol:

1. Compiles governance rules from the repo constitution
2. Loads the ticket's scope, budget, and constraints
3. Scans for sibling sessions and warns about scope conflicts
4. Checks for unmerged work on other branches that overlaps your scope
5. Injects operational learnings from prior sessions
6. Produces a bootstrap prompt that the agent sees first

The agent works within these boundaries. At session-finish, drift detection scores how well the work stayed in scope.

Architecture

CLI / MCP  →  Orchestrator  →  Stdlib  →  Control  →  Kernel (frozen, 10 functions)

The kernel is intentionally small and frozen — governance compilation, ticket locks, audit log, rule checks. Everything else (session lifecycle, drift detection, feature tracing, dispatch, GC) lives in the stdlib. See docs/architecture.md.

MCP server

pip install exoprotocol[mcp]
exo-mcp

{
  "mcpServers": {
    "exo": {
      "command": "exo-mcp",
      "args": [],
      "env": { "EXO_ACTOR": "agent:claude" }
    }
  }
}

Works with Claude Code, Cursor, and any MCP-compatible client. Every CLI command has a matching MCP tool.

Documentation

Guides (for humans)

• Getting Started — install, init, connect your agents
• Workflow Patterns — solo, multi-agent, code review, CI
• FAQ — common questions and quick fixes

Agent Reference

• Agent Quickstart — zero to first governed session
• Session Lifecycle — state machine, bootstrap anatomy, handoff, audit mode
• Governance Rules — rule types, budgets, scope, traceability
• Config Reference — complete .exo/config.yaml schema
• Error Reference — every ExoError code with resolution steps
• MCP Tool Reference — all 70 MCP tool signatures

Shared

• CLI Reference — all commands at a glance
• Architecture — layer model, key concepts, module map
• exoprotocol.dev — project site

License

MIT License. See LICENSE.