Nova

From intent to implementation. Right in your terminal.

The flagship Compass AI agent for understanding, building, and verifying real software.

Get started · Why Nova · Workflows · Documentation · Compass

Nova brings repository understanding, implementation, specialist agents, and verification into one terminal workflow. Give it an outcome: trace a regression, deliver a feature, review a risky change, or turn project knowledge into a presentation. Nova can inspect the evidence, use your tools, and carry the work through to a checked result.

Your repository. Your model choice. Your approval boundaries. Built for unfamiliar codebases, long-running sessions, and work that needs more than a plausible answer.

Proprietary software, built for real work. The licence permits personal use and internal business use of official distributions, including commercial development. It does not claim ownership of your inputs, projects, or generated outputs. Hosted services and model access may require separate subscriptions or credentials.

Get started

Install with Node.js 22.13.0 or newer and npm. Official platform packages cover Windows x64, macOS arm64/x64, and Linux arm64/x64.

npm install -g @compass-ai/nova
nova setup
nova

Run nova from the repository you want to work on. Setup guides you through authentication, provider access, consent, and local preferences. The compass command remains available as an alias.

Try a first task:

Explain how this project starts, identify its main components, and show me
which tests cover its most important behaviour. Do not change any files.

Dictate a prompt (interactive terminal)

Install a microphone recorder on PATH before enabling voice: winget install ffmpeg on Windows, brew install ffmpeg on macOS, or your distribution's ffmpeg package on Linux. Linux can also use pw-record or arecord when available. Restart the terminal after installation if its PATH has not updated. Then log in to Compass and run /voice on inside Nova. /voice status shows the active recorder; /voice off disables dictation for this session.

The first use asks you to acknowledge that audio is sent to Compass for OpenAI Whisper transcription using your organisation's configured key. Nova deletes the temporary local WAV after capture, never submits the resulting text automatically, and remembers your acknowledgement (not the on/off setting) in user-global configuration. Your organisation must have an OpenAI key configured. Voice input is unavailable in print mode, piped sessions, SDK/ACP, daemon, and AG-UI clients.

Tap Ctrl+Space or Alt+V to start recording; tap again to stop and insert the transcript at the cursor. Esc cancels a recording. If an agent turn is in progress, the transcript is queued until the prompt is ready; Esc discards queued text. Review the draft and press Enter yourself. Some terminals intercept Ctrl+Space; use Alt+V instead (macOS Terminal/iTerm2 may require Option as Meta). In config.json, voice.keybindings can choose either or both bindings. Silent or very short clips are discarded without upload. Recording stops after 120 seconds; transcription is not live.

Dictation uses the session's response language, or English before the first substantive request. To dictate in a different language, use /voice language pt-PT; /voice language default restores the session language. voice.windowsDevice, voice.linuxInput, and voice.silenceThresholdDb are optional user-global recorder/silence preferences. No recorder is downloaded by v1.

Why Nova

| What matters | What Nova brings | | --- | --- | | Understand before editing | Repository search, targeted symbol reads, dependency inspection, and source references. Local JS/TS language-server support adds definitions, references, inferred types, and diagnostics. | | Do the work, not just describe it | File edits, shell commands, Git operations, implementation plans, and verification with your project's own tests and checks. | | Bring in the right specialist | Delegate focused exploration, research, planning, verification, or implementation to agents with scoped tools and execution budgets. | | Keep long tasks moving | Resume conversations, recall archived sessions, retain project memory, and compact context instead of rebuilding the brief from scratch. | | Protect work in progress | Inspect diffs and use managed Git worktrees to separate new work from an existing working tree. | | Choose how you connect | Compass-managed models, direct provider credentials, supported OpenAI OAuth flows, and custom endpoints. | | Make execution visible | Follow local runtime events in the live dashboard, inspect token usage and cost estimates, and diagnose setup issues with nova doctor. | | Go beyond code | Built-in skills for frontend design, PowerPoint, and spreadsheets; discover additional skills and connect external tools through MCP. |

One workflow, from investigation to verification

Understand → Plan when needed → Implement → Verify → Review

Nova can trace the relevant code, turn complex changes into approval-gated plans, make scoped edits, and run the checks that matter. Specialist agents can provide a separate verification pass. You review the evidence and decide when to commit or publish.

Simple requests do not need a planning ceremony. Complex requests do not need to lose their context halfway through.

Put Nova to work

Start with the outcome you need. Connected services and specialist workflows depend on your configuration and access.

