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 Opus, Sonnet, 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 | | /undo | Undo last file operation | | /export | Export conversation as Markdown/JSON/HTML | | /compact | Summarize conversation to free context | | /index | Reindex project for semantic search | | /agents | Switch to specialized agents | | /config | View/modify configuration | | /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 | Codebase navigation and understanding | | Code Reviewer | Security and quality analysis | | Debugger | Error diagnosis and fixes | | Planner | Architecture and implementation planning |

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

---
name: security-audit
model: sonnet-4-20250514
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                  # Model configuration
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 | Best For | |-------|----------| | Claude Opus 4.5 | Complex reasoning, architecture decisions | | Claude Sonnet 4.5 | Balanced performance (default) | | Claude Haiku 4.5 | Fast iterations, quick tasks | | Ollama | Cloud/Local/Private, offline capable | | GLM 4.7, Minimax, Kimi, Gemini | Alternative models |

All models support:

• 200K token context window
• Streaming responses
• Vision and 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

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