Agent runtime

Neon is a durable Flue assistant backed by local app state. The design keeps deterministic facts and mutations in services and typed tools while using the model for synthesis, triage, and next-step reasoning.

A normal conversation starts in a virtual scratch workspace rather than a mounted host checkout. Explicit Neondeck capabilities bridge that workspace to registered repos, local state, GitHub, connected services, and approved command execution. The workspace limits direct access; the capability supplied for a turn determines what effects are possible. See safety and sandboxes for the boundary of chat, schedules, watches, Autopilot, and PR review.

Flue agent

The display assistant owns addressable chat sessions. A new session deliberately reloads current SOUL, skills, model config, memory summaries, and repo context. Existing sessions are not silently rewritten when those inputs change.

Neondeck indexes session metadata, linked repo/watch/task context, compact summaries, stale-context badges, and audit records in app state. Cross-session references should use those summaries and metadata first; raw transcript page access remains explicit, audited, and owned by Flue.

Tools and services

Tools are schema-backed deterministic capabilities backed by shared app services. Neon uses them for config updates, repo facts, GitHub PR/check facts, runtime skill lookup, memory, dashboard presets, schedules, watches, and guarded execution. Dashboard, CLI, and local API surfaces call the same services. Config changes should go through typed tools or APIs, not freestyle file editing.

Agents and app-owned operations

Flue 2 has no workflow runtime. Neondeck keeps durable operation state in its own SQLite tables and dispatches purpose-bound agents only when model work is required. The mounted agents are:

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

Conversation, curation, and handled-PR learning reviews use keyed learning-review agent submissions. Neondeck persists the bounded evidence before dispatch, correlates the Flue submission with app-owned review state, and can recover interrupted admissions after restart.

Watched-PR Autopilot uses one continuing pr-autopilot-owner agent per PR rather than a chain of transition jobs. Every fixing turn runs in that PR's managed-worktree coding workspace; current mode and turn source add or withhold the separate push and PR-response tools. The manual /fix-ci command remains a separate app-owned operation that prepares a CI dossier and may start a bounded Kilo task.

That owner resolves the current display-assistant model and thinking level for each turn; models.prReview belongs to the separate fresh initial-review agent. Its full per-mode system prompt is editable in runtime config and applies on the next turn without replacing the owner conversation. The current watch state still constructs the actual tool registry outside the prompt.

Skills

Skills provide procedural knowledge and conventions. The built-in neondeck skill is app-owned. User runtime skills are trusted local extensions loaded from runtime-home skills/ and configured external skill roots.

Memory

Structured memory supports active user, local, and project scopes. Legacy session and watch rows may be read for compatibility, but new learning writes do not create them. Memory is current guidance for future sessions; archive history and audit events preserve what changed. See memory and learning for scopes, curation, and session-stability behavior.

Schedules and watches

The local scheduler claims and records each bounded occurrence in app state. PR watches are deterministic pollers that invoke agent reasoning only when there is meaningful state to summarize or act on.

Scheduled tasks cover PR watches, briefings, and bounded agent instructions. Their validated triggers are persisted locally, while Flue owns each admitted agent submission. A requested repo or working directory is task context, not a mounted shell workspace. General instructions can still use allowed typed capabilities, so scheduled work is not automatically read-only.

Reports and busywork

Busywork automation writes durable local reports under the runtime home and lists them through GET /api/reports and the Reports dashboard panel. /review-pr produces PR overview and findings reports plus local Neon-origin draft comments for a human reviewer. The reviewer receives bounded read-only Git tools for listing, searching, and reading the exact PR head and its merge-base diff. Repository files are not copied wholesale into the prompt, and a large generated-file patch no longer disables anchoring for unrelated files. A persistent reviewer conversation can inspect the same saved revision for follow-up questions without gaining mutation or GitHub-delivery authority. /fix-ci writes a CI failure dossier and, when a bounded Kilo run creates commits, returns through the prepared diff review loop. /explain-ci --report writes the dossier without attempting a fix.

The initial review and follow-up reviewer use separate, complete prompt templates in prReview.prompts. The initial model receives PR facts as a distinct untrusted JSON request and must return the server-owned structured review schema. Follow-up turns render the current saved review context and exact-workspace availability into the configured conversation template. Prompt overrides can replace all shipped guidance, but cannot add mutation tools or direct GitHub delivery authority.

Reports are local artifacts served from /reports/:id. Docs-drift reports can stage a docs fix into a managed worktree, but the result still lands as a prepared diff for human review.

Scheduled tasks

Scheduled tasks are validated local records with a typed spec and an interval, one-shot, or timezone-aware cron trigger. The scheduler claims each due occurrence before running an app service or dispatching a bounded agent submission; approval-gated tools remain approval-gated, and fresh scheduled-agent sessions cannot use the ordinary interactive commit or push path. Other typed mutations remain available when the task asks for them. An instruction deliberately targeted at an existing agent session inherits that session's interactive context instead of the default scheduled-session restriction. Morning briefings use a typed profile and a persistent, non-active briefing session so a background run never replaces the dashboard's active conversation. General instruction tasks can be paused, resumed, or deleted.

Briefing orchestration persists deterministic grounding separately from the Flue transcript, dispatches the user's selected display assistant model with its complete configured MCP catalog, and settles run metadata from Flue submission observations. Assistant prose is never an application schema. MCP login or approval failures produce a candid partial briefing rather than fabricated facts or automatic approval.

External agent handoff

Same-host agents and local hooks can hand work to Neon through the CLI or the localhost-only /api/handoff/* mirror. Handoff verbs are additive: they create attributed PR watches, notifications, release watches, and optionally admit a fresh bounded PR review agent when handoff.allowExternalReviewQueue allows it. They do not execute commands, approve work, push branches, submit GitHub reviews, or mutate provider settings.

neondeck register-pr owner/repo#123 --from codex --note "adds retry logic" --json

curl -sS -X POST http://127.0.0.1:3583/api/handoff/register-pr \
  -H 'content-type: application/json' \
  --data '{"source":"codex","ref":"owner/repo#123","note":"adds retry logic"}'

The repository ships an Agent Skills-compatible skills/neondeck-handoff/SKILL.md. Copy that skill folder into another agent's local skill root, such as ~/.claude/skills/, or reference it from repo-level agent guidance so those agents register PRs after pushes.

Observability

neondeck records Flue observations, failed submissions, app operation summaries, emitted progress data, tool activity, and notifications. Raw submission inspection can expose prompts and tool data, so dashboard summaries stay compact and guarded.