Nova

Nova brings the power of advanced AI language models directly to your terminal. Write code, debug issues, refactor projects, and understand complex codebases using natural language — all without leaving your command line.

Part of the Compass Platform ecosystem — sync sessions across CLI, Desktop, and Web.

Why Nova?

• 💬 Natural Conversations - Describe what you want in plain English, Nova handles the implementation
• 🔍 Deep Code Understanding - Intelligent indexing and semantic search across your entire codebase
• 🔒 Safe by Default - Three-tier approval system ensures you're always in control of file changes
• ⚡ Blazingly Fast - Stream responses in real-time with state-of-the-art language models
• 🛠️ Built for Developers - Git integration, shell execution, session management, and more

Quick Start

Install

npm install -g @compass-ai/nova

Setup

nova setup

You'll be guided through API key configuration and consent management.

Start Using Nova

# In any project directory
nova

# Then ask Nova to help with anything:
❯ Help me refactor this authentication module to use JWT
❯ Find all the files that handle user permissions
❯ Create a git commit with a descriptive message for my changes
❯ Explain how the payment processing flow works

Key Features

AI-Powered Development

Nova leverages advanced language models to provide intelligent assistance for:

• Writing and refactoring code
• Debugging and fixing issues
• Explaining complex codebases
• Generating documentation
• Creating git commits and PRs

Smart Codebase Understanding

• File Indexing - Automatically indexes your project structure
• Semantic Search - Find relevant code using natural language
• Dependency Analysis - Understand relationships between files and modules
• Context-Aware - Nova maintains conversation history with 200K token context window

Safe File Operations

• Manual Mode (Default) - Review every change before it's applied
• Auto Mode - Safe operations approved automatically, risky ones require review
• Strict Mode - Maximum safety, all operations require explicit approval
• Automatic Backups - Changes are backed up before modification
• Undo Support - Roll back changes with /undo

Developer Workflow Integration

• Git Operations - Intelligent commits, PR descriptions, conflict resolution
• Shell Execution - Run commands with cross-platform support
• Session Management - Save, load, and export conversation history
• Token Tracking - Monitor usage and costs in real-time

Common Use Cases

# Code refactoring
❯ Refactor the user service to follow SOLID principles

# Debugging
❯ I'm getting a null pointer error in checkout.ts line 45, help me fix it

# Code understanding
❯ Explain how the authentication flow works in this codebase

# Documentation
❯ Generate JSDoc comments for all functions in src/utils/

# Git operations
❯ Create a commit for my changes with a descriptive message
❯ Help me write a PR description for this feature

# Quick commits with /commit
❯ /commit
→ Analyzes staged changes
→ Generates conventional commit message
→ Creates commit with one approval

# Testing
❯ Write unit tests for the payment processing module

Interactive Commands

During a session, use these slash commands:

| Command | Description | |---------|-------------| | /help | Show available commands | | /model [name] | Switch between models (e.g. /model opus, /model haiku) | | /commit | Generate conventional commits from staged changes | | /approve [mode] | Toggle approval modes (manual/auto/strict) | | /tokens | View token usage stats | | /cost | Display estimated API costs | | /context | Show context window usage | | /export | Export conversation as Markdown/JSON/HTML | | /compact | Summarize conversation to free context | | /index | Reindex project for semantic search | | /files | List tracked project files | | /agents | Switch to specialized agents | | /config | View/modify configuration | | /mcp | Manage Model Context Protocol servers | | /update | Check for and install Nova updates | | /personality | Change communication style | | /unleash | Toggle unguarded mode | | /wrap | Consolidate memory at end of session | | /purge | Clean up old backups and logs | | /attach | Attach a file to the conversation | | /paste | Paste clipboard content into conversation | | /ask | Sideband Q&A without affecting main context | | /logout | Log out of Compass platform | | /clear | Clear conversation history | | /exit | Exit Nova |

Custom Slash Commands

Define your own slash commands as Markdown files for frequently used prompts.

Creating Commands

Project commands (shared with team):

mkdir -p .compass/commands
echo "Analyze this code for performance issues:" > .compass/commands/optimize.md

Personal commands (available everywhere):

mkdir -p ~/.compass/commands
echo "Review this code for security issues:" > ~/.compass/commands/security.md

Features

• Arguments: Use $ARGUMENTS for all args, or $1, $2 for positional
• File references: Include files with @src/file.ts
• Bash execution: Run commands with !git status``
• Frontmatter: Configure with YAML metadata

Example Command

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

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

## Task
Fix issue #$1 following our coding standards.

