Docs

neondeck is a local-first autonomous developer assistant designed to stay visible beside your work on a companion display, vertical panel, or sensor-panel style deck. The local app serves a React dashboard and Flue backend; 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.
  • Configuration: runtime-home files, models, providers, repos, SOUL, and skills.
  • CLI: command reference for setup, repo registry, watches, Neon slash commands, and future TUI entrypoints.
  • Agent runtime: Flue agents, actions, workflows, skills, memory, watches, reports, scheduled tasks, and observability.
  • Autopilot: watch a PR, choose a capability mode, review the continuing owner's work, and understand the safe-push and recovery boundaries.
  • MCP servers: remote and local MCP servers, OAuth login, approval policy, and Runtime Overview state.
  • Execution environments: sandboxes, the execution policy gate, exe.dev, and where work actually runs.
  • 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, Flue workflows, deterministic actions, local SQLite state, and a Vite/React dashboard. It is designed for everything from 32:9 ultrawides like the Corsair Xeneon Edge to custom layouts for the size and constraints you want. Dashboard layout is driven by runtime JSON config, measured panel size, and typed actions 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 pre-migration copies in data/backups/. data/flue.db stores Flue runtime state.

Project pieces

  • src/: Hono, Flue, SQLite persistence, sensors, and local APIs.
  • web/: Vite React dashboard for the companion display.
  • 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 invoked through the command-run Flue workflow. Deterministic results are persisted in workflow_summaries and exposed at /api/workflows/summaries. 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. The watched-PR Autopilot can notify, prepare a committed change for review, wait for approval in its continuing owner conversation, or push through its narrow safe-delivery path. Provider-specific deploy adapters are still a future integration.

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 PR review assistance, 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 artifacts are self-contained slide decks with a plain-language review brief first, bounded Markdown and links, keyboard navigation, print layouts, and the same typed document model in the standalone report and dashboard overlay. Scheduled tasks are durable local work managed through /api/scheduled-tasks and typed task actions.

Flue actions and workflows

Neon gets deterministic capabilities through schema-backed Flue actions for config, repo status, GitHub PR/check facts, runtime skills, dashboard layout presets, schedules, watches, commands, and local dev doctor checks. Bounded operations are also available as discovered Flue workflows: 

briefing
command-run
curate_learning_store
dev-doctor
fix-pr-ci
handoff_to_kilo
promote_kilo_result
reconcile_kilo_task
review-pr-for-human
review_conversation_for_learning
review_kilo_result
review_pr_batch_for_learning
scheduled-agent-instruction
scheduler-tick
summarize_kilo_session
verify_kilo_result
watch-pr

Watched-PR Autopilot is a continuing pr-autopilot-owner agent controlled through typed actions, not a workflow for every transition. The separate manual /fix-ci path remains available as the fix-pr-ci workflow.

Workflow observability

The dashboard includes a dedicated workflow observability panel for active Flue runs, failed runs, emitted progress data, and recent action/tool/operation activity. Rows show compact, redacted summaries by default. When a row has a guarded Flue run inspection URL, the panel exposes it through an explicit inspect link.

Developer commands

fnm use 26.4.0
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