Architecture

Architecture

Lantern combines three core functions into one Rust binary:

1. MCP Server

Exposes tools for agents to interact with the runtime:

• devorch_report_status — agent reports its status (ack, complete, blocked, failed, degraded, recovered)
• devorch_peer_message — agent sends a message to another agent role
• devorch_query_team_state — agent queries the state of all team members
• devorch_get_setup_instructions — agent fetches its initialization instructions

See MCP Tools for full specifications.

2. Local Runner (iTerm2 + Git)

• iTerm2 Integration: Creates a terminal window with a squad layout (9 panes by default in a 4×2+1 grid)
• Git Worktrees: Each squad member gets a dedicated worktree branching off the repo root
• Process Management: Launches agent CLIs in panes, monitors health, recovers from crashes

3. Runtime Authority

• SQLite Database: Local state store at ~/.lantern/data/relay/lantern.db — the single source of truth for squad state, agent health, session metadata
• Optional Temporal Integration: Local Temporal dev server at 127.0.0.1:8243 for workflow execution logging and diagnostics (not on the delivery path; Docker Temporal is unsupported)

Directory Structure

~/.lantern/
├── bin/
│   ├── lantern              # Main executable
│   └── temporal             # Temporal CLI (optional)
├── data/
│   ├── relay/
│   │   └── lantern.db       # SQLite state store
│   └── temporal/            # Temporal dev server data (optional)
├── logs/                    # Service logs
├── config/                  # Configuration (rarely used)
└── run/                     # Runtime state (pidfiles, sockets)

Design Principles

• Local-only: No cloud connectivity, no remote dependencies
• Stateless agents: Agents are ephemeral; state lives in SQLite
• Process isolation: Each agent gets its own terminal pane and git worktree
• Zero secrets: No API keys, tokens, or credentials required
• Transparent recovery: Automatic detection and recovery from agent failures