Neon Pilot Documentation

Neon Pilot is a durable AI agent runtime with a desktop app, background automation, and knowledge management. It wraps an LLM with persistent state, tools, and async workflows.

Quick start

Download the latest macOS app from GitHub Releases, or let an agent install and bootstrap the packaged app:

curl -fsSL https://raw.githubusercontent.com/patleeman/neon-pilot/master/install.sh | bash -s -- --install-cli --bootstrap

After install, open Neon Pilot.app and create a conversation. If you installed the CLI, verify the runtime with:

neon-pilot bootstrap doctor

See Getting Started for the user setup flow, or Development workflow for building from source.

Start here

Pick the shortest path for what you are doing:

Audience	First docs to read	Success check
New user	Getting Started, then Views and Conversations	App opens, provider is configured, and a first conversation gets a reply.
Power user organizing context	Conversation context, Knowledge base sync, Projects	Useful files, folders, notes, and project records are available to conversations.
External agent or script author	Agent bootstrap, Neon Pilot CLI, CLI reference	`neon-pilot bootstrap doctor` passes and reports usable provider setup.
Extension builder	Build an extension with your agent, then Extension authoring	The extension installs, its route/action works through the app, and its build passes.
Repo contributor	Development workflow, then the owning package or extension README	Focused validation passes and the app can still start when touched code affects startup.
Release operator	Release cycle, Release QA, Release test inventory	Release doctor, hardening tests, and hands-on smoke notes are complete.

Common Tasks

Install and verify Neon Pilot — use Getting Started, then run the first conversation.
Give the agent useful context — use Conversation context for files, folders, images, drawings, and generated context.
Keep work organized — use Conversations, Projects, and Knowledge base sync.
Let work continue later — use Conversations for follow-ups/deferred resumes and Daemon for background runtime behavior.
Install more capabilities — use Extension distribution and the first-party optional extension repo.
Build a custom capability — start with Build an extension with your agent.

Reference

Agent bootstrap — packaged install, CLI setup, provider configuration, and external-agent verification
Projects — project records and workspace metadata
Configuration — file-based config and settings stores
Neon Pilot CLI — local control plane; extensions add administration commands with contributes.cliCommands
CLI reference — generated command contract reference for automation and scripts
Telemetry — local JSONL telemetry logs, SQLite observability indexes, exports, and runtime producers
Activity tree — shared model for conversations, executions, and future sidebar sub-items
Performance diagnostics — renderer timing tripwires for conversation load and API latency
SQLite migrations — shared versioned schema migration framework
Release QA — required release gate and hands-on smoke checklist
Release test inventory — broad release-risk checklist
Feature inventory — user-perspective feature list for QA planning and coverage mapping

The public website docs are built from the page list in apps/site/build-docs.mjs. Update that list when a repo doc should appear on neonpilot.net; keep this README as the human and agent map for the source tree.

Builder and Architecture Docs

Build an extension with your agent — agent-first guide for asking Neon Pilot to create, build, reload, validate, and test native extensions
Extension authoring — native extension manifests, frontend/backend entries, tools, skills, agent hooks, event bus, notifications, stable SDK imports, and integration testing
Extension API types — SDK package with exported types for frontend and backend code
Extension templates — copy-paste stubs for data-dashboard, crud-page, and settings-section patterns
Design system — shared UI package, Storybook, and extension-friendly component guidance
Neon Pilot taste — mandatory UI taste and control-selection guidance for app and extension work
Extension visual refinement — screenshot-backed iteration loop for generated extension UI
Design examples — positive and negative visual anchors
Development workflow — validation, UI QA, checkpoints, and secret scanning
Client workflow tests — frontend workflow coverage matrix for chat, sidebar, extensions, settings, geometry, and recovery paths
Desktop API Boundary — HTTP data plane, WebSocket realtime plane, and native-only IPC policy
Daemon — background process and runtime lifecycle
Sandboxing — shared process execution launcher, wrapper extensions, and direct process API policy
Filesystem Authority — shared scoped filesystem boundary, backend seam, policy hooks, and command-sandbox root grants
Renderer isolation — process ownership, critical lanes, and transcript projection boundaries
Product runtime and extension host split — architecture and validation for the product/extension process boundary
System extensions — feature-owned docs and implementation packages
First-party optional extensions — optional packages distributed from GitHub release artifacts