Usage: /fix-issue 123

See Custom Commands Documentation for full details.

Agents & Skills

Nova includes specialized agents for different workflows:

| Agent | Purpose | |-------|---------| | Explorer | Fast codebase navigation, file search, and pattern matching | | Code Reviewer | Security, quality, and best practices analysis | | Debugger | Root cause analysis, error diagnosis, and fixes | | Planner | Architecture design and implementation planning with impact analysis |

Switch agents with /agents or create custom agents in agents.md:

---
name: security-audit
model: sonnet
approval-mode: strict
---
Focus on: OWASP Top 10, dependency vulnerabilities, secret detection

Learn more about the Skills ecosystem at agentskills.io.

Configuration

Nova uses a hierarchical configuration system:

1. Default values - Sensible built-in defaults
2. Global config - ~/.compass/config.json
3. Project config - ./.compass/config.json
4. Environment variables - Override any setting

Environment Variables

ANTHROPIC_API_KEY=your_api_key_here  # When using Anthropic models
COMPASS_MODEL=sonnet                  # Default model (see aliases above)
COMPASS_DEBUG=true                    # Enable debug logging
NO_COLOR=1                            # Disable colored output

Privacy & Security

Nova is designed with privacy and security as core principles:

• Local-First - All data stored on your machine
• Explicit Consent - Required before any data collection
• GDPR Compliant - Full data export and deletion capabilities
• Encrypted Credentials - API keys stored securely
• Automatic Expiration - Session data expires after 30 days

AI Model Support

Nova supports multiple AI models — switch anytime with /model:

| Model | Alias | Best For | |-------|-------|----------| | Claude Opus 4.7 | opus, o | Complex reasoning, architecture decisions, extended thinking | | Claude Sonnet 4.6 | sonnet, s | Balanced performance (default) | | Claude Opus 4.6 | opus-4.6 | Previous-gen complex reasoning | | Claude Sonnet 4.5 | sonnet-4.5 | Previous-gen balanced performance | | Claude Haiku 4.5 | haiku, h | Fast iterations, quick tasks | | Z.AI GLM 5.1 | glm-5.1, g | Cloud-hosted, open-source alternative | | Z.AI GLM 5 | glm-5 | Cloud-hosted, open-source | | MiniMax M2.7 | minimax-m2.7, m | Versatile cloud alternative | | Kimi K2.6 | kimi-k2.6, k | Deep reasoning alternative | | Gemini 3 Pro | gemini-3-pro, p | Creative cloud alternative | | DeepSeek V4 Pro | deepseek-v4-pro | High-context reasoning alternative | | GPT-5.5 | gpt-5.5 | Advanced OpenAI reasoning, vision, and structured output | | GPT-5.4 | gpt-5.4 | OpenAI reasoning, vision, and structured output |

All models support:

• 200K token context window
• Streaming responses
• Tool use

Requirements

• Node.js >= 18.0.0
• API key for your chosen AI provider (e.g., Anthropic)

Troubleshooting

API Key Issues

# Reconfigure your API key
nova setup

Reset to Defaults

nova reset --force

Enable Debug Mode

COMPASS_DEBUG=true nova

Slow performance in OneDrive / iCloud / Dropbox folders

Nova detects cloud-synced folders and automatically skips not-yet-downloaded placeholder files during bulk searches to avoid triggering mass hydration. The codebase indexer is disabled by default inside cloud roots. If you need to index anyway (at the cost of downloading every file), set in your config:

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

Other keys: cloudAware.enabled, cloudAware.skipPlaceholdersInWalks, cloudAware.allowBackupInTree, cloudAware.allowArchivalInTree, cloudAware.warnOnHydration. Full matrix in ADR 026.

Uninstalling

To uninstall Nova:

npm uninstall -g @compass-ai/nova

During uninstall, you'll be prompted to optionally remove your user data stored in ~/.compass/. This directory contains:

• Configuration settings
• API credentials (encrypted)
• Conversation history and saved sessions
• Project memories
• Custom commands, agents, and skills
• Token usage tracking

By default, this data is preserved so you can reinstall Nova later without losing your settings.

Complete Removal

To remove Nova and all user data in one step:

# The uninstall prompt will ask if you want to delete ~/.compass
npm uninstall -g @compass-ai/nova
# Answer 'y' when prompted

Or manually remove data after uninstalling:

rm -rf ~/.compass

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

MIT License - see LICENSE for details.

Links

• npm Package
• Report Issues
• Compass Official

Ready to supercharge your development workflow? Install Nova and start building with AI assistance today.

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