Docs

neondeck is a local-first autonomous developer assistant that keeps pull requests moving. It surfaces the PRs you opened, watches the ones you put on Autopilot, works beside you while you review everyone else's, and briefs you on what needs attention. It runs on whatever screen you already have. A second monitor, a vertical panel, or a strip display like the Xeneon Edge all work, and none of them are required.

This Astro site documents the project and deploys separately to Cloudflare at neondeck.dev.

Start here

  • Getting started: install, initialize a runtime home, configure secrets, and launch the local dashboard.
  • Upgrading: update npm, release archive, or source installations while preserving runtime state.
  • Configuration: runtime-home files, models, providers, repos, SOUL, and skills.
  • CLI: command reference for setup, repo registry, watches, and Neon slash commands.
  • Agent runtime: Flue agents, tools, app operations, skills, memory, watches, reports, scheduled tasks, and observability.
  • Autopilot: watch a PR, choose a capability mode, review the continuing owner's work, and understand semantic autonomous judgment, mechanical delivery guards, and recovery.
  • MCP servers: remote and local MCP servers, OAuth login, approval policy, and Runtime Overview state.
  • Safety and sandboxes: how plain chat, scheduled work, PR watches, Autopilot, human review, host commands, and the experimental exe.dev command path use different trust boundaries.
  • Contributing: local dev loop, roadmap workflow, checks, reviews, and PR expectations.

Current runtime

The local app is a Node 26 Hono server with Flue agents and tools, app-owned deterministic services, local SQLite state, and a Vite/React dashboard. The dashboard fits the screen it is on, whether that is an ordinary monitor or a 32:9 ultrawide like the Corsair Xeneon Edge, and you can hand it a custom layout instead. Dashboard layout is driven by runtime JSON config, measured panel size, and typed tools Neon can use to adapt the surface. Local dashboard surfaces subscribe to one multiplexed /api/events stream whose named config, notification, session, and review events refresh affected panels without a browser reload.

Runtime home

neondeck resolves mutable local state in this order: NEONDECK_HOME, then XDG_CONFIG_HOME/neondeck, then ~/.config/neondeck. First run, or neondeck init, creates the runtime home. 

~/.config/neondeck/
  .env
  config.json
  mcp.json
  repos.json
  dashboard.json
  SOUL.md
  skills/
    custom-skill/
      SKILL.md
  data/
    backups/
    neondeck.db
    flue.db

data/neondeck.db stores Neondeck app state such as watches, jobs, notifications, memories, workflow summaries, and config history. App database migrations apply automatically from shipped migration files and retain the latest two recognized managed backups, including restore-safety snapshots, in data/backups/. Use neondeck db backup and neondeck db restore for explicit recovery. data/flue.db stores Flue runtime state.

Project pieces

  • src/: Hono, Flue, SQLite persistence, sensors, and local APIs.
  • web/: Vite React dashboard.
  • docs/: Astro marketing and docs site for neondeck.dev.
  • config/dashboard.json and config/dashboard.schema.json: default dashboard layout seed and JSON Schema copied into new runtime homes.
  • SOUL.md: default agent personality material copied into new runtime homes.

Neon commands

Slash commands can be typed into the chat panel, run from dashboard buttons, or chosen from the chat input's slash-command suggestions. Deterministic results are persisted in app-owned operation summaries and shown in the Activity panel. The chat surface special-cases /briefing as a normal assistant turn instead of a result card. 

/repo-status [repo-id]
/review-queue
/review-pr <repo#number|owner/repo#number|url>
/fix-ci [repo#number|owner/repo#number]
/explain-ci [--report] [repo#number|owner/repo#number]
/summarize-pr [repo#number|owner/repo#number]
/draft-pr-description [repo-id|owner/repo]
/prepare-pr [repo-id|owner/repo]
/review-local [repo-id|owner/repo]
/briefing
/reasoning [off|minimal|low|medium|high|xhigh]
/memory ...
/dev-doctor
/watch-pr <repo#number|owner/repo#number|url>

Watches and scheduler

PR watches persist in SQLite and survive restart. A /watch-pr watch polls GitHub for merge state, merge commit checks, review feedback, and quiet no-op refreshes. Provider-specific deploy adapters are still a future integration.

The watched-PR Autopilot can notify, prepare a committed change for review, wait for approval in its continuing owner conversation, or autonomously deliver when that owner judges the change sound and the narrow mechanical delivery guards pass. The owner currently uses the display-assistant model. Its complete per-mode prompt can be inspected, replaced, or reset from the Runtime panel, and changes apply on the next owner turn.

Scheduled tasks use validated interval, one-shot, or timezone-aware cron triggers. The typed briefing profile owns its cron schedule, timezone, enabled state, instructions, and persistent conversation; agent-instruction endpoints create other tasks that the local scheduler dispatches through Flue.

Conversational briefings

A briefing first persists a bounded deterministic snapshot of repos, review queue, watches, scheduler state, notifications, hygiene, and autopilot state. It then dispatches a normal turn to the configured display assistant model in a durable briefing session. The Flue transcript is the canonical response; Neondeck never parses the assistant prose into metrics or a second report.

Every enabled MCP tool configured for the display assistant remains available. Neon calls only sources relevant to the saved instructions, and normal login, approval, denial, and audit controls still apply. If local or MCP sources are unavailable, the assistant should identify the partial context and continue with the facts it has. Briefing turns are informational and do not mutate external systems.

Reports and scheduled tasks

Reports are local HTML artifacts for CI failure dossiers, docs drift, issue triage, and hygiene. The dashboard lists them in the Reports panel and serves individual artifacts from /reports/:id. PR review instead persists one briefing with a fixed recommendation overview and renders it with the live local draft queue in the dashboard or its standalone client route. Scheduled tasks are durable local work managed through /api/scheduled-tasks and typed task actions.

Flue agents and tools

Neon gets deterministic capabilities through schema-backed Flue tools for config, repo status, GitHub PR/check facts, runtime skills, dashboard layout presets, schedules, watches, commands, and local dev doctor checks. Product state and orchestration remain app-owned; Flue agents are dispatched only for model work: 

display-assistant
pr-review-assistant
pr-reviewer
learning-review
pr-autopilot-owner

Learning reviews use a keyed learning-review Flue agent. Their bounded evidence, submission identity, result, and audit trail remain in Neondeck's app-owned learning state so interrupted admission can be recovered.

Watched-PR Autopilot is a continuing pr-autopilot-owner agent controlled through typed tools, not a job for every transition. The separate manual /fix-ci path remains available as an explicit app-owned operation.

Activity and submission observability

The dashboard Activity panel combines compact app operation summaries, Flue submission observations, emitted progress data, and recent tool activity. Rows stay compact and redacted by default; raw prompts and tool payloads are not exposed through a legacy workflow-run inspector.

PR review submissions show model turns, exact-revision workspace calls, separate model and tool time, latest-turn token usage, returned evidence volume, and the Git operations the reviewer chose. If older events were pruned, the summary is explicitly marked partial. Expand an event to see typed metadata such as paths, line ranges, result counts, truncation, and remaining workspace budget. Source, patch, and literal search contents are deliberately excluded from retained activity records.

The reviewer receives a bounded read-only Git surface instead of a preselected changed-file manifest. It starts from the exact merge-base change index, then chooses among patches, targeted hunk evidence, raw head or base files, repository search, commit history, and blame. This keeps exploration revision-bound while allowing the model to gather the context appropriate to each change.

Developer commands

node --version
npm run setup
npm run dev
npm run check
npm run test:integration
npm run verify
npm run docs:astro-dev
npm run docs:build