| Your goal | Ask Nova | | --- | --- | | Fix a regression | “Find why checkout fails after the latest auth change. Reproduce it, fix the cause, and run the relevant tests.” | | Deliver a feature | “Add CSV export using the existing permissions model. Inspect the current flow first and verify the change.” | | Make a safe migration | “Plan the database migration, identify compatibility risks, and wait for approval before implementing.” | | Get a second review | “Use a verification agent to review this diff for regressions and security issues without editing files.” | | Understand a codebase | “Trace this request from the CLI entry point to the provider call, with source references.” | | Communicate the result | “Create a PowerPoint release briefing from these notes, covering user impact, risks, and rollout.” | | Analyse a workbook | “Inspect this spreadsheet, explain the anomalies, and produce a formatted summary workbook.” |

Pick up where you left off

nova --continue

Use nova session to browse archived sessions. In a conversation, /context shows context usage and /compact helps recover space during long-running work.

Isolate a change

nova --worktree

Start in a managed Git worktree and use nova worktrees to inspect or manage it. Merging or discarding isolated work is a separate action, not a side effect of starting a session.

To compile and try the Nova CLI from that worktree, open a separate PowerShell terminal and run:

Set-Location -LiteralPath '<worktree path shown by nova worktrees>'
npm ci
npm run build
npm start

npm start runs that worktree's compiled dist/cli.js, not an installed nova command. After editing source files, stop the running CLI, rebuild with npm run build, and start it again with npm start. The build writes to dist in the worktree, leaving the original checkout's build alone.

Use Nova in scripts

nova --print "Summarise the staged diff. Do not modify files or create a commit."
nova --model gpt-5.6-luna --print "Inspect this workspace and suggest the next step."

Print mode runs a single non-interactive query and writes only the completed final answer to stdout. SDK streaming callbacks and the legacy accumulated content result remain available to embedded clients; finalText contains the completed answer. Failed runs do not print partial answers.

For a self-contained writing task, opt into a single text completion. Supply the full source material in the prompt; this path does not read the repository, load conversation history, or expose tools. A concrete model is required.

nova --completion --model gpt-5.6-luna --system 'Return only a conventional commit message.' --max-tokens 120 --print 'Describe this supplied diff: ...'

Embedded clients can call runSDKCompletion({ prompt, model, system, maxTokens, abortSignal }). The result contains text, token usage, cost, stop reason, and preparation/provider/total timings. The CLI writes only the completed text to stdout. --completion rejects session, agent, attachment, and tool options; --system and --max-tokens apply only to completion mode. Existing SDK hosts may pass --unleash; completion mode accepts it for compatibility and ignores it because this path has no tools or approval flow.

--model <model> selects a model ID or alias for the print invocation while retaining Nova's normal system prompt. It overrides agent and resumed-session model preferences without changing the saved default. Backend routing and failover still apply; --model auto requests automatic routing.

nova --print 'Return only JSON describing this project. Do not modify files.' --validate-json --progress

--validate-json validates the entire final answer before emitting stdout; invalid or empty JSON fails with a nonzero exit and a stderr diagnostic. It does not force the model to generate JSON, remove Markdown fences, or validate a schema. --progress adds labelled status updates to stderr. --reasoning-summary adds only explicit provider-supported public summaries to stderr (currently OpenAI Responses); unavailable summaries produce no output, and raw thinking is never substituted. Tool diagnostics are silent by default; --tool-output compact or --tool-output verbose enables them on stderr. Print output also removes provider reasoning prefixes marked with <think>, <thinking>, or <reasoning>, including a missing opening tag when a closing tag identifies the prefix.

For integration clients, nova tools-rpc exposes an internal JSON-RPC stdio tool server; use nova tools-rpc --help for its explicit tool allowlist options. Interactive plan-lifecycle tools are not available in print mode.

In interactive terminals, use /tag backend to name a peer session, then ask another session: Ask @backend about progress. Type @ to select a live peer; full IDs, unique eight-character ID prefixes, and quoted names such as @"Backend API" also work. A resolved mention turns on peer messaging for the current session until /peers refuse or exit. Unknown or ambiguous mentions show an error. @ no longer autocompletes or implicitly includes files; use ordinary paths or explicit attachments instead.

Your models, your integrations

Use Compass-managed access or configure a supported direct provider. Register custom endpoints with nova models register; supported wire schemas include Anthropic, OpenAI Chat, and OpenAI Responses. Model availability, usage limits, billing, and feature support depend on your provider and account.

Extend the workflow through documented interfaces, without modifying Nova's implementation:

• Skills: Built-in PowerPoint, spreadsheet, frontend-design, and skill-discovery workflows. Additional skills can be installed for your work.
• MCP: Connect configured servers for external tools and resources through nova mcp.
• Forge: Create reusable project tools, validate a sibling test, and approve them before loading through MCP. Forge ships with supported obfuscated JS npm distributions; see the Forge creation, installation, and usage guide, including explicit user-global copies and revocation.
• Custom commands and hooks: Package repeatable prompts and project-specific lifecycle behaviour.
• Scheduled tasks: Run recurring workflows through an active interactive scheduler or configured daemon. See scheduling behaviour and requirements.

Make a workflow repeatable

Create .nova/commands/review.md in your project, using .compass/commands/review.md instead if that legacy directory is active:

---
description: Review the current diff
---

Review the current diff for correctness, regressions, and missing tests.
Read the surrounding code. Report actionable findings with file references.
Do not modify files, stage changes, or create a commit.

Then run /review inside Nova. Personal commands belong in the active ~/.nova/commands or ~/.compass/commands directory.

Visibility without leaving your workflow

Enable live events before starting a session. In PowerShell:

$env:NOVA_OBSERVABILITY = "1"
nova

In another terminal, from the same project:

nova dashboard

Nova opens the local live dashboard and prints its address, continuity-view address, and event-file location. Use nova doctor for diagnostic health checks; repairs are separate, confirmation-gated actions.

| Command | Purpose | | --- | --- | | nova setup / nova init | Configure access and preferences / initialise project configuration. | | nova session / nova --continue | Browse archived sessions / resume the most recent conversation. | | nova models / nova openai | Manage custom models / OpenAI authentication and usage flows. | | nova mcp / nova lsp | Manage MCP connections / local JS/TS code intelligence. | | nova worktrees | Inspect and manage Nova-created worktrees. | | nova commit | Generate and create a conventional commit from staged changes. | | nova doctor / nova dashboard | Diagnose configuration / open local live observability. | | nova tokens / nova logs | Inspect token usage / system event logs. | | nova data / nova consent | Manage local data export and deletion / consent settings. | | nova update | Check for and install updates. | | nova --help | Discover CLI commands and options. |

Inside a session: /help, /model, /plan, /agents, /mcp, /context, /compact, /tokens, /usage, /ask, /export, and /exit.

Nova loads project instructions from AGENTS.md, falling back to NOVA.md when AGENTS.md is absent. The same selection applies independently in the active project and global state directories (.nova or legacy .compass). If both files exist in one location, only AGENTS.md is loaded, even if empty; merging or deleting NOVA.md is up to you. Personal NOVA.local.md and state-directory rules/*.md continue to load as before. Automatic discovery covers these locations, not nested subdirectories.

Control, privacy, and responsible use

Nova runs locally, but local execution does not mean all data stays on your machine: prompts, selected code context, and tool content may be sent to your configured model providers or connected services. Choose integrations and consent settings appropriate to your data.

• Policy-governed actions: Tool execution is subject to runtime policy, approvals, and hooks. Approval behaviour depends on your configured mode; review permissions before enabling automation.
• Separation where it matters: Managed worktrees and supported file-edit backups help preserve and recover work. Review diffs and verification results before shipping.
• Continuity under your control: Local configuration, memories, and session state use Nova's active state directories. Data export, deletion, and consent controls are available through the CLI.
• Defensive security focus: Nova's default security instructions support defensive analysis and remediation, not malicious activity or credential harvesting.

New installations use .nova; existing .compass directories remain supported. Upgrading does not automatically rename or merge them. See state-directory compatibility and manual migration.

Help and documentation

Start with nova doctor for setup problems, nova setup to reconfigure access, and /help for in-session guidance. Use nova --debug when investigating a problem, and review logs for sensitive content before sharing them. To remove the npm package, run npm uninstall -g @compass-ai/nova; review local-state retention separately.

Documentation index · Built-in tool reference · Repository guidance · npm package · Compass

Licence

Nova is proprietary software, not open source. Public availability on npm does not change its licensing terms. The Nova Proprietary Software License is authoritative; this is a summary:

• Permitted: Install and run official distributions for personal and internal business use, including commercial development. Necessary installation and backup copies must preserve legal notices. Documented configuration, extension, and integration interfaces are allowed.
• Restricted: Except with prior written permission or as permitted by applicable law, you may not redistribute, resell, sublicense, modify, create derivative works, extract or reuse Nova's implementation, reverse engineer it, defeat obfuscation, offer it as a hosted or managed service to third parties, or remove proprietary notices.
• Your work: The licence does not claim ownership of your inputs, projects, or generated outputs, or restrict their use merely because you used Nova. Third-party rights and separate service terms still apply.
• Separate rights and services: Third-party components retain their own licences; rights already granted for earlier releases under different licences remain intact. Paid or hosted service access is not included. Separate written agreements take precedence where they conflict.

For permissions beyond the licence, contact the publisher through Compass.

Date: 2026-06-24 · Last modified: 2026-09-15

Co-authored by Nova