Quickstart Guide

This guide helps new developers and AI agents understand the Pilot codebase quickly.

First 5 Minutes

1. Understand what Pilot is

Pilot is a web-based AI platform (like ChatGPT or Claude Web) that:

• Provides a chat interface for AI coding assistance
• Manages workspaces where users interact with AI agents
• Integrates OpenChamber UI for the chat experience
• Runs AI agents via OpenCode CLI in isolated runtime instances

2. Read these files in order

3. Understand the directory structure

pilot/
├── @core/           # Foundational packages (lint, typescript, base, query, ui, ai)
├── @packages/       # Application packages (chamber-ui, frontend, backend, domain, shared)
├── @services/       # Deployable services (app, gateway, chamber, runtime, compute, sandbox)
├── @demos/          # Demo/POC applications
├── @plan/           # Planning, architecture, documentation
│   ├── ARCHITECTURE.md   # Long-term architecture
│   ├── STATE.md          # Current state
│   ├── QUICKSTART.md     # This file
│   ├── GLOSSARY.md       # Terms
│   ├── plans/            # Execution plans
│   ├── upstream/         # Upstream tracking (openchamber, opencode)
│   ├── contracts/        # API contracts
│   ├── flows/            # Flow diagrams
│   ├── product/          # Product documentation
│   ├── sync/             # Upstream sync workflow
│   ├── ideas/            # Ideas and analysis
│   └── notes/            # Session notes
└── NETWORK.yml      # Network configuration source of truth

Understanding the @plan/ Structure

Plans (@plan/plans/)

Execution plans follow a consistent structure:

2026-02-17 - 7 - Documentation System/
├── Plan.md       # Goals, success criteria, phases
├── Tasks.md      # Task breakdown with priorities
├── Progress.md   # Append-only progress log
├── Summary.md    # Final outcomes (when complete)
└── Review.md     # Retrospective (when complete)

Plan status meanings:

• Active - Currently being executed
• Complete - All tasks done, reviewed
• Superseded - Replaced by a newer plan

Architecture vs. Plans

• ARCHITECTURE.md is normative - the source of truth for how things should be
• Plans are execution artifacts - they implement architecture decisions
• If a plan conflicts with architecture, the architecture should be reviewed first

Local Development

Prerequisites

• Node.js >= 20
• pnpm (installed via corepack)
• Docker (for runtime service)

Quick Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Build in dependency order
pnpm build:core && pnpm build:packages && pnpm build:services

# Type check
pnpm test:type

# Lint
pnpm lint

# Run a specific service
pnpm --filter @pilot/app dev
pnpm --filter @pilot/gateway dev

Service Ports (from NETWORK.yml)

Key Concepts

The Runtime Flow

User → @pilot/app → @pilot/gateway → @pilot/runtime → OpenCode CLI
                         ↓
                   Resolves workspace
                   to runtime instance

Package vs. Service

• Package (@packages/*, @core/*): Reusable code, no deployment
• Service (@services/*): Deployable runtime, has ports/domains

Upstream Relationship

Pilot builds on two upstream projects:

We track upstream versions and divergence in @plan/upstream/.

Common Tasks

Adding a new feature

1. Check @plan/ARCHITECTURE.md for ownership boundaries
2. Determine which package/service owns the feature
3. If cross-cutting, consider creating a plan in @plan/plans/

Understanding a component

1. Find the component in the appropriate package
2. Check for // @pilot:divergence or // @pilot:note annotations
3. Reference @plan/upstream/openchamber/DIVERGENCE.md for context

Syncing with upstream

1. Read @plan/sync/openchamber/SYNC.md for the workflow
2. Check @plan/upstream/openchamber/DIVERGENCE.md for known divergences
3. Create a new manifest in @plan/sync/openchamber/manifests/

Getting Help

• Architecture questions: Check @plan/ARCHITECTURE.md
• Current state: Check @plan/STATE.md
• Terms unclear: Check @plan/GLOSSARY.md
• Specific package: Check the package's AGENTS.md or README.md