Code Tools Orchestrator

A persistent local control plane for coordinating multiple coding agents across multiple projects — without collisions.

Manage sessions with Claude Code, OpenAI Codex, GitHub Copilot, and (future) Cursor through a single daemon that handles lifecycle, git worktree isolation, artifact tracking, events, and cleanup.

Architecture

CLI ──────► FastAPI Daemon ◄────── Web UI
                 │
            Service Layer
                 │
         ┌───────┼───────┐
    Adapters  Worktrees  Runtime
   (Claude,   (git)     (processes)
    Codex,
    Copilot)

Daemon — FastAPI server, single source of truth (SQLite + SQLAlchemy)
CLI — Typer-based thin client that calls the daemon API
Web UI — React + TypeScript + Vite dashboard with live SSE event stream
Adapters — thin wrappers per agent (Claude, Codex, Copilot)
Worktree Manager — one git worktree per coding session, branch pattern orch/{agent}/{project}/{session_id}
Runtime Manager — subprocess lifecycle, PID tracking, failure detection

Quick Start

Prerequisites

Python 3.12+
Node.js 18+ (for the UI)
Git

1. Clone & install backend

git clone <repo-url> code-tools-orchestrator
cd code-tools-orchestrator

python -m venv venv
source venv/bin/activate
pip install -e .

2. Configure

cp backend/.env.example .env
# Edit .env if needed — defaults work out of the box

Variable	Purpose	Default
`DATABASE_URL`	SQLite database path	`sqlite:///./orchestrator.db`
`HOST`	Daemon bind address	`127.0.0.1`
`PORT`	Daemon bind port	`8000`
`LOG_LEVEL`	Logging level	`INFO`
`PROJECT_RUNTIME_DIRNAME`	Per-project runtime directory name	`.orchestrator`

3. Start everything

./start.sh

This single script starts both the backend and frontend, installs any missing dependencies, waits for the backend health check, and tears everything down on Ctrl+C.

Backend — http://127.0.0.1:8000/api/v1
Frontend — http://localhost:5173

Or start individually

# Backend only (from project root)
python -m backend.app.main

# Frontend only
cd frontend && npm install && npm run dev

Check health:

curl http://127.0.0.1:8000/api/v1/health

4. Run tests

# Backend (from project root)
python -m pytest backend/tests/ -v

# Frontend
cd frontend
npm test

CLI Reference

The CLI connects to the daemon at http://127.0.0.1:8000 by default. Override with ORCH_DAEMON_URL.

# Run the CLI (from project root)
python backend/cli.py <command>

Health

orch health

Check that the daemon is running and responsive.

Projects

# List all registered projects
orch projects list

# Register a project
orch projects add ~/projects/my-app
orch projects add ~/projects/my-app --name "My App" --default-branch main

Commands

Send a command to an agent. This creates a session, sets up a worktree (for coding actions), and starts the agent runtime.

orch send <agent> <action> <project_slug> [scope_path] [--model <model>]

Agents: claude, codex, copilot, cursor

Actions:

Action	Creates worktree?	Description
`analyze`	No	Analyze code without modifications
`review`	No	Review code without modifications
`implement`	Yes	Implement changes in an isolated worktree
`plan`	Yes	Create an implementation plan

Examples:

# Ask Codex to analyze a directory
orch send codex analyze my-app src/payments

# Ask Claude to implement a feature
orch send claude implement my-app "add error handling to the API"

# Ask Copilot to review code
orch send copilot review my-app src/auth

# Override the model used by the agent runtime
orch send copilot review my-app src/auth --model gpt-5.2
orch send claude analyze my-app --model sonnet/opus
orch send codex implement my-app "add caching" --model gpt-5.2-codex

Model selection

If --model is provided, the command is persisted with that model and the adapter receives it. If omitted, the adapter uses its default.

Sessions

# List all sessions
orch sessions list

# Show session details
orch sessions show <session_id>

Follow-up

Send additional instructions to a running or waiting session:

orch followup <session_id> "focus on error handling"

# or equivalently
orch sessions followup <session_id> "focus on error handling"

Stop

Stop a running session's agent process (keeps data):

orch stop <session_id>

Resume

Restart a stopped or failed session:

orch resume <session_id>

Delete

Permanently remove a session and all its resources (worktree, artifacts, logs, DB records):

orch delete <session_id>

# Also delete the git branch
orch delete <session_id> --delete-branch

REST API

All endpoints are served under the /api/v1 prefix at http://127.0.0.1:8000/api/v1.

Health

Method	Path	Description
`GET`	`/api/v1/health`	Service health check

Projects

Method	Path	Description
`GET`	`/api/v1/projects`	List projects
`POST`	`/api/v1/projects`	Register a project
`GET`	`/api/v1/projects/{id}`	Get project by ID
`GET`	`/api/v1/projects/slug/{slug}`	Get project by slug
`PUT`	`/api/v1/projects/{id}`	Update project

