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

If you are new to Neon Pilot, read these first:

• Getting Started — install the packaged app and verify the runtime
• Desktop App — understand the Electron shell, shortcuts, and app chrome
• Views — learn Conversation and Workbench layouts
• Conversations — work with live threads, branching, follow-ups, and async follow-through
• Conversation context — attach files, folders, images, drawings, and generated context
• Knowledge base sync — set up git-backed durable knowledge
• Extension distribution — install optional extensions and understand extension repositories

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

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
• Development workflow — validation, UI QA, checkpoints, and secret scanning
• 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
• 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
• Extension Manager — extension registry, validation, import/export, and diagnostics
• File Explorer — workspace file browsing
• Telegram Gateway — Telegram chat connections
• 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; disabled by default while Codex Desktop custom-model picker fixes are pending upstream
• Model Picker — composer model and thinking controls
• Neon Pilot CLI — unified CLI control plane for internal agents and external callers
• OpenAI Desktop Plugin — Settings-managed installer for the external Codex/OpenAI Desktop neon-pilot plugin with a CLI skill and focused delegated-agent MCP bridge
• Onboarding — first-run onboarding bootstrap and conversation flow
• 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
• DS4 — local DeepSeek V4 Flash provider/profile for antirez/ds4
• Exa Search — Exa web search
• Hermes Agent — Hermes Agent API session interface
• Kitty Litter Mobile Pairing — mobile pairing bridge
• Local Models — MLX and GGUF model runtime management
• Self Preservation — process self-preservation guard
• Suggested Context — related conversation suggestions
• Video Probe — video analysis via local or remote video-capable models
• Writing Studio — document-first collaborative writing surface

Sections

View Modes — Conversation and Workbench views, plus conversation context attachments.

Core Product Model — conversations and projects. Core stays a small stable platform; product features should live in system or user extensions.

Desktop App — Electron shell and app-level behavior.

Background Runtime — daemon lifecycle and runtime operations.

Connectivity — runtime connectivity architecture.

Operations — development workflow, configuration file format, and release cycle.

Edit this page on GitHub →