@compass-ai/nova 1.1.14 → 1.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +263 -354
- package/dist/cli.js +1107 -1064
- package/dist/index.js +728 -687
- package/package.json +6 -4
package/README.md
CHANGED
|
@@ -1,354 +1,263 @@
|
|
|
1
|
-
# Nova
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[)
|
|
267
|
-
|
|
268
|
-
## Troubleshooting
|
|
269
|
-
|
|
270
|
-
### API Key Issues
|
|
271
|
-
```bash
|
|
272
|
-
# Reconfigure your API key
|
|
273
|
-
nova setup
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
### Reset to Defaults
|
|
277
|
-
```bash
|
|
278
|
-
nova reset --force
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
### Enable Debug Mode
|
|
282
|
-
```bash
|
|
283
|
-
COMPASS_DEBUG=true nova
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
### Slow performance in OneDrive / iCloud / Dropbox folders
|
|
287
|
-
Nova detects cloud-synced folders and automatically skips not-yet-downloaded
|
|
288
|
-
placeholder files during bulk searches to avoid triggering mass hydration.
|
|
289
|
-
The codebase indexer is disabled by default inside cloud roots. If you need
|
|
290
|
-
to index anyway (at the cost of downloading every file), set in your config:
|
|
291
|
-
```json
|
|
292
|
-
{ "cloudAware": { "allowIndexing": true } }
|
|
293
|
-
```
|
|
294
|
-
Other keys: `cloudAware.enabled`, `cloudAware.skipPlaceholdersInWalks`,
|
|
295
|
-
`cloudAware.allowBackupInTree`, `cloudAware.allowArchivalInTree`,
|
|
296
|
-
`cloudAware.warnOnHydration`. Full matrix in
|
|
297
|
-
[ADR 026](docs/adr/adr026-cloud-aware-io.md).
|
|
298
|
-
|
|
299
|
-
## Uninstalling
|
|
300
|
-
|
|
301
|
-
To uninstall Nova:
|
|
302
|
-
|
|
303
|
-
```bash
|
|
304
|
-
npm uninstall -g @compass-ai/nova
|
|
305
|
-
```
|
|
306
|
-
|
|
307
|
-
During uninstall, you'll be prompted to optionally remove your user data stored in `~/.compass/`. This directory contains:
|
|
308
|
-
|
|
309
|
-
- Configuration settings
|
|
310
|
-
- API credentials (encrypted)
|
|
311
|
-
- Conversation history and saved sessions
|
|
312
|
-
- Project memories
|
|
313
|
-
- Custom commands, agents, and skills
|
|
314
|
-
- Token usage tracking
|
|
315
|
-
|
|
316
|
-
**By default, this data is preserved** so you can reinstall Nova later without losing your settings.
|
|
317
|
-
|
|
318
|
-
### Complete Removal
|
|
319
|
-
|
|
320
|
-
To remove Nova and all user data in one step:
|
|
321
|
-
|
|
322
|
-
```bash
|
|
323
|
-
# The uninstall prompt will ask if you want to delete ~/.compass
|
|
324
|
-
npm uninstall -g @compass-ai/nova
|
|
325
|
-
# Answer 'y' when prompted
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
Or manually remove data after uninstalling:
|
|
329
|
-
|
|
330
|
-
```bash
|
|
331
|
-
rm -rf ~/.compass
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
## Contributing
|
|
335
|
-
|
|
336
|
-
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
|
|
337
|
-
|
|
338
|
-
## License
|
|
339
|
-
|
|
340
|
-
MIT License - see [LICENSE](LICENSE) for details.
|
|
341
|
-
|
|
342
|
-
## Links
|
|
343
|
-
|
|
344
|
-
- [npm Package](https://www.npmjs.com/package/@compass-ai/nova)
|
|
345
|
-
- [Report Issues](https://github.com/Compass-Agentic-Platform/nova/issues)
|
|
346
|
-
- [Compass Official](https://compassap.ai/)
|
|
347
|
-
|
|
348
|
-
---
|
|
349
|
-
|
|
350
|
-
**Ready to supercharge your development workflow?** Install Nova and start building with AI assistance today.
|
|
351
|
-
|
|
352
|
-
```bash
|
|
353
|
-
npm install -g @compass-ai/nova && nova setup
|
|
354
|
-
```
|
|
1
|
+
# Nova
|
|
2
|
+
|
|
3
|
+
Date: 2026-06-08
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@compass-ai/nova)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
Nova is the flagship Compass AI agent for planning, editing, verifying, and shipping software from your terminal.
|
|
11
|
+
|
|
12
|
+
Built for real repositories, long-running sessions, guarded execution, dirty worktrees, and teams that need more than a chat box pasted beside an editor.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install -g @compass-ai/nova
|
|
16
|
+
nova setup
|
|
17
|
+
nova
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
You can also launch the same CLI with:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
compass
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Why Nova
|
|
27
|
+
|
|
28
|
+
Nova is designed for production software work, not demo prompts.
|
|
29
|
+
|
|
30
|
+
| Capability | What it means |
|
|
31
|
+
| --- | --- |
|
|
32
|
+
| Agentic delivery | Ask for outcomes: investigate, plan, edit, test, review, commit. |
|
|
33
|
+
| Deep repository context | Nova searches, reads, and reasons across project files before changing them. |
|
|
34
|
+
| Guarded execution | File, shell, git, database, and external actions run through explicit safety rules. |
|
|
35
|
+
| Multi-model support | Use Compass-managed models, provider keys, OAuth flows, or registered custom endpoints. |
|
|
36
|
+
| Extensible workflows | Add custom slash commands, MCP servers, skills, agents, hooks, and scheduled tasks. |
|
|
37
|
+
| Git-native operation | Work with diffs, branches, commits, worktrees, dirty-tree isolation, and PR-ready summaries. |
|
|
38
|
+
|
|
39
|
+
## What you can ask Nova to do
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
❯ Find why checkout fails after the latest auth change
|
|
43
|
+
❯ Plan a safe migration from Express middleware to Fastify hooks
|
|
44
|
+
❯ Implement the plan and verify it with tests
|
|
45
|
+
❯ Review this diff for regressions and security issues
|
|
46
|
+
❯ Create a conventional commit for the staged changes
|
|
47
|
+
❯ Spawn a verification agent to check the fix without editing files
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Nova can write code, refactor modules, explain systems, run tests, inspect logs, generate documentation, manage git state, and coordinate multi-step implementation plans.
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
### Requirements
|
|
55
|
+
|
|
56
|
+
- Node.js >= 22.12.0
|
|
57
|
+
- npm
|
|
58
|
+
- A Compass account or API credentials for your chosen model provider
|
|
59
|
+
|
|
60
|
+
### Global install
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npm install -g @compass-ai/nova
|
|
64
|
+
nova setup
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The setup flow configures authentication, consent, provider access, and local preferences.
|
|
68
|
+
|
|
69
|
+
### Start a session
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cd your-project
|
|
73
|
+
nova
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Run one non-interactive query for scripts or CI-style usage:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
nova --print "summarize the staged diff"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Core capabilities
|
|
83
|
+
|
|
84
|
+
### Plan, build, verify
|
|
85
|
+
|
|
86
|
+
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.
|
|
87
|
+
|
|
88
|
+
### Codebase understanding
|
|
89
|
+
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
|
+
### Safe tool use
|
|
93
|
+
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
### Agents and skills
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
|
|
100
|
+
### Model flexibility
|
|
101
|
+
|
|
102
|
+
Nova supports Compass-managed models, Anthropic-compatible providers, OpenAI chat and responses flows, OpenAI OAuth where available, and custom model endpoints through `nova models`.
|
|
103
|
+
|
|
104
|
+
### Worktree isolation
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
### MCP and custom workflows
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
112
|
+
## Command surface
|
|
113
|
+
|
|
114
|
+
### CLI commands
|
|
115
|
+
|
|
116
|
+
| Command | Purpose |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `nova` | Start the interactive agent session. |
|
|
119
|
+
| `nova setup` | Configure auth, provider keys, and consent. |
|
|
120
|
+
| `nova init` | Create project-local Compass configuration. |
|
|
121
|
+
| `nova commit` | Generate and create a conventional commit from staged changes. |
|
|
122
|
+
| `nova models` | Register, list, and remove custom model endpoints. |
|
|
123
|
+
| `nova mcp` | Manage MCP servers and authentication. |
|
|
124
|
+
| `nova openai` | Manage OpenAI login, status, and usage flows. |
|
|
125
|
+
| `nova worktrees` | Inspect and manage Nova-created worktrees. |
|
|
126
|
+
| `nova tokens` | Inspect token usage. |
|
|
127
|
+
| `nova data` | Export or inspect local user data. |
|
|
128
|
+
| `nova cache` | Clear project and global cache data. |
|
|
129
|
+
| `nova logs` | Inspect JSONL system event logs. |
|
|
130
|
+
| `nova reset` | Reset configuration and local state. |
|
|
131
|
+
| `nova update` | Check for and install updates. |
|
|
132
|
+
|
|
133
|
+
### In-session commands
|
|
134
|
+
|
|
135
|
+
| Command | Purpose |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| `/help` | Show available commands. |
|
|
138
|
+
| `/model` | Switch models. |
|
|
139
|
+
| `/plan` | Create or manage an implementation plan. |
|
|
140
|
+
| `/commit` | Generate a commit from staged changes. |
|
|
141
|
+
| `/agents` | Switch or inspect specialized agents. |
|
|
142
|
+
| `/mcp` | Manage MCP tooling. |
|
|
143
|
+
| `/tokens` | View token usage. |
|
|
144
|
+
| `/cost` | View estimated cost. |
|
|
145
|
+
| `/context` | Inspect context usage. |
|
|
146
|
+
| `/compact` | Summarize long sessions to recover context. |
|
|
147
|
+
| `/export` | Export the conversation. |
|
|
148
|
+
| `/undo` | Revert supported file edits. |
|
|
149
|
+
| `/attach` | Attach files to the session. |
|
|
150
|
+
| `/ask` | Ask a side question without polluting the main thread. |
|
|
151
|
+
| `/exit` | Leave Nova. |
|
|
152
|
+
|
|
153
|
+
## Custom slash commands
|
|
154
|
+
|
|
155
|
+
Project commands live in `.compass/commands`. Personal commands live in `~/.compass/commands`.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
mkdir -p .compass/commands
|
|
159
|
+
echo "Review this code for performance and correctness issues:" > .compass/commands/review.md
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Use arguments, file references, command output, and frontmatter to define repeatable workflows.
|
|
163
|
+
|
|
164
|
+
```markdown
|
|
165
|
+
---
|
|
166
|
+
description: Fix a tracked issue
|
|
167
|
+
argument-hint: [issue-number]
|
|
168
|
+
allowed-tools: Bash(git:*)
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
Current branch: !`git branch --show-current`
|
|
172
|
+
Recent commits: !`git log --oneline -5`
|
|
173
|
+
|
|
174
|
+
Fix issue #$1 and verify the change.
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Run it inside Nova:
|
|
178
|
+
|
|
179
|
+
```text
|
|
180
|
+
/fix-issue 123
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Configuration
|
|
184
|
+
|
|
185
|
+
Nova resolves configuration in this order:
|
|
186
|
+
|
|
187
|
+
1. Built-in defaults
|
|
188
|
+
2. Global config at `~/.compass/config.json`
|
|
189
|
+
3. Project config at `./.compass/config.json`
|
|
190
|
+
4. Environment variables
|
|
191
|
+
5. CLI flags
|
|
192
|
+
|
|
193
|
+
Common environment variables:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
COMPASS_MODEL=sonnet
|
|
197
|
+
COMPASS_DEBUG=true
|
|
198
|
+
COMPASS_VERBOSE=true
|
|
199
|
+
NO_COLOR=1
|
|
200
|
+
ANTHROPIC_API_KEY=your_key_here
|
|
201
|
+
OPENAI_API_KEY=your_key_here
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Privacy and safety
|
|
205
|
+
|
|
206
|
+
Nova is built around local control and explicit approvals.
|
|
207
|
+
|
|
208
|
+
- Credentials are stored securely instead of written into project files.
|
|
209
|
+
- User data, memories, sessions, commands, skills, and cache live under `~/.compass` unless project-local config is used.
|
|
210
|
+
- File edits are backed up where supported.
|
|
211
|
+
- Destructive commands, external side effects, and shared-state operations are gated.
|
|
212
|
+
- Dirty repositories can be isolated through managed worktrees.
|
|
213
|
+
- GDPR-style export and deletion flows are available through `nova data` and consent commands.
|
|
214
|
+
- Nova only assists with defensive security work and refuses malicious security tasks.
|
|
215
|
+
|
|
216
|
+
## Troubleshooting
|
|
217
|
+
|
|
218
|
+
### Reconfigure auth
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
nova setup
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Reset local state
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
nova reset --force
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Enable debug logs
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
COMPASS_DEBUG=true nova
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Cloud-synced folders
|
|
237
|
+
|
|
238
|
+
Nova detects OneDrive, iCloud, Dropbox, and similar folders. It avoids hydrating placeholder files during bulk searches and disables indexing inside cloud roots by default.
|
|
239
|
+
|
|
240
|
+
To override that behavior:
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{ "cloudAware": { "allowIndexing": true } }
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Use this carefully; indexing cloud placeholders can download a ton of files.
|
|
247
|
+
|
|
248
|
+
## Uninstall
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
npm uninstall -g @compass-ai/nova
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
The uninstall flow can preserve or remove `~/.compass`, which contains configuration, encrypted credentials, sessions, memories, commands, agents, skills, token usage, and cache data.
|
|
255
|
+
|
|
256
|
+
## Links
|
|
257
|
+
|
|
258
|
+
- [npm package](https://www.npmjs.com/package/@compass-ai/nova)
|
|
259
|
+
- [Compass](https://compassap.ai/)
|
|
260
|
+
- [License](LICENSE)
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
Co-authored by [Nova](https://www.compassap.ai/portfolio/nova.html)
|