Extension docs

Neon Pilot product features live in extensions. The normal way to create one is to ask your agent to build it; start with Build an extension with your agent. Agents should use this README as the map: read the owning extension's README.md before changing feature behavior, and read Extension authoring plus Extension API types before changing extension APIs.

System extensions are bundled under extensions/system-*. Optional first-party extensions live in patleeman/neon-pilot-extensions, are not bundled or auto-loaded, and become normal user extensions only after installation into <state-root>/extensions/{extension-id}. Users install released optional extensions from Settings → Extensions → Install; after installing, check the main extension registry to enable and inspect the extension.

Feature-specific documentation lives beside the owning extension package.

Bundled system extensions:

Artifacts — rendered artifacts beside the active conversation
Automations — scheduled and conversation-bound automations
Background Work — background commands and subagents linked to conversations
Caffeinate — macOS caffeinate top-bar control
Codex Profile — Codex/OpenAI tool profile, including apply_patch and image generation
Composer Attachments — composer attachment controls
Context Hardening — tool-output bounds before agent context
Context Usage — composer status for context-window usage
Conversation Tools — conversation inspection, titles, working directories, and CLI commands
Diffs — checkpoint and workspace diff inspection
Dynamic Workflows — model-authored workflow coordinators that fan out daemon-backed subagents
Excalidraw Input — composer drawing input
Agent Plugins — Codex and Claude plugin import, update tracking, and compatibility reports
Extension Manager — extension registry, validation, import/export, and diagnostics
File Explorer — workspace file browsing
Git Status — branch and diff status in the composer
Goal Mode — persisted goal tracking and automatic continuation
Host view components — host-owned UI components reusable by extensions
Image Probe — image attachment inspection with a vision agent
Local Dictation — Whisper.cpp dictation controls and settings
MCP — configured MCP server inspection, auth, and calls
AI Gateway — opt-in local Responses API proxy for external coding agents
Model Picker — composer model and thinking controls
Neon Pilot CLI — unified CLI control plane for internal agents and external callers
Onboarding — first-run guided tour over real app pages
Prompt Assembly — prompt inputs, capabilities, and diagnostics inspection
Reply Actions — transcript selection actions and draft starters
Scratchpad — conversation-scoped markdown scratchpad
Settings — native first-party settings routes
Skills — backend compatibility actions for agent skills
Telemetry extension — app traces, model usage, tool health, and performance
Terminal — PTY-backed terminal panel
Todos — conversation-scoped execution todos
Web Fetch — web content fetch tool

Optional first-party extensions from patleeman/neon-pilot-extensions:

Agent Browser — agent-browser CLI integration
Auto Router — judge-based model routing controls
Browser — Workbench browser views and browser automation
DuckDuckGo Search — web search using DuckDuckGo's HTML page
Dynamic Workflows — workflow coordinators that fan out daemon-backed subagents
DS4 — local DeepSeek V4 Flash provider/profile for antirez/ds4
Exa Search — Exa web search
Knowledge — knowledge base browsing, editing, references, and sync
Suggested Context — related conversation suggestions
Video Probe — video analysis via local or remote video-capable models
Writing Studio — document-first collaborative writing surface

Docs maintenance checklist

When behavior, setup, or workflow changes, update the docs in the same change:

Update the smallest owning doc first, then this README only if navigation changes.
Keep first-run docs accurate: install path, provider setup, first task verification, and recovery hints.
Update the owning extension README before changing extension behavior.
Add public website coverage by updating apps/site/build-docs.mjs only when a repo doc should appear on neonpilot.net.
Prefer user-facing terms from CONTEXT.md; keep implementation details in architecture docs, not onboarding docs.
For docs-only edits, run formatting checks rather than the full product suite unless examples or generated references changed.

Source Docs Scope

Treat root docs, docs/, extensions/*/README.md, packages/*/README.md, and benchmark docs as source documentation. Ignore generated or packaged copies under dist/, packages/*/dist/, app bundles, and other build outputs during docs audits unless the task is specifically about packaged resources.

Edit this page on GitHub →