Prerequisites

Verify installation

nova --version
nova doctor          # validate config + connections
nova               # start the TUI

nova doctor runs six checks: configuration file, secrets, LLM provider connection, Tavily connection, file permissions, and the voice stack. It returns exit code 0 when everything passes.

Update Nova

nova update --check  # check without installing
nova update          # update the running installation

The TUI checks in the background at startup and hourly. Installation detection covers source checkout, uv-tool, git, and package installs. On Windows, uv-managed updates run in a separate detached process because nova.exe locks the package directory. Set NOVA_DISABLE_UPDATE_CHECK=1 to disable background checks.

Onboarding

First-run setup checks what you enter before saving it: an API key is tested against the provider, and an Ollama host must answer with a model installed. Keys go to the OS keychain. A typo shows up on the setup screen, not on your first prompt.

Entry point chain

Subcommands

Flags

Environment variables

Credential storage

Keys go to the OS keychain (via the keyring library) with a permission-restricted JSON fallback. The endpoint and project are paired with the key as non-secret metadata in Nova.config.json. Enumeration and deletion are supported, and secrets are never logged or interpolated into exception messages.

nova secrets set openai_api_key
nova secrets set anthropic_api_key
nova secrets list
nova secrets delete openai_api_key

get_provider_auth_status() resolves credential readiness into a ProviderAuthStatus with states: CONFIGURED, MISSING, NOT_REQUIRED, MANAGED, UNKNOWN.

Configuration modules

config/ holds 14 modules:

Key directories

Model providers

The model catalog draws from two sources: provider profile data (LangChain packages ship auto-generated _profiles.py listing every model with capability flags) for OpenAI, Anthropic, Google, and NVIDIA; and a live list for Ollama and OpenCode Go. The curated MODEL_PRESETS list is unioned into every result and ordered first.

Per-role model selection

/model covers four roles:

Any role left unset inherits the main agent's model. Reasoning effort changes without a restart via /effort low|medium|high|off.

The Textual TUI provides a scrollable transcript, multi-line input that grows with content (shift+enter for a newline), modal dialogs with entrance animations, keyboard shortcuts, condensed tool groups, syntax-highlighted diffs, click-to-copy, parallel session panes, a docked todo checklist, a status bar with shimmer animation, and pulsing borders on active elements.

Screens

Key bindings

Performance features

• status ticks repaint in place
• rendered Markdown cached per width
• static data stays out of checkpoints
• subagent graphs compile on first use
• skill listing cached across restarts
• garbage collection tuned to run while idle
• a watchdog logs any UI freeze over 1s

UI panels

Optional notes, workspace files, and activity panels are customizable via /ui patch with a JSON object, then /ui preview and /ui commit. Panel order follows the panels list. Layouts are saved per workspace under ~/.nova/ui/. /ui rollback restores the saved layout.

Command categories

Council system

/council <task> has several agents propose plans independently, critique each other anonymously, and vote. A judge picks the top 3 and nothing is implemented until you approve one. Past council runs are kept in .nova/council/.

Research swarm

/research fans a question out to 7 research personas: web researcher, fact checker, literature reviewer, market analyst, financial analyst, technical researcher, synthesizer.

Output formats

Exit codes

Runner behavior

headless/runner.py drives a single prompt through the UI-agnostic event stream (iterate_agent_events) to completion with no human present.

• prompt from headless_prompt, format from headless_output_format
• tool interrupts use evaluate_tool_actions unless --deny-tools
• a None verdict (ask the user) is converted to an approve
• question/plan interrupts resolve to the default response
• counts turns, accumulates text, tracks usage, enforces max-turns
• autosaves the run as a resumable session; never fails on a save error

Headless runs are the exception to the approval rule: --deny-tools rejects everything, so a pipeline fails closed instead of hanging on a prompt nobody is there to answer.

File operations

Shell & execution

Web & search

Code intelligence

Memory & knowledge

Agent & delegation

Async agents

Background tasks

Artifacts & plans

File recovery

UI & desktop

Tool search

Only core tools are bound to the model on every call. search_tools finds the rest on demand. Search covers every currently available tool, including core and already loaded tools, plus specialist subagents. Use a capability description, an exact name, a partial name, or a wildcard.

search_tools("playwright browser automation")
search_tools("*")            # browse the catalog

MCP tools (serena, playwright, cua-driver, etc.) are discovered by MCPMiddleware and attached to the main agent. They are granted to subagents selectively via MCP_TOOLS_BY_SUBAGENT.

In-process specialists

Their graphs are compiled on first use, so unused ones cost nothing at start-up.

Research swarm

Dispatched by /research; kept out of the everyday roster and loaded on demand.

Async background agents

12 graphs on a remote LangGraph server that Nova launches itself, on demand. No Docker needed. Async agents read, search, and report; the ones that write (documentation, tests, refactoring) do so unattended, so give them a self-contained task. Work that needs your approval along the way belongs with an in-process specialist, because approvals do not reach the server.

By default, Nova launches its own langgraph dev server on an ephemeral port (gated on the opt-in agents-server extra). Nothing is started at boot: the server comes up on the first start_async_task (a few seconds) and stops when Nova exits. A session that never delegates never pays for it. A server that will not come up leaves the session as it was (in-process subagents), never blocks it. Users can create async agents by setting async: true in an agent.md frontmatter.

Agent-to-agent mailbox

The orchestrator can message its subagents by name and read replies via the send_agent_message and read_agent_messages tools.

The three tiers

Durable store

A single sync SqliteStore at ~/.nova/store.db (with a stdlib-sqlite3 fallback), wrapped by a DualModeStore for both sync and async access. All Hermes namespaces live under the ("nova", ...) prefix.

AgentMemoryMiddleware

• loads memory into the system prompt at before_agent
• always injects agent.md, memories/INDEX.md, HABITS.md, learning overview
• per-turn retrieval: lexical overlap scoring, top-3 topic bodies
• hot-reloads memory files when they change on disk
• prompt-cache split: the retrieval block sits after the cache breakpoint

Memory tools

A skill is a playbook (SKILL.md) with YAML frontmatter (name, description required; version, tags optional) and a Markdown body with canonical sections: When to Use, Quick Reference, Procedure, Pitfalls, Verification. Optional supporting files, scripts, and even an executable skill.py entry point can ship alongside.

Skill loading

Skills are loaded from multiple sources in precedence order (later overrides earlier):

1. User skills

   ~/.nova/skills/

2. Shared global

   ~/.agents/skills/

3. Claude skills

   ~/.claude/skills/

4. Plugin skills

   ~/.nova/plugins/<name>/skills/

5. Project skills

   .agents/skills/, .nova/skills/, .claude/skills/

Caching uses a directory signature (name, mtime, size) per skill, so only changed directories are re-parsed. A disk cache at ~/.nova/cache/skill_index.json enables cross-process reuse.

Skill retrieval

Hybrid search fuses BM25 (exact terms) with static Model2Vec embeddings (paraphrases) by reciprocal rank. The embedding model is minishlab/potion-code-16M.

RefreshingSkillsMiddleware is tiered:

Also provides mid-session refresh when watched skill directories change.

Skill versioning

Every mutation snapshots the prior SKILL.md first: .history/<version>.md inside the skill dir, .history/manifest.json as the version log, skills-archive/ for soft-deleted skills, and origin.json for provenance. restore() rolls back to any version.

Skill management commands

nova skills list              # list all skills
nova skills create my-skill   # create a new skill
nova skills create my-skill --project  # project-specific skill
nova skills info web-research # view skill details
nova skills add owner/repo    # install from GitHub
nova skills remove <name>     # remove a skill
nova skills find <query>      # search for skills
nova skills update <name>     # update from source

nova skills add runs the official Skills CLI (npx --yes skills@latest add) with your arguments unchanged. It requires Node.js, npm/npx, and Git for repository sources.

Available presets

• playwright
• serena
• context7
• apify
• cua-driver
• brave-search
• memory
• postgres
• google-drive
• fetch
• time
• sqlite
• stripe
• everything
• sequential-thinking
• chrome-devtools
• firecrawl
• tavily
• exa
• perplexity

Perplexity requires an API key. Select it in /mcp to configure it.

Management

nova mcp add brave-search --preset brave-search
nova mcp add my-server --transport http --url https://example.com/mcp
nova mcp add my-server --transport stdio --command "python -m my_mcp_server"
nova mcp list
nova mcp remove my-server

MCPMiddleware is inserted dynamically when MCP servers are configured. It calls list_servers() on every model turn, so it is skipped entirely when there are no servers. Tools are eagerly discovered before building the agent graph.

Plugins are discovered via the nova.plugins entry point group and tracked in ~/.nova/plugins/manifest.json with an enabled list (read/written atomically).

Plugin capabilities

Middleware slots

Plugin management

/plugins                    # list plugins
/plugins enable my-plugin   # enable a plugin
/plugins disable my-plugin  # disable a plugin
/reload-plugins             # reload plugin registrations

The system is orchestrated by NovaLearningMiddleware (hermes/middleware.py), a thin orchestrator that delegates to four focused modules:

The review loop

Trigger logic (hermes/review.py, ReviewRunner.should_review()). A review fires when any of these hold (and a review wasn't just done):

• Failure burst: ≥ FAILURE_BURST (default 3) failed tool calls in the current window
• Substantive threshold: count ≥ REVIEW_THRESHOLD (default 10) AND the window contains real work
• Hard cap: count ≥ 2× threshold (so all-trivial windows can't defer forever)
• Clean win: real substantive work, zero failures, past the floor

OOB model invocation: the review runs as a separate, out-of-band model call — it is NEVER injected into the agent's task turn.

Content persistence: after the OOB review, the parsed content is applied:

Post-review actions: every review runs cleanup_legacy_skills_once() and maybe_create_from_review(); every 5th review runs maybe_refine_skills() (one high-failure skill per cycle); every 10th review runs maybe_curate(), ThresholdTuner.run_tuning_pass(), and PromptEvolutionEngine.maybe_auto_evolve().

What Hermes learns

1. User model

   User preferences, communication style, merged into agent.md.

2. Topic lessons

   Cross-session facts/lessons organized by topic.

3. Good habits

   Reusable practices that worked well, stored in HABITS.md.

4. Skills

   Episode-grounded skills created from review <skill> blocks.

5. Prompt templates

   A/B-tested rewrites of system prompt templates.

6. Verification memory

   Per-repo failure patterns that make the inline verifier smarter.

Self-evolution engine

Fires at task completion:

1. Slice

   The task's episodic window.

2. Score

   Complexity via a deterministic heuristic (no LLM).

3. Invoke

   If complex enough (≥ 8), runs an OOB model call returning <skill> (new) or <level_up skill="name"> (improvement).

4. Debate

   New skills go through one adversarial critic round before freezing.

Loop engineering enhancements

Key design principles

• Never block the turn: all learning runs OOB or in background tasks.
• Fail-open: any learning failure logs and continues; never breaks the agent.
• Durable persistence: all learning state survives restarts via the LangGraph BaseStore.
• Bounded: every loop has hard caps (max retries, max lessons per review, etc.).

The loop

1. Task

   The user's request.

2. Understand

   Read the codebase, find the relevant code.

3. Plan

   Decide what to change.

4. Edit

   Write the code.

5. Test

   Run the tests.

6. Verify

   Grade the result. Fail? Back to plan.

When verification passes, the run is done, and the verdict and the diff that earned it are stored. When it fails, the failure comes back as feedback and the loop runs again, up to three attempts, then reports honestly instead of guessing.

Grader criteria

Five criteria scored by a separate model call:

• responded to the request
• wrote files
• no errors
• tests pass
• did not modify tests to pass

Turning it on

# Grade each finished run (costs one extra model call per turn)
/learning on

# Hold a specific piece of work to your own criteria
/goal rubric <what counts as done>

Off by default. The inline verifier lives in core/verification_loop.py and hermes/verifier.py. It is fail-open by design: a verification failure never breaks the run.

Security

• only allowlisted channel/chat IDs receive responses
• /remote allow <ID> manages the allowlist
• unauthorised messages are silently ignored (no acknowledgement leaked)

Lifecycle

/remote start discord --token TOKEN --channel ID
/remote start telegram --token TOKEN --chat ID
/remote stop               # gracefully shut down all bridges
/remote status             # show what is running

Voice notes (Telegram)

Telegram accepts voice notes: they are transcribed with the configured /voice STT provider and sent to the agent as an ordinary prompt. The transcript is echoed back so you can see what was heard. In a Telegram forum, each session gets its own topic, and a question Nova asks you is deleted from the chat once you answer it.

Cron / heartbeat scheduler

Proactive scheduled tasks via standard 5-field cron expressions. Fired jobs go on the same queue as remote bridges, so they run like any prompt. Manage with /cron.

nova cron add "0 9 * * *" "review open PRs"
nova cron list
nova cron remove <id>

Webhook ingress server

Let external systems (GitHub, Linear, or any signed sender) trigger a Nova run. Per-source HMAC-SHA256 secrets, timing-safe verification, binds to 127.0.0.1 by default. Manage with /webhook.

nova webhook add <name> --secret <secret>
nova webhook list
nova webhook remove <name>

Streaming

Response chunks are captured from the agent's output and sent back to the originating platform. For Discord, messages longer than 2,000 characters are split. For Telegram the limit is 4,096. Edit-in-place streaming creates a single "live" reply message and edits it in place on subsequent calls.

Providers

Voice modes

Two modes: push-to-talk (ctrl+g, press to start recording, release to stop) and hands-free (ctrl+l, always-listening with VAD). Code blocks are stripped before speaking. The speak tool speaks a short summary aloud.

Voice management

/voice test              # verify it works
/voice on/off            # toggle voice I/O
/voice mode ptt|listen   # switch mode
/voice settings tts orpheus   # switch TTS provider
/voice settings stt parakeet  # switch STT provider

Additional middleware

Appended after the base stack:

• RefreshingSkillsMiddleware — tiered listing + per-turn suggestions
• SkillCurationMiddleware — clamps loaded skills to the user-enabled set
• CodeInterpreterMiddleware — QuickJS eval bridge for dynamic subagent dispatch
• RepairToolCallsEachStep — repairs malformed tool-call history before every model call
• ToolSearchMiddleware — deferred loading of ~85 tools and ~90 subagents
• ModelRouterMiddleware — optional, off by default
• HardDenyMiddleware — enforces explicit denies even without HITL interrupt
• extra_middleware — caller-injected (e.g., Cowork's WorkspacePolicy broker)

SessionState composite

states/Session.py (741 lines) holds six focused state slices plus cross-cutting identity fields, using __getattr__/__setattr__ for dynamic field routing.

Session storage layout

Sessions live in ~/.nova/sessions/<session_id>/:

Four-tier persistence

1. Checkpointer

   LangGraph, SQLite-backed. Persists message history per thread_id. Primary conversation state.

2. Snapshot

   SessionManager's snapshot.json. The authoritative recovery generation, written atomically.

3. Store

   Durable key/value at ~/.nova/store.db. SqliteStore, then stdlib fallback, then in-memory.

4. Semantic files

   memory.md, workspace_state.json, ui_journal.jsonl, skills, worktrees, update cache.

Session lifecycle

• saves the incoming prompt before execution
• checkpoints active sessions every five seconds
• saves again when a turn ends
• resume with nova --continue or /sessions
• abrupt termination can lose progress since the last save

Save is serialized via a @serialized_save decorator to prevent concurrent autosave and final-save interleaving. Restoration validates project root, repo hash, and NOVA.md checksum, but never blocks on a mismatch.

Parallel sessions

Parallel sessions run as separate OS processes, each bound to its own git worktree. The child streams ui_events dataclasses to the parent as JSONL; the parent decodes them back and feeds the existing TUI renderer. Up to four run concurrently.

Session leases are durable, TTL-based, and cross-process (DEFAULT_TTL = 300s, DEFAULT_RENEW_INTERVAL = 60s). On a lease conflict, a turn runs unleased rather than blocking. Worktrees live under ~/.nova/worktrees/<repo-name>/<slug>, outside the repo.

1. Clear

   Older tool results are offloaded to /cleared/ so the agent can read them back.

2. Compact

   The conversation is summarized hierarchically via LLM.

3. Reserve

   A hard backstop always keeps an 8k-token reserve.

ContextManager

context/manager.py is a model-aware facade for all context-window operations:

Compaction

Compaction rewrites the whole conversation into one synthetic HumanMessage carrying the summary. The pre-compaction transcript is archived to ~/.nova/sessions/<thread>/.

System One compaction (experimental) asks Jev or a compatible local/custom decision model whether each old tool result is still needed, and clears only results scored stale. Off by default. Configure through /model → Decisions to select Jev, Tev1, or Custom System One.

Context meter

The TUI's CTX meter uses the latest main-model input usage when available and an estimated summary/tail breakdown after compaction or resume. SESSION accumulates main-model input and output across tool-loop calls against a configured token budget (1M by default).

Security middleware

security/middleware.py screens URL-bearing tool arguments for deception: hidden/invisible Unicode (BiDi overrides, zero-width chars, BOM), punycode domain spoofing (xn-- decoding), and mixed-script or confusable domain labels. Policy is warn and sanitize: invisible characters are stripped from the URL in place and the call proceeds; spoofing signals are surfaced as a notice but not blocked.

Human-in-the-loop

hitl/interrupts.py is a configurable interrupt system requiring user approval before destructive or external operations. 11 tool categories have schema-driven interrupt specs:

File recovery

Automatic snapshots are taken before destructive operations. Files targeted by rm are captured before deletion, files overwritten by write_file have their previous content saved, and files modified by edit_file have the pre-edit content saved. Snapshots live in ~/.nova/trash/<session-id>/. Files over 10 MB are skipped. Restore via /restore or the list_trash and restore_file tools.

Other safety layers

Sandbox flags

nova --sandbox os                    # OS sandbox (default on Linux/macOS)
nova --sandbox docker                # Docker container
nova --sandbox langsmith             # LangSmith microVMs
nova --no-sandbox                    # force unconfined local execution
nova --sandbox-id <id>               # reuse an existing sandbox
nova --sandbox docker --ports 8080:8080
nova --sandbox langsmith --sandbox-vcpus 2 --sandbox-mem-bytes 8589934592

The default sandbox image is python:3.11-slim. The sandbox factory (integrations/sandbox_factory.py) creates the appropriate backend based on the provider type, supporting workspace binding, setup scripts, and resource configuration.

Vixie desktop companion

vixie/ is a background server for desktop notifications and system tray integration: task completion and status alerts, quick access to Nova status, a WebSocket server for real-time event streaming, and state mapping (idle, thinking, working, success, error, user_input, planning).

Agent server launcher

The local langgraph dev server that hosts async agent graphs. It reserves a port but does not start at boot; the first start_async_task triggers ensure_started(). Health is confirmed by polling GET /ok and then the first graph. Stop is graceful (SIGTERM to the process group, Ctrl+Break on Windows) then force (SIGKILL / taskkill /T /F). A server that won't come up leaves the session exactly as it was.

Server, Cowork, and tracking

Hooks system

Lifecycle hooks can be Python scripts, shell commands, or any executable.

Global configuration (~/.nova/)

~/.nova/
  agents/default/
    agent.md          # user model + preferences
    memories/         # semantic memory tier
      INDEX.md
      <topic>.md
  skills/
    web-research/
      SKILL.md
  hooks/
    pre_tool_call.py
    post_tool_call.sh
  daemons/
    registry.json     # detached daemon registry
  plans/
    <project-slug>/   # global plan archive
  plugins/
    manifest.json     # plugin enable/disable manifest
  trash/
    <session-id>/     # file recovery snapshots
      manifest.json
  store.db            # durable LangGraph key/value store
  Nova.config.json    # persistent configuration
  logs/
    nova.log
  ui/
    <workspace>/       # saved UI layouts

Project configuration

my-project/
  .nova/
    NOVA.md               # project context and conventions
    config.json           # project configuration
    hooks.json            # project-specific hooks
    skills/               # project-specific skills
    wiki/                 # project wiki vault
      index.md
      log.md
      README.md
      Clippings/          # Obsidian Web Clipper inbox
      wiki/               # synthesized pages
    plans/                # approved plans
    council/              # past council runs
    project-graph.json    # project graph
  .claude/                # also supported (Claude Code compatible)
  .nova.config.json       # project-level config (scoped)

Extras

Common issues

nova doctor

Runs six checks and returns exit code 0 when all pass (1 on failures):

1. Configuration

   ~/.nova/config.json exists and is valid JSON with a provider set.

2. Secrets

   Lists configured secrets via the SecretManager.

3. LLM connection

   Ollama tests /api/tags and checks allocated context; cloud providers create a model instance.

4. Tavily

   Tests the search API if a key is configured.

5. Permissions

   Checks that secrets.json is not readable by others.

6. Voice stack

   Checks audio imports, PortAudio, and the default input device.

Diagnostics

nova doctor           # validate config + connections
nova --version       # check version
nova paths list      # check approved paths

Any UI freeze over one second is logged to ~/.nova/logs/freeze.log. The application log lives at ~/.nova/logs/nova.log.

Getting help

• run nova doctor
• check ~/.nova/logs/freeze.log
• open an issue on GitHub
• include nova --version output