@compass-ai/nova

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.
/attach	Attach files to the session.
/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