Commands

Method	Path	Description
`GET`	`/api/v1/commands`	List commands
`POST`	`/api/v1/commands`	Submit a natural-language command

Sessions

Method	Path	Description
`GET`	`/api/v1/sessions`	List sessions
`POST`	`/api/v1/sessions`	Create a session
`GET`	`/api/v1/sessions/{id}`	Get session details
`POST`	`/api/v1/sessions/{id}/followup`	Send follow-up instruction
`POST`	`/api/v1/sessions/{id}/stop`	Stop session
`POST`	`/api/v1/sessions/{id}/resume`	Resume session
`POST`	`/api/v1/sessions/{id}/archive`	Archive session
`POST`	`/api/v1/sessions/{id}/delete`	Delete session and resources
`GET`	`/api/v1/sessions/{id}/cleanup-preview`	Preview what deletion will remove
`GET`	`/api/v1/sessions/{id}/log-tail`	Get recent log output

Artifacts

Method	Path	Description
`GET`	`/api/v1/artifacts`	List artifacts (filterable by project/session)

Events

Method	Path	Description
`GET`	`/api/v1/events`	List persisted events
`GET`	`/api/v1/stream/events`	SSE live event stream

Session Lifecycle

Sessions move through a state machine:

created ──► running ──► completed ──► archived ──► deleted
                │              │
                ├──► failed ───┤
                │              │
                ├──► stopped ──┤
                │       │
                │       └──► running  (resume)
                │
                └──► waiting_for_user ──► running  (follow-up)

State	Description
`created`	Session initialized, worktree prepared
`running`	Agent process is active
`waiting_for_user`	Agent needs additional input
`completed`	Agent finished successfully
`failed`	Agent process crashed or errored
`stopped`	User stopped the session
`archived`	Hidden from active views, data preserved
`deleted`	All resources removed

Per-Project Runtime Layout

When a session is created for a project, runtime files are stored locally:

my-project/
  .orchestrator/
    worktrees/
      <session-id>/        # Isolated git worktree
    artifacts/
      <session-id>/        # Session outputs (plans, diffs, transcripts)
    logs/
      <session-id>.log     # Agent process log

Each coding session gets its own git worktree and branch (orch/{agent}/{project}/{session_id}), ensuring agents never modify the same working directory.

Web UI

The dashboard at http://localhost:5173 provides:

Dashboard — project count, active sessions, failures, command composer, live event stream
Projects — list and detail views with sessions and artifacts
Sessions — list, detail with log tail, artifacts, follow-up input, and action buttons
Events — live filterable SSE event stream

Project Structure

code-tools-orchestrator/
  backend/
    app/
      api/           # FastAPI route handlers
      adapters/      # Agent adapters (Claude, Codex, Copilot)
      core/          # Config, database
      models/        # SQLAlchemy models & enums
      schemas/       # Pydantic request/response schemas
      services/      # Business logic (session, command, event, cleanup, worktree, runtime)
    tests/           # pytest test suite
    alembic/         # Database migrations
    cli.py           # CLI entry point
  frontend/
    src/
      api/           # API client & React hooks
      pages/         # Dashboard, Projects, Sessions, Events
      components/    # Shared UI components
  docs/              # Architecture, design, and spec documents

Documentation

Detailed design docs are in docs/:

Document	Content
`architecture.md`	System components, data flow, layered architecture
`domain-model.md`	Entity review, enum design, indexes, API contracts
`session-lifecycle.md`	Full state machine, transitions, test cases
`command-system.md`	Command grammar, parsing, action semantics
`event-taxonomy.md`	33 event types, payload structures, SSE format
`worktree-safety.md`	Isolation rules, race condition avoidance
`runtime-manager.md`	Process lifecycle, restart behavior, error handling
`adapter-architecture.md`	Adapter contract, output normalization
`cleanup-system.md`	Delete vs archive, safety checks, workflow
`cli-usage.md`	CLI ergonomics, full usage examples
`ui-design.md`	Information architecture, page designs
`testing-strategy.md`	Lifecycle tests, transition tests, failure scenarios
`integration-validation.md`	End-to-end verification, concurrency validation

License

See LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
backend		backend
code_tools_orchestrator.egg-info		code_tools_orchestrator.egg-info
docs		docs
frontend		frontend
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

Code Tools Orchestrator

Architecture

Quick Start

Prerequisites

1. Clone & install backend

2. Configure

3. Start everything

Or start individually

4. Run tests

CLI Reference

Health

Projects

Commands

Model selection

Sessions

Follow-up

Stop

Resume

Archive

Delete

REST API

Health

Projects

Commands

Sessions

Artifacts

Events

Session Lifecycle

Per-Project Runtime Layout

Web UI

Project Structure

Documentation

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages