Nova

Date: 2026-06-24

Nova is the flagship Compass AI agent for planning, editing, verifying, and shipping software from your terminal.

Built for real repositories, long-running sessions, guarded execution, dirty worktrees, and teams that need more than a chat box pasted beside an editor.

Recent releases added a local live observability dashboard and nova doctor health checks with safe repair flows.

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

You can also launch the same CLI with:

compass

Why Nova

Nova is designed for production software work, not demo prompts.

| Capability | What it means | | --- | --- | | Agentic delivery | Ask for outcomes: investigate, plan, edit, test, review, commit. | | Deep repository context | Nova searches, reads, and reasons across project files before changing them. | | Guarded execution | File, shell, git, database, and external actions run through explicit safety rules. | | Multi-model support | Use Compass-managed models, provider keys, OAuth flows, or registered custom endpoints. | | Extensible workflows | Add custom slash commands, MCP servers, skills, agents, hooks, and scheduled tasks. | | Git-native operation | Work with diffs, branches, commits, worktrees, dirty-tree isolation, and PR-ready summaries. |

What you can ask Nova to do

❯ Find why checkout fails after the latest auth change
❯ Plan a safe migration from Express middleware to Fastify hooks
❯ Implement the plan and verify it with tests
❯ Review this diff for regressions and security issues
❯ Create a conventional commit for the staged changes
❯ Spawn a verification agent to check the fix without editing files

Nova can write code, refactor modules, explain systems, run tests, inspect logs, generate documentation, manage git state, and coordinate multi-step implementation plans.

Install

Requirements

• Node.js >= 22.12.0
• npm
• A Compass account or API credentials for your chosen model provider

Global install

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

The setup flow configures authentication, consent, provider access, and local preferences.

Start a session

cd your-project
nova

Run one non-interactive query for scripts or CI-style usage:

nova --print "summarize the staged diff"

Advanced scripted tool workflows can use Nova's internal JSON-RPC stdio server:

nova tools-rpc --stdio --allow-tool read_file

tools-rpc is for automation clients, not normal interactive use. It keeps JSON-RPC messages on stdin/stdout and sends diagnostics to stderr.

Core capabilities

Plan, build, verify

Nova can break complex work into implementation plans, execute each step, and verify the result with the project's own tooling. It treats passing tests, lint, type checks, and observable behavior as completion criteria, not vibes.

Codebase understanding

Nova uses file search, code search, dependency analysis, and targeted reading to understand unfamiliar projects before it edits. It can trace flows, identify call sites, compare patterns, and explain architecture with source references.

Safe tool use

Nova can read and edit files, run shell commands, inspect git state, query saved database connections, manage worktrees, analyze dependencies, and call MCP tools where configured. Risky operations are gated; destructive or externally visible actions require confirmation.

Agents and skills

Nova includes specialized agents for exploration, verification, planning, and implementation. Skills package repeatable workflows such as frontend design, PowerPoint generation, Azure and CloudFoundry operations, and project-specific todo management.

Model flexibility

Nova supports Compass-managed models, Anthropic-compatible providers, OpenAI chat and responses flows, OpenAI OAuth where available, and custom model endpoints through nova models.

Worktree isolation

When a repository already has uncommitted work, Nova can use managed git worktrees so new requests do not trample user changes. Finish merges the isolated work back; cancel discards only the managed worktree when explicitly requested.

MCP and custom workflows

Connect external tools through Model Context Protocol servers, define project or personal slash commands, and add hooks that run on lifecycle events. Team workflows live close to the code instead of rotting in someone's notes.

Command surface

CLI commands

| Command | Purpose | | --- | --- | | nova | Start the interactive agent session. | | nova setup | Configure auth, provider keys, consent, and repair flows. | | nova init | Create project-local Compass configuration. | | nova commit | Generate and create a conventional commit from staged changes. | | nova models | Register, list, and remove custom model endpoints. | | nova session [id] [--limit n] [--offset n] | List or resume archived sessions for the current project. | | nova doctor | Run diagnostic health checks and optional safe repairs. | | nova dashboard | Start the local live observability dashboard. | | nova mcp | Manage MCP servers and authentication. | | nova openai | Manage OpenAI login, status, and usage flows. | | nova worktrees | Inspect and manage Nova-created worktrees. | | nova tokens | Inspect token usage. | | nova data | Export or inspect local user data. | | nova cache | Clear project and global cache data. | | nova logs | Inspect JSONL system event logs. | | nova tools-rpc | Start the internal JSON-RPC stdio server for scripted tool workflows. | | nova reset | Reset configuration and local state. | | nova update | Check for and install updates. |

In-session commands

| Command | Purpose | | --- | --- | | /help | Show available commands. | | /model | Switch models. | | /plan | Create or manage an implementation plan. | | /commit | Generate a commit from staged changes. | | /agents | Switch or inspect specialized agents. | | /mcp | Manage MCP tooling. | | /tokens | View token usage. | | /cost | View estimated cost. | | /context | Inspect context usage. | | /compact | Summarize long sessions to recover context. | | /export | Export the conversation. | | /undo | Revert supported file edits. | | /ask | Ask a side question without polluting the main thread. | | /exit | Leave Nova. |

Custom slash commands

Project commands live in .compass/commands. Personal commands live in ~/.compass/commands.

mkdir -p .compass/commands
echo "Review this code for performance and correctness issues:" > .compass/commands/review.md

Use arguments, file references, command output, and frontmatter to define repeatable workflows.

---
description: Fix a tracked issue
argument-hint: [issue-number]
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`

Fix issue #$1 and verify the change.

Run it inside Nova:

/fix-issue 123

Configuration

Nova resolves configuration in this order:

1. Built-in defaults
2. Global config at ~/.compass/config.json
3. Project config at ./.compass/config.json
4. Environment variables
5. CLI flags

Common environment variables:

COMPASS_MODEL=sonnet
COMPASS_DEBUG=true
COMPASS_VERBOSE=true
NO_COLOR=1
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Privacy and safety

Nova is built around local control and explicit approvals.

• Credentials are stored securely instead of written into project files.
• User data, memories, sessions, commands, skills, and cache live under ~/.compass unless project-local config is used.
• File edits are backed up where supported.
• Destructive commands, external side effects, and shared-state operations are gated.
• Dirty repositories can be isolated through managed worktrees.
• GDPR-style export and deletion flows are available through nova data and consent commands.
• Nova only assists with defensive security work and refuses malicious security tasks.

Troubleshooting

Reconfigure auth

nova setup

Reset local state

nova reset --force

Enable debug logs

COMPASS_DEBUG=true nova

Cloud-synced folders

Nova detects OneDrive, iCloud, Dropbox, and similar folders. It avoids hydrating placeholder files during bulk searches and disables indexing inside cloud roots by default.

To override that behavior:

{ "cloudAware": { "allowIndexing": true } }

Use this carefully; indexing cloud placeholders can download a ton of files.

Uninstall

npm uninstall -g @compass-ai/nova

The uninstall flow can preserve or remove ~/.compass, which contains configuration, encrypted credentials, sessions, memories, commands, agents, skills, token usage, and cache data.

Links

• npm package
• Compass
• License

Co-authored by Nova