Pilot
Your AI crew, ready to fly.
Pilot is an open source, local-first AI CLI platform. The repo combines a React Ink terminal app, a plugin system, AI routing, machine setup tooling, and a GitHub-based release pipeline in one TypeScript monorepo.
Everything runs locally by default. Network services are used for publishing, distribution, security scanning, and optional product features, but the core CLI and local configuration stay on your machine.
Technical Entry Points
What Ships Today
packages/cli contains the main @medalsocial/pilot terminal applicationpackages/plugins/kit contains the bundled machine-management plugin- GitHub Actions handles CI, package releases, binary builds, security scans, and the landing-page worker deploy
workers/pilot-landing serves pilot.medalsocial.com and the install script- Changesets drives package versioning and changelog generation
How Pilot Is Built
| Layer | Technology | Why |
|---|
| Terminal UI | React Ink | React mental model for terminal screens and reusable UI primitives |
| Command routing | Commander.js | Stable CLI parsing and help generation |
| AI layer | Vercel AI SDK | Streaming, tool calling, provider abstraction |
| Plugins | plugin.toml + Zod validation | Declarative commands, MCP servers, and permission checks |
| Package build | TypeScript + tsup | Package compilation and local developer builds |
| Binary distribution | bun build --compile | Standalone executables attached to GitHub releases |
| Testing | Vitest + ink-testing-library + E2E | Component, command, repo-guardrail, and end-to-end coverage |
| Linting | Biome | Fast formatting and static checks |
| Versioning | Changesets | Controlled multi-package release flow |
| CI/CD | GitHub Actions | Quality gates, package publishing, security scans, deploys |
| Machine setup | Nix (abstracted in product UX) | Reproducible machine configuration without surfacing Nix to end users |
Monorepo Map
pilot/
├── packages/
│ ├── cli/ # @medalsocial/pilot
│ └── plugins/
│ └── kit/ # @medalsocial/kit
├── workers/pilot-landing/ # Landing page + install script worker
├── tests/ # Repo-level and e2e tests
├── docs/ # Architecture, workflows, security, and quality records
├── scripts/ # Build and install helpers
└── .github/workflows/ # CI, release, deploy, and agentic automations
For the full codebase walkthrough, see docs/ARCHITECTURE.md.
Release And Automation Flow
Pilot uses two workflow families:
- Deterministic GitHub Actions YAML workflows for CI, npm publishing, binary attachment, worker deploys, and security scans.
gh-aw agentic workflows written in Markdown and compiled to .lock.yml files for planning, PR triage, issue triage, changeset generation, and related automations.
The important operational detail is that package publishing and binary attachment are separate workflows:
release.yml publishes the npm package and creates the GitHub release/tag.build-binaries.yml runs after the release is published, compiles per-platform binaries, signs them, uploads the assets, and syncs the Homebrew tap.
That means a GitHub Release can exist before binary assets appear, and if the binary workflow fails the release can remain package-only until the workflow is rerun. The repo-level workflow inventory lives in docs/WORKFLOWS.md.
Local-First Model
- Knowledge base lives under
~/.pilot/
- Crew config is portable via
AGENTS.md and CLAUDE.md
- Telemetry is local-only
- Plugin permissions are declared in
plugin.toml and validated before load
Cloud connectivity remains optional. The CLI, local state, and configuration model do not depend on a hosted Pilot backend.
Quick Start
# Install
curl -fsSL pilot.medalsocial.com/install | sh
# Launch
pilot
Commands
| Command | What it does |
|---|
pilot | Launch the cockpit and chat with the crew |
pilot up <template> | Install a template, skills, and related setup steps |
pilot crew | Manage crew members, skills, and tools |
pilot training | Manage knowledge and brand context |
pilot plugins | Browse and manage plugins |
pilot update | Check for and apply updates |
pilot status | Show machine and system health |
pilot status --json | Emit machine-readable health data |
pilot usage | AI token usage and costs for this project |
pilot usage --week / --month / --since YYYYMMDD | Usage by time window |
pilot usage --json | Machine-readable JSON output |
pilot completions <shell> | Generate shell completions |
pilot help | Show command help |
status --json
Outputs machine-readable JSON for scripting and CI:
{
"pilot": "0.1.5",
"node": "v24.0.0",
"platform": "darwin",
"arch": "arm64"
}
| Field | Type | Description |
|---|
pilot | string | Installed Pilot version |
node | string | Node.js version with v prefix |
platform | string | OS platform (darwin, linux, win32) |
arch | string | CPU architecture (arm64, x64) |
Shell Completions
# Bash
pilot completions bash >> ~/.bashrc
# Zsh
pilot completions zsh >> ~/.zshrc
# Fish
pilot completions fish > ~/.config/fish/completions/pilot.fish
Contributor Quick Start
pnpm install
pnpm build
pnpm quality
pnpm quality:100
pnpm test
pnpm dev
Contributor guardrails:
- Use
pnpm only; other package managers are blocked
- Run
pnpm quality:100 before opening quality, workflow, package, or plugin changes
- Add a changeset for release-worthy changes unless the PR is explicitly internal-only
- Do not commit generated
dist/ or coverage/ output
- Review AI-assisted patches before merging and add tests for behavior changes
See CONTRIBUTING.md for the full contributor policy.
Operational References
Long-form design history and implementation plans are maintained outside this source repository. Use the following files as the current operational reference:
Feature Tracker
Status: Pre-release · Building v1
Core Platform
| Feature | Status | Spec |
|---|
| Monorepo + toolchain (Turbo, Biome, Husky) | Done | Plan |
| React Ink component library | Done | Plan |
| Commander.js CLI routing | Done | Plan |
| Design token system (from Pencil) | Done | Spec |
| Structured logging + error system | Planned | Plan |
| ErrorBoundary + crash recovery | Planned | Plan |
Onboarding & Setup
| Feature | Status | Spec |
|---|
| curl installer (single command) | Planned | Plan |
| Welcome screen + crew introduction | Done | Spec |
| Home screen (instruments dashboard) | Done | Plan |
| REPL routing (Welcome → Home) | Done | Plan |
| Machine detection + auto-config | Done | Spec |
| Update flow (check, progress, what's new) | Done | Plan |
| XDG Base Directory compliance | Planned | Plan |
AI & Crew
| Feature | Status | Spec |
|---|
| Vercel AI SDK integration (Claude) | Planned | Plan |
| 5 crew leads (Brand, Marketing, Tech, CS, Sales) | Planned | Spec |
| Auto-routing (natural language to right crew lead) | Planned | Plan |
| AI retry + timeout + offline resilience | Planned | Plan |
| AGENTS.md / CLAUDE.md generation | Planned | Plan |
Skill Deployment
| Feature | Status | Spec |
|---|
| ~/.pilot/skills/ structure | Planned | Spec |
| Symlink to ~/.claude/skills/pilot | Planned | Plan |
| CLAUDE.md routing injection | Planned | Plan |
| Smart updates (manifest checksums) | Planned | Plan |
| Tech Lead dev guide + AI best practices | Planned | Spec |
Plugin System
| Feature | Status | Spec |
|---|
| Plugin manifest (plugin.toml + Zod) | Done | Plan |
| Plugin registry (load, enable, disable, remove) | Done | Plan |
| Plugins screen (split panel browse + manage) | Done | Plan |
| Plugin sandboxing (permission enforcement) | Planned | Plan |
| Contribution guidelines | Planned | Plan |
Training & Knowledge
| Feature | Status | Spec |
|---|
| Training screen (split panel sources) | Done | Plan |
| Knowledge base (sources, articles, runs) | Planned | Spec |
| Bi-directional source sync | Planned | Spec |
| Config migration system | Planned | Plan |
Admin
| Feature | Status | Spec | Description |
|---|
| Admin Dashboard | In Progress | Spec | CLI command center with health strip, tabbed panels, SDK-powered data |
Machine Management (Kit)
| Feature | Status | Spec |
|---|
pilot kit init — bootstrap a fresh machine | Done | Spec |
pilot kit status — health checks (TTY + JSON) | Done | Spec |
pilot kit update — pull + rebuild with progress UI | Done | Spec |
pilot kit clean — scan and remove junk/dev caches | Done | Spec |
Kit readiness — KIT_CONFIG, completions guardrail, JSON error envelope | Done | Spec — Vault vault/open-source/pilot/specs/2026-05-09-pilot-kit-readiness-design.md |
pilot up (One-Click Setup)
| Feature | Status | Spec |
|---|
| Hosted registry (fetch, cache, SHA verify, offline fallback) | Done | Spec |
| Template manifest format (pkg/npm/mcp/skill steps, cross-platform) | Done | Spec |
pilot up <template> install flow with progress UI | Done | Spec |
pilot up browse UI (split-panel, categories) | Done | Spec |
pilot down <template> step-based uninstall | Done | Spec |
| Specialist crew wiring on install | Done | Spec |
Observability
| Feature | Status | Spec |
|---|
pilot usage — Claude Code + Codex token/cost report | Done | Spec |
MedalSocial SDK Integration
| Feature | Status | Spec |
|---|
| SDK mainstreaming design | Planned | Spec |
| PR1: Release pipeline | Planned | Plan |
| PR2: Pilot integration | Planned | Plan |
Distribution & Quality
| Feature | Status | Spec |
|---|
| tsup dual CJS/ESM build | Planned | Plan |
| Single binary via ncc | Planned | Plan |
| Changesets versioning + automation classifier | Done | Plan |
| GitHub Actions CI + release | Done | Plan |
| E2E test suite | Planned | Plan |
| Shell completions (bash, zsh, fish) + parity guardrail | Done | Spec — Vault vault/open-source/pilot/specs/2026-05-09-pilot-kit-readiness-design.md |
| NO_COLOR / FORCE_COLOR support | Done | Plan |
| Local-only telemetry | Planned | Spec |
| Themes (dark/light from design tokens) | Planned | Spec |
Contributing
See CONTRIBUTING.md for contributor workflow, testing rules, and review policy.
License
Apache-2.0
