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

pnpm install
pnpm run setup:hooks   # optional: enable the tracked pre-commit hook
pnpm run build
pnpm run desktop:start

The repo intentionally avoids a root postinstall; third-party build scripts are allowlisted in pnpm-workspace.yaml, and anything new shows up in pnpm ignored-builds.

See Getting Started for the full setup.

Start here

• Getting Started — install from source and verify the app
• Views — Conversation, Workbench layouts
• Conversation context — attach files, folders, and generated context
• Conversations — live threads, branching, async follow-through
• Projects — project records and workspace metadata
• Desktop App — Electron shell, shortcuts, and app chrome
• Desktop API Boundary — renderer IPC/local-api contract and HTTP edge policy
• Knowledge — vault, docs, skills, instruction files, and managed sync
• Knowledge base sync — git-backed knowledge base setup, local paths, and sync behavior
• Configuration — file-based config, env vars
• Development workflow — validation, UI QA, checkpoints, and secret scanning
• 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
• Activity tree — shared model for conversations, executions, and future sidebar sub-items
• Performance diagnostics — renderer timing tripwires for conversation load and API latency
• Telemetry — local JSONL telemetry logs, SQLite observability indexes, exports, and runtime producers
• Build an extension with your agent — agent-first guide for asking Neon Pilot to create, build, reload, validate, and test native extensions
• Extension templates — copy-paste stubs for data-dashboard, crud-page, and settings-section patterns
• Extension authoring — reference for 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
• System extensions — feature-owned docs and implementation packages
• Experimental extensions — rough user extensions that are not bundled with the app

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-*. Experimental extensions are bundled under experimental-extensions/extensions/*, are loaded by the registry, and should set defaultEnabled: false. User extensions live under <state-root>/extensions/{extension-id} by default and follow the same package contract.

Feature-specific documentation lives beside the owning extension package:

• ACP Protocol
• Artifacts
• Auto Mode
• Automations
• Browser
• Caffeinate
• Codex Profile
• Composer Attachments
• Clean-room Spec Generator
• Context Hardening
• Context Usage
• Conversation Tools
• Diffs
• DuckDuckGo Search
• Exa Search
• Excalidraw Input
• Extension Manager
• File Explorer
• Git Status
• Host view components
• Image Probe
• Images
• Kitty Litter Mobile Pairing
• Knowledge
• Local Dictation
• Local Models
• Loose Ends
• MCP
• Model Picker
• Onboarding — first-run onboarding bootstrap and conversation flow
• Prompt Assembly — prompt inputs, capabilities, and diagnostics inspection
• Reply Actions
• Runs
• Session Exchange
• Self Preservation
• Settings
• Skills
• SpeechMike
• Suggested Context
• Telegram Gateway
• Telemetry extension
• Video Probe
• Web Fetch

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 →