Content
# Pantheon
Pantheon is one local dashboard for AI coding agents, with one shared project brain.
It is a local-first control plane for terminal-based coding agents such as Hermes, Claude Code, Codex-style CLIs, Gemini CLI, Aider, and future non-MCP agents. Pantheon stores workspaces, tasks, memories, logs, and indexed project context locally. It does not require a new AI API key.
## Current Status
Pantheon is an open-source local orchestration build. It runs without a hosted service or provider API key; installed coding agents remain optional integrations.
Implemented:
- FastAPI backend bound to `127.0.0.1` by default.
- React/Vite/TypeScript dashboard.
- SQLite storage through SQLAlchemy.
- Hermes, Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode, and OpenClaw detection adapters.
- Connected MCP agents, including Codex desktop, OpenCode, OpenClaw, and generic MCP clients.
- Mock local agents that work even when no external agents are installed.
- Local subprocess terminal backend, so tmux and WSL are not required.
- Optional tmux backend for users who prefer tmux on Linux.
- Durable agent runtime sessions with lifecycle states, heartbeat checks, recovery reconciliation, persistent bounded logs, and audit events.
- Agent role/capability profiles and optional per-workspace authority hierarchies. Flat mode is the default: every agent reports directly to the Pantheon Orchestrator.
- Live agent connection registry with heartbeat, task claiming, progress, delegation, and completion through MCP.
- Workspace creation, task queueing, task dependencies, task decomposition, task runs, approval gates, cancellation/failure/retry status, memory CRUD/search, file indexing, and activity logs.
- WebSocket terminal log streaming.
- Operational dashboard for agent status, orchestration queue/timeline, approvals, runtime logs, audit events, RAG search, graph memory, setup checks, backup/export, and workspace health.
- MCP server exposing shared context, task, memory, workspace, and agent-status tools.
- Watchdog-backed workspace monitoring with a polling fallback.
- Local context ingestion, chunking, embedding-job records, SQLite keyword retrieval with citations, and an optional vector backend extension point.
- Graph memory with deterministic entity extraction, node deduplication, memory/entity edges, and graph traversal search.
- Safety layer with command policy checks, workspace boundary checks, secret redaction, and structured audit records.
- Local metadata backup/export.
Not included in the local v1 release:
- User authentication and multi-user access control (Pantheon remains localhost-only).
- Cloud sync.
- Multi-machine networking.
- Agent marketplace.
- Cloud/team orchestration.
- Auth, roles, and remote server deployment.
- A required cloud or vector service. The baseline stays dependency-free.
- Rich visual graph canvas. Current graph browser is operational/list-based.
- Persistent terminal sessions across backend restarts when using the default process backend.
## Quick Start
The launcher bootstraps a local virtual environment and starts the bundled dashboard:
```powershell
cd D:\projects\pantheon
.\start.cmd
```
Open:
- Dashboard and API: `http://127.0.0.1:8765`
The launchers serve the built dashboard from `frontend/dist`, start the FastAPI backend, and use the default local process backend. Pantheon does not require WSL or tmux. Built-in mock agents are available for onboarding; real agents remain optional integrations installed by the user.
## Fresh Setup
For a fresh clone (the launcher is the recommended path):
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cd frontend
npm install
npm run build
cd ..
./start.sh
```
On Windows PowerShell:
```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
cd frontend
npm install
npm run build
cd ..
.\start.cmd
```
## Development
Backend:
```bash
cd backend
PYTHONPATH=. pytest
uvicorn app.main:app --host 127.0.0.1 --port 8765
```
Frontend:
```bash
cd frontend
npm run dev
npm run build
```
Smoke check:
```bash
PYTHONPATH="$PWD/backend" python scripts/check_api_flow.py
```
## Architecture
- `backend/app/agents`: adapter interface and Hermes, Claude Code, and mock CLI adapters.
- `backend/app/terminal`: local process backend plus optional tmux backend.
- `backend/app/runtime`: durable agent session, task-run, log, recovery, and setup-check service.
- `backend/app/orchestration`: task decomposition, dependencies, approvals, assignment policy, stuck-run detection, and timeline.
- `backend/app/context`: RAG ingestion/search and graph memory.
- `backend/app/safety`: command policy, workspace boundary checks, secret redaction, and audit events.
- `backend/app/backup`: local metadata export.
- `backend/app/database`: SQLite initialization and SQLAlchemy models.
- `backend/app/workspaces`: workspace path validation, file indexing, and monitoring.
- `backend/app/memory`: shared local memory CRUD and keyword search.
- `backend/app/mcp_server`: MCP server and tool functions.
- `backend/app/main.py`: FastAPI REST API and WebSocket log stream.
- `frontend/src`: dashboard UI.
- `scripts/run_local.py`: local launcher used by `start.ps1`.
## API Overview
- `GET /health`
- `POST /agents/detect`
- `GET /agents`
- `GET /agents/connections`
- `POST /agents/connections`
- `POST /agents/connections/heartbeat`
- `POST /agents/connections/disconnect`
- `POST /agents/{agent_id}/start`
- `POST /agents/{agent_id}/stop?workspace_id=...`
- `GET /agents/{agent_id}/status?workspace_id=...`
- `POST /agents/{agent_id}/message?workspace_id=...`
- `GET /agent-connections/{connection_id}/tasks`
- `POST /agent-connections/{connection_id}/tasks/{run_id}/claim`
- `POST /agent-connections/{connection_id}/runs/{run_id}/progress`
- `GET /agents/{agent_id}/logs?workspace_id=...`
- `WS /ws/agents/{agent_id}/logs?workspace_id=...`
- `POST /workspaces`
- `GET /workspaces`
- `POST /workspaces/{workspace_id}/index`
- `POST /tasks`
- `GET /tasks`
- `PATCH /tasks/{task_id}`
- `POST /tasks/{task_id}/queue`
- `POST /tasks/dispatch`
- `POST /tasks/{task_id}/retry`
- `GET /task-runs`
- `PATCH /task-runs/{run_id}`
- `POST /orchestration/decompose`
- `POST /orchestration/dependencies`
- `GET /orchestration/timeline`
- `POST /orchestration/stuck`
- `GET /approvals`
- `POST /approvals/{gate_id}`
- `POST /memories`
- `GET /memories`
- `GET /memories/search?q=...`
- `PATCH /memories/{memory_id}`
- `DELETE /memories/{memory_id}`
- `GET /runtime/sessions`
- `POST /runtime/recover`
- `GET /runtime/logs?q=...`
- `GET /audit`
- `GET /setup/status`
- `GET /workspaces/{workspace_id}/agent-graph`
- `PATCH /workspaces/{workspace_id}/agent-graph`
- `PUT /workspaces/{workspace_id}/agents/{agent_id}/parent`
- `POST /context/documents`
- `GET /context/retrieve?workspace_id=...&q=...`
- `GET /context/graph/{workspace_id}`
- `GET /context/graph/{workspace_id}/search?q=...`
- `POST /backup/export`
- `GET /mcp` (MCP transport information; current SDKs expose the mounted MCP endpoint)
## MCP Setup Examples
Do not overwrite real agent configuration automatically. Add a block like this manually after reviewing paths.
Codex desktop, OpenCode, OpenClaw, and other MCP clients can connect to Pantheon through the local MCP endpoint. The setup page shows the exact URL and a generated configuration for the selected client.
Stdio example:
```json
{
"mcpServers": {
"pantheon": {
"command": "/path/to/pantheon/.venv/bin/python",
"args": ["-m", "app.mcp_server.server"],
"env": {
"PYTHONPATH": "/path/to/pantheon/backend",
"PANTHEON_DATABASE_URL": "sqlite:////path/to/pantheon/data/pantheon.db"
}
}
}
}
```
For Codex desktop, add the local Pantheon server in MCP settings and restart the client. Connected clients call `connect_agent`, `heartbeat_agent`, `list_available_tasks`, `claim_task`, `report_task_progress`, and `complete_run`.
OpenCode supports a local MCP entry in `opencode.jsonc`:
```json
{
"mcp": {
"pantheon": {
"type": "local",
"command": ["python", "-m", "app.mcp_server.server"],
"environment": {"PYTHONPATH": "/path/to/pantheon/backend"}
}
}
}
```
OpenClaw can register the same local server through its MCP configuration or expose its own gateway with `openclaw mcp serve` for Pantheon’s gateway connection mode.
## Configuration
Pantheon reads environment variables with the `PANTHEON_` prefix:
- `PANTHEON_HOST`
- `PANTHEON_PORT`
- `PANTHEON_DATABASE_URL`
- `PANTHEON_DATA_DIR`
- `PANTHEON_MANAGED_WORKSPACE_ROOT`
- `PANTHEON_TERMINAL_BACKEND`
Use `PANTHEON_TERMINAL_BACKEND=process` for the default no-tmux mode. Use `tmux` only if tmux is installed and you want tmux-managed sessions.
## GitHub Notes
Do not commit local runtime folders or installed dependencies. The included `.gitignore` excludes:
- `.test-python/`
- `.venv/`
- `frontend/node_modules/`
- SQLite databases
- logs
- `.env`
- caches
## License
MIT
