@build-astron-co/nimbus 0.4.1 → 0.4.3
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/CHANGELOG.md +268 -89
- package/README.md +26 -567
- package/dist/src/agent/compaction-agent.js +24 -12
- package/dist/src/agent/context-manager.js +2 -1
- package/dist/src/agent/expand-files.js +2 -1
- package/dist/src/agent/loop.js +71 -33
- package/dist/src/agent/permissions.js +4 -2
- package/dist/src/agent/system-prompt.js +34 -17
- package/dist/src/app.js +1 -1
- package/dist/src/auth/keychain.js +8 -4
- package/dist/src/auth/store.js +70 -107
- package/dist/src/cli/init.js +35 -19
- package/dist/src/cli/run.js +18 -10
- package/dist/src/cli/serve.js +4 -2
- package/dist/src/cli.js +52 -11
- package/dist/src/commands/alias.js +5 -3
- package/dist/src/commands/audit/index.js +2 -1
- package/dist/src/commands/aws-terraform.js +36 -18
- package/dist/src/commands/completions.js +1 -1
- package/dist/src/commands/config.js +3 -2
- package/dist/src/commands/connect-github.js +92 -0
- package/dist/src/commands/cost/index.js +3 -2
- package/dist/src/commands/deploy.js +15 -10
- package/dist/src/commands/doctor.js +9 -6
- package/dist/src/commands/drift/index.js +2 -1
- package/dist/src/commands/export.js +5 -3
- package/dist/src/commands/generate-terraform.js +110 -2
- package/dist/src/commands/import.js +3 -3
- package/dist/src/commands/incident.js +10 -5
- package/dist/src/commands/login.js +8 -93
- package/dist/src/commands/logs.js +16 -8
- package/dist/src/commands/onboarding.js +6 -4
- package/dist/src/commands/pipeline.js +6 -3
- package/dist/src/commands/plugin.js +3 -2
- package/dist/src/commands/profile.js +27 -14
- package/dist/src/commands/questionnaire.js +1 -1
- package/dist/src/commands/rollback.js +3 -2
- package/dist/src/commands/rollout.js +5 -3
- package/dist/src/commands/runbook.js +17 -10
- package/dist/src/commands/schedule.js +10 -5
- package/dist/src/commands/status.js +2 -1
- package/dist/src/commands/team-context.js +12 -7
- package/dist/src/commands/template.js +1 -1
- package/dist/src/commands/tf/index.js +6 -3
- package/dist/src/commands/upgrade.js +5 -3
- package/dist/src/commands/version.js +6 -3
- package/dist/src/commands/watch.js +6 -3
- package/dist/src/compat/sqlite.js +5 -3
- package/dist/src/config/mode-store.js +2 -1
- package/dist/src/config/profiles.js +4 -2
- package/dist/src/config/types.js +2 -1
- package/dist/src/engine/executor.js +8 -4
- package/dist/src/engine/planner.js +9 -5
- package/dist/src/llm/providers/anthropic.js +6 -3
- package/dist/src/llm/providers/ollama.js +1 -1
- package/dist/src/llm/router.js +22 -7
- package/dist/src/nimbus.js +1 -0
- package/dist/src/sessions/manager.js +6 -3
- package/dist/src/sharing/viewer.js +2 -1
- package/dist/src/tools/file-ops.js +1 -2
- package/dist/src/tools/schemas/devops.js +197 -108
- package/dist/src/tools/schemas/standard.js +1 -1
- package/dist/src/ui/App.js +25 -13
- package/dist/src/ui/FileDiffModal.js +22 -11
- package/dist/src/ui/HelpModal.js +2 -1
- package/dist/src/ui/InputBox.js +6 -3
- package/dist/src/ui/MessageList.js +40 -20
- package/dist/src/ui/TerminalPane.js +2 -1
- package/dist/src/ui/ToolCallDisplay.js +12 -6
- package/dist/src/ui/TreePane.js +2 -1
- package/dist/src/ui/ink/index.js +37 -21
- package/dist/src/version.js +1 -1
- package/dist/src/watcher/index.js +8 -4
- package/package.json +3 -5
- package/src/__tests__/alias.test.ts +0 -133
- package/src/__tests__/app.test.ts +0 -76
- package/src/__tests__/audit.test.ts +0 -877
- package/src/__tests__/circuit-breaker.test.ts +0 -116
- package/src/__tests__/cli-run.test.ts +0 -351
- package/src/__tests__/compat-sqlite.test.ts +0 -68
- package/src/__tests__/context-manager.test.ts +0 -632
- package/src/__tests__/context.test.ts +0 -242
- package/src/__tests__/devops-terminal-gaps.test.ts +0 -718
- package/src/__tests__/doctor.test.ts +0 -48
- package/src/__tests__/enterprise.test.ts +0 -401
- package/src/__tests__/export.test.ts +0 -236
- package/src/__tests__/gap-11-18-20.test.ts +0 -958
- package/src/__tests__/generator.test.ts +0 -433
- package/src/__tests__/helm-streaming.test.ts +0 -127
- package/src/__tests__/hooks.test.ts +0 -582
- package/src/__tests__/incident.test.ts +0 -179
- package/src/__tests__/init.test.ts +0 -487
- package/src/__tests__/intent-parser.test.ts +0 -229
- package/src/__tests__/llm-router.test.ts +0 -209
- package/src/__tests__/logs.test.ts +0 -107
- package/src/__tests__/loop-errors.test.ts +0 -244
- package/src/__tests__/lsp.test.ts +0 -293
- package/src/__tests__/modes.test.ts +0 -336
- package/src/__tests__/perf-optimizations.test.ts +0 -847
- package/src/__tests__/permissions.test.ts +0 -338
- package/src/__tests__/pipeline.test.ts +0 -50
- package/src/__tests__/polish-phase3.test.ts +0 -340
- package/src/__tests__/profile.test.ts +0 -237
- package/src/__tests__/rollback.test.ts +0 -83
- package/src/__tests__/runbook.test.ts +0 -219
- package/src/__tests__/schedule.test.ts +0 -206
- package/src/__tests__/serve.test.ts +0 -275
- package/src/__tests__/sessions.test.ts +0 -322
- package/src/__tests__/sharing.test.ts +0 -340
- package/src/__tests__/snapshots.test.ts +0 -581
- package/src/__tests__/standalone-migration.test.ts +0 -199
- package/src/__tests__/state-db.test.ts +0 -334
- package/src/__tests__/status.test.ts +0 -158
- package/src/__tests__/stream-with-tools.test.ts +0 -778
- package/src/__tests__/subagents.test.ts +0 -176
- package/src/__tests__/system-prompt.test.ts +0 -248
- package/src/__tests__/terminal-gap-v2.test.ts +0 -395
- package/src/__tests__/terminal-parity.test.ts +0 -393
- package/src/__tests__/tf-apply.test.ts +0 -187
- package/src/__tests__/tool-converter.test.ts +0 -256
- package/src/__tests__/tool-schemas.test.ts +0 -602
- package/src/__tests__/tools.test.ts +0 -144
- package/src/__tests__/version-json.test.ts +0 -184
- package/src/__tests__/version.test.ts +0 -49
- package/src/__tests__/watch.test.ts +0 -129
- package/src/agent/compaction-agent.ts +0 -266
- package/src/agent/context-manager.ts +0 -499
- package/src/agent/context.ts +0 -427
- package/src/agent/deploy-preview.ts +0 -487
- package/src/agent/expand-files.ts +0 -108
- package/src/agent/index.ts +0 -68
- package/src/agent/loop.ts +0 -1998
- package/src/agent/modes.ts +0 -429
- package/src/agent/permissions.ts +0 -513
- package/src/agent/subagents/base.ts +0 -116
- package/src/agent/subagents/cost.ts +0 -51
- package/src/agent/subagents/explore.ts +0 -42
- package/src/agent/subagents/general.ts +0 -54
- package/src/agent/subagents/index.ts +0 -102
- package/src/agent/subagents/infra.ts +0 -59
- package/src/agent/subagents/security.ts +0 -69
- package/src/agent/system-prompt.ts +0 -990
- package/src/app.ts +0 -180
- package/src/audit/activity-log.ts +0 -290
- package/src/audit/compliance-checker.ts +0 -540
- package/src/audit/cost-tracker.ts +0 -318
- package/src/audit/index.ts +0 -23
- package/src/audit/security-scanner.ts +0 -641
- package/src/auth/guard.ts +0 -75
- package/src/auth/index.ts +0 -56
- package/src/auth/keychain.ts +0 -82
- package/src/auth/oauth.ts +0 -465
- package/src/auth/providers.ts +0 -470
- package/src/auth/sso.ts +0 -113
- package/src/auth/store.ts +0 -505
- package/src/auth/types.ts +0 -187
- package/src/build.ts +0 -141
- package/src/cli/index.ts +0 -16
- package/src/cli/init.ts +0 -1227
- package/src/cli/openapi-spec.ts +0 -356
- package/src/cli/run.ts +0 -628
- package/src/cli/serve-auth.ts +0 -80
- package/src/cli/serve.ts +0 -539
- package/src/cli/web.ts +0 -71
- package/src/cli.ts +0 -1728
- package/src/clients/core-engine-client.ts +0 -227
- package/src/clients/enterprise-client.ts +0 -334
- package/src/clients/generator-client.ts +0 -351
- package/src/clients/git-client.ts +0 -627
- package/src/clients/github-client.ts +0 -410
- package/src/clients/helm-client.ts +0 -504
- package/src/clients/index.ts +0 -80
- package/src/clients/k8s-client.ts +0 -497
- package/src/clients/llm-client.ts +0 -161
- package/src/clients/rest-client.ts +0 -130
- package/src/clients/service-discovery.ts +0 -38
- package/src/clients/terraform-client.ts +0 -482
- package/src/clients/tools-client.ts +0 -1843
- package/src/clients/ws-client.ts +0 -115
- package/src/commands/alias.ts +0 -100
- package/src/commands/analyze/index.ts +0 -352
- package/src/commands/apply/helm.ts +0 -473
- package/src/commands/apply/index.ts +0 -213
- package/src/commands/apply/k8s.ts +0 -454
- package/src/commands/apply/terraform.ts +0 -582
- package/src/commands/ask.ts +0 -167
- package/src/commands/audit/index.ts +0 -357
- package/src/commands/auth-cloud.ts +0 -407
- package/src/commands/auth-list.ts +0 -134
- package/src/commands/auth-profile.ts +0 -121
- package/src/commands/auth-refresh.ts +0 -187
- package/src/commands/auth-status.ts +0 -141
- package/src/commands/aws/ec2.ts +0 -501
- package/src/commands/aws/iam.ts +0 -397
- package/src/commands/aws/index.ts +0 -133
- package/src/commands/aws/lambda.ts +0 -396
- package/src/commands/aws/rds.ts +0 -439
- package/src/commands/aws/s3.ts +0 -439
- package/src/commands/aws/vpc.ts +0 -393
- package/src/commands/aws-discover.ts +0 -542
- package/src/commands/aws-terraform.ts +0 -755
- package/src/commands/azure/aks.ts +0 -376
- package/src/commands/azure/functions.ts +0 -253
- package/src/commands/azure/index.ts +0 -116
- package/src/commands/azure/storage.ts +0 -478
- package/src/commands/azure/vm.ts +0 -355
- package/src/commands/billing/index.ts +0 -256
- package/src/commands/chat.ts +0 -320
- package/src/commands/completions.ts +0 -268
- package/src/commands/config.ts +0 -372
- package/src/commands/cost/cloud-cost-estimator.ts +0 -266
- package/src/commands/cost/estimator.ts +0 -79
- package/src/commands/cost/index.ts +0 -810
- package/src/commands/cost/parsers/terraform.ts +0 -273
- package/src/commands/cost/parsers/types.ts +0 -25
- package/src/commands/cost/pricing/aws.ts +0 -544
- package/src/commands/cost/pricing/azure.ts +0 -499
- package/src/commands/cost/pricing/gcp.ts +0 -396
- package/src/commands/cost/pricing/index.ts +0 -40
- package/src/commands/demo.ts +0 -250
- package/src/commands/deploy.ts +0 -260
- package/src/commands/doctor.ts +0 -1386
- package/src/commands/drift/index.ts +0 -787
- package/src/commands/explain.ts +0 -277
- package/src/commands/export.ts +0 -146
- package/src/commands/feedback.ts +0 -389
- package/src/commands/fix.ts +0 -324
- package/src/commands/fs/index.ts +0 -402
- package/src/commands/gcp/compute.ts +0 -325
- package/src/commands/gcp/functions.ts +0 -271
- package/src/commands/gcp/gke.ts +0 -438
- package/src/commands/gcp/iam.ts +0 -344
- package/src/commands/gcp/index.ts +0 -129
- package/src/commands/gcp/storage.ts +0 -284
- package/src/commands/generate-helm.ts +0 -1249
- package/src/commands/generate-k8s.ts +0 -1508
- package/src/commands/generate-terraform.ts +0 -1202
- package/src/commands/gh/index.ts +0 -863
- package/src/commands/git/index.ts +0 -1343
- package/src/commands/helm/index.ts +0 -1126
- package/src/commands/help.ts +0 -715
- package/src/commands/history.ts +0 -149
- package/src/commands/import.ts +0 -868
- package/src/commands/incident.ts +0 -166
- package/src/commands/index.ts +0 -367
- package/src/commands/init.ts +0 -1051
- package/src/commands/k8s/index.ts +0 -1137
- package/src/commands/login.ts +0 -716
- package/src/commands/logout.ts +0 -83
- package/src/commands/logs.ts +0 -167
- package/src/commands/onboarding.ts +0 -405
- package/src/commands/pipeline.ts +0 -186
- package/src/commands/plan/display.ts +0 -279
- package/src/commands/plan/index.ts +0 -599
- package/src/commands/plugin.ts +0 -398
- package/src/commands/preview.ts +0 -452
- package/src/commands/profile.ts +0 -342
- package/src/commands/questionnaire.ts +0 -1172
- package/src/commands/resume.ts +0 -47
- package/src/commands/rollback.ts +0 -315
- package/src/commands/rollout.ts +0 -88
- package/src/commands/runbook.ts +0 -346
- package/src/commands/schedule.ts +0 -236
- package/src/commands/status.ts +0 -252
- package/src/commands/team/index.ts +0 -346
- package/src/commands/team-context.ts +0 -220
- package/src/commands/template.ts +0 -233
- package/src/commands/tf/index.ts +0 -1093
- package/src/commands/upgrade.ts +0 -607
- package/src/commands/usage/index.ts +0 -134
- package/src/commands/version.ts +0 -174
- package/src/commands/watch.ts +0 -153
- package/src/compat/index.ts +0 -2
- package/src/compat/runtime.ts +0 -12
- package/src/compat/sqlite.ts +0 -177
- package/src/config/index.ts +0 -17
- package/src/config/manager.ts +0 -530
- package/src/config/mode-store.ts +0 -62
- package/src/config/profiles.ts +0 -84
- package/src/config/safety-policy.ts +0 -358
- package/src/config/schema.ts +0 -125
- package/src/config/types.ts +0 -609
- package/src/config/workspace-state.ts +0 -53
- package/src/context/context-db.ts +0 -199
- package/src/demo/index.ts +0 -349
- package/src/demo/scenarios/full-journey.ts +0 -229
- package/src/demo/scenarios/getting-started.ts +0 -127
- package/src/demo/scenarios/helm-release.ts +0 -341
- package/src/demo/scenarios/k8s-deployment.ts +0 -194
- package/src/demo/scenarios/terraform-vpc.ts +0 -170
- package/src/demo/types.ts +0 -92
- package/src/engine/cost-estimator.ts +0 -480
- package/src/engine/diagram-generator.ts +0 -256
- package/src/engine/drift-detector.ts +0 -902
- package/src/engine/executor.ts +0 -1066
- package/src/engine/index.ts +0 -76
- package/src/engine/orchestrator.ts +0 -636
- package/src/engine/planner.ts +0 -787
- package/src/engine/safety.ts +0 -743
- package/src/engine/verifier.ts +0 -770
- package/src/enterprise/audit.ts +0 -348
- package/src/enterprise/auth.ts +0 -270
- package/src/enterprise/billing.ts +0 -822
- package/src/enterprise/index.ts +0 -17
- package/src/enterprise/teams.ts +0 -443
- package/src/generator/best-practices.ts +0 -1608
- package/src/generator/helm.ts +0 -630
- package/src/generator/index.ts +0 -37
- package/src/generator/intent-parser.ts +0 -514
- package/src/generator/kubernetes.ts +0 -976
- package/src/generator/terraform.ts +0 -1875
- package/src/history/index.ts +0 -8
- package/src/history/manager.ts +0 -250
- package/src/history/types.ts +0 -34
- package/src/hooks/config.ts +0 -432
- package/src/hooks/engine.ts +0 -392
- package/src/hooks/index.ts +0 -4
- package/src/llm/auth-bridge.ts +0 -198
- package/src/llm/circuit-breaker.ts +0 -140
- package/src/llm/config-loader.ts +0 -201
- package/src/llm/cost-calculator.ts +0 -171
- package/src/llm/index.ts +0 -8
- package/src/llm/model-aliases.ts +0 -115
- package/src/llm/provider-registry.ts +0 -63
- package/src/llm/providers/anthropic.ts +0 -462
- package/src/llm/providers/bedrock.ts +0 -477
- package/src/llm/providers/google.ts +0 -405
- package/src/llm/providers/ollama.ts +0 -767
- package/src/llm/providers/openai-compatible.ts +0 -340
- package/src/llm/providers/openai.ts +0 -328
- package/src/llm/providers/openrouter.ts +0 -338
- package/src/llm/router.ts +0 -1104
- package/src/llm/types.ts +0 -232
- package/src/lsp/client.ts +0 -298
- package/src/lsp/languages.ts +0 -119
- package/src/lsp/manager.ts +0 -294
- package/src/mcp/client.ts +0 -402
- package/src/mcp/index.ts +0 -5
- package/src/mcp/manager.ts +0 -133
- package/src/nimbus.ts +0 -233
- package/src/plugins/index.ts +0 -27
- package/src/plugins/loader.ts +0 -334
- package/src/plugins/manager.ts +0 -376
- package/src/plugins/types.ts +0 -284
- package/src/scanners/cicd-scanner.ts +0 -258
- package/src/scanners/cloud-scanner.ts +0 -466
- package/src/scanners/framework-scanner.ts +0 -469
- package/src/scanners/iac-scanner.ts +0 -388
- package/src/scanners/index.ts +0 -539
- package/src/scanners/language-scanner.ts +0 -276
- package/src/scanners/package-manager-scanner.ts +0 -277
- package/src/scanners/types.ts +0 -172
- package/src/sessions/manager.ts +0 -472
- package/src/sessions/types.ts +0 -44
- package/src/sharing/sync.ts +0 -300
- package/src/sharing/viewer.ts +0 -163
- package/src/snapshots/index.ts +0 -2
- package/src/snapshots/manager.ts +0 -530
- package/src/state/artifacts.ts +0 -147
- package/src/state/audit.ts +0 -137
- package/src/state/billing.ts +0 -240
- package/src/state/checkpoints.ts +0 -117
- package/src/state/config.ts +0 -67
- package/src/state/conversations.ts +0 -14
- package/src/state/credentials.ts +0 -154
- package/src/state/db.ts +0 -58
- package/src/state/index.ts +0 -26
- package/src/state/messages.ts +0 -115
- package/src/state/projects.ts +0 -123
- package/src/state/schema.ts +0 -236
- package/src/state/sessions.ts +0 -147
- package/src/state/teams.ts +0 -200
- package/src/telemetry.ts +0 -108
- package/src/tools/aws-ops.ts +0 -952
- package/src/tools/azure-ops.ts +0 -579
- package/src/tools/file-ops.ts +0 -615
- package/src/tools/gcp-ops.ts +0 -625
- package/src/tools/git-ops.ts +0 -773
- package/src/tools/github-ops.ts +0 -799
- package/src/tools/helm-ops.ts +0 -943
- package/src/tools/index.ts +0 -17
- package/src/tools/k8s-ops.ts +0 -819
- package/src/tools/schemas/converter.ts +0 -184
- package/src/tools/schemas/devops.ts +0 -3502
- package/src/tools/schemas/index.ts +0 -73
- package/src/tools/schemas/standard.ts +0 -1148
- package/src/tools/schemas/types.ts +0 -735
- package/src/tools/spawn-exec.ts +0 -148
- package/src/tools/terraform-ops.ts +0 -862
- package/src/types/ambient.d.ts +0 -193
- package/src/types/config.ts +0 -83
- package/src/types/drift.ts +0 -116
- package/src/types/enterprise.ts +0 -335
- package/src/types/index.ts +0 -20
- package/src/types/plan.ts +0 -44
- package/src/types/request.ts +0 -65
- package/src/types/response.ts +0 -54
- package/src/types/service.ts +0 -51
- package/src/ui/App.tsx +0 -2114
- package/src/ui/DeployPreview.tsx +0 -174
- package/src/ui/FileDiffModal.tsx +0 -162
- package/src/ui/Header.tsx +0 -131
- package/src/ui/HelpModal.tsx +0 -57
- package/src/ui/InputBox.tsx +0 -503
- package/src/ui/MessageList.tsx +0 -1032
- package/src/ui/PermissionPrompt.tsx +0 -163
- package/src/ui/StatusBar.tsx +0 -277
- package/src/ui/TerminalPane.tsx +0 -84
- package/src/ui/ToolCallDisplay.tsx +0 -643
- package/src/ui/TreePane.tsx +0 -132
- package/src/ui/chat-ui.ts +0 -850
- package/src/ui/index.ts +0 -33
- package/src/ui/ink/index.ts +0 -1444
- package/src/ui/streaming.ts +0 -176
- package/src/ui/theme.ts +0 -104
- package/src/ui/types.ts +0 -75
- package/src/utils/analytics.ts +0 -72
- package/src/utils/cost-warning.ts +0 -27
- package/src/utils/env.ts +0 -46
- package/src/utils/errors.ts +0 -69
- package/src/utils/event-bus.ts +0 -38
- package/src/utils/index.ts +0 -24
- package/src/utils/logger.ts +0 -171
- package/src/utils/rate-limiter.ts +0 -121
- package/src/utils/service-auth.ts +0 -49
- package/src/utils/validation.ts +0 -53
- package/src/version.ts +0 -4
- package/src/watcher/index.ts +0 -214
- package/src/wizard/approval.ts +0 -383
- package/src/wizard/index.ts +0 -25
- package/src/wizard/prompts.ts +0 -338
- package/src/wizard/types.ts +0 -172
- package/src/wizard/ui.ts +0 -556
- package/src/wizard/wizard.ts +0 -304
- package/tsconfig.json +0 -24
package/README.md
CHANGED
|
@@ -6,605 +6,64 @@
|
|
|
6
6
|
[](https://github.com/the-ai-project-co/nimbus/actions)
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
[](https://nodejs.org/)
|
|
9
|
-
[](https://github.com/the-ai-project-co/nimbus/actions)
|
|
10
10
|
|
|
11
|
-
> AI-powered
|
|
11
|
+
> AI-powered DevOps terminal agent — type `nimbus`, get a live infrastructure operator
|
|
12
12
|
|
|
13
|
-
Nimbus is an intelligent command-line agent
|
|
14
|
-
language models to DevOps and cloud engineering workflows. Think of it as an AI
|
|
15
|
-
pair-programmer that understands Terraform, Kubernetes, Helm, and cloud
|
|
16
|
-
providers natively. It ships as a single self-contained binary with an
|
|
17
|
-
interactive terminal UI, 20 built-in tools, support for 11+ LLM providers, and a
|
|
18
|
-
three-mode safety system that separates reading, building, and deploying.
|
|
13
|
+
Nimbus is an intelligent command-line agent purpose-built for DevOps and cloud engineering. Type `nimbus`, describe what you want, and Nimbus plans, validates, and executes across Terraform, Kubernetes, Helm, AWS, GCP, and Azure — all from a single terminal session.
|
|
19
14
|
|
|
20
15
|
---
|
|
21
16
|
|
|
22
|
-
##
|
|
23
|
-
|
|
24
|
-
- [Features](#features)
|
|
25
|
-
- [Quick Start](#quick-start)
|
|
26
|
-
- [Installation](#installation)
|
|
27
|
-
- [Getting Started](#getting-started)
|
|
28
|
-
- [Commands](#commands)
|
|
29
|
-
- [Modes](#modes)
|
|
30
|
-
- [LLM Providers](#llm-providers)
|
|
31
|
-
- [MCP Support](#mcp-support)
|
|
32
|
-
- [Project Configuration (NIMBUS.md)](#project-configuration-nimbusmd)
|
|
33
|
-
- [Keyboard Shortcuts (TUI)](#keyboard-shortcuts-tui)
|
|
34
|
-
- [Development](#development)
|
|
35
|
-
- [Architecture](#architecture)
|
|
36
|
-
- [License](#license)
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
## Features
|
|
41
|
-
|
|
42
|
-
- **Interactive TUI** -- Rich terminal interface built with Ink and React,
|
|
43
|
-
featuring syntax highlighting, markdown rendering, code blocks, and a status
|
|
44
|
-
bar with mode indicators.
|
|
45
|
-
- **20 Built-in Tools** -- File operations (read, write, edit, glob, grep), git,
|
|
46
|
-
bash, terraform, kubectl, helm, AWS/GCP/Azure cloud discovery, web search,
|
|
47
|
-
cost estimation, drift detection, deploy preview, and subagent task spawning.
|
|
48
|
-
- **11+ LLM Providers** -- Anthropic, OpenAI, Google, AWS Bedrock, Azure OpenAI,
|
|
49
|
-
Ollama, Groq, DeepSeek, OpenRouter, Together AI, Fireworks AI, and Perplexity.
|
|
50
|
-
Any OpenAI-compatible endpoint can be added.
|
|
51
|
-
- **Three Modes** -- Plan (read-only), Build (edit/create), and Deploy (full
|
|
52
|
-
infra access). Each mode progressively expands tool availability and resets
|
|
53
|
-
permissions on switch.
|
|
54
|
-
- **Session Persistence** -- Conversations are stored in SQLite and can be
|
|
55
|
-
resumed, branched, or shared. Multi-session support with file conflict
|
|
56
|
-
detection.
|
|
57
|
-
- **MCP Server Support** -- Connect to Model Context Protocol servers to extend
|
|
58
|
-
Nimbus with external tools via JSON-RPC over stdio or HTTP.
|
|
59
|
-
- **Subagent System** -- Spawn parallel sub-tasks (explore, infra, security,
|
|
60
|
-
cost, general) with isolated context and independent model selection.
|
|
61
|
-
- **Context Management** -- Auto-compaction at 85% context window usage.
|
|
62
|
-
Preserves first message, last 5 messages, summaries, and active tool state.
|
|
63
|
-
- **Snapshot / Undo / Redo** -- Uses `git write-tree` for git projects (or
|
|
64
|
-
filesystem copy for non-git) to checkpoint and roll back changes.
|
|
65
|
-
- **Infrastructure Generation** -- Generate Terraform configurations, Kubernetes
|
|
66
|
-
manifests, and Helm charts from natural language descriptions with
|
|
67
|
-
best-practice templates.
|
|
68
|
-
- **Cost Estimation and Drift Detection** -- Estimate infrastructure costs
|
|
69
|
-
before deploying and detect configuration drift across your environments.
|
|
70
|
-
- **Enterprise Features** -- Teams, billing, audit logs, usage tracking,
|
|
71
|
-
security scanning, and compliance checking (SOC2, HIPAA, PCI-DSS, GDPR, ISO
|
|
72
|
-
27001).
|
|
73
|
-
- **Web UI** -- Browser-based interface via `nimbus web`, backed by an Elysia
|
|
74
|
-
HTTP API with SSE streaming.
|
|
75
|
-
- **Human-in-the-Loop Safety** -- 4-tier permission engine (auto_allow,
|
|
76
|
-
ask_once, always_ask, blocked) with action-specific escalation for destructive
|
|
77
|
-
operations.
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## Quick Start
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
# Install
|
|
85
|
-
npm install -g @build-astron-co/nimbus
|
|
86
|
-
# or via Homebrew
|
|
87
|
-
brew tap the-ai-project-co/tap
|
|
88
|
-
brew install nimbus
|
|
89
|
-
|
|
90
|
-
# Set up authentication
|
|
91
|
-
nimbus login
|
|
92
|
-
|
|
93
|
-
# Start the interactive AI agent
|
|
94
|
-
nimbus
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
On first run, Nimbus launches an onboarding flow that walks you through provider
|
|
98
|
-
selection and API key configuration. After that, running `nimbus` drops you into
|
|
99
|
-
the interactive chat.
|
|
100
|
-
|
|
101
|
-
---
|
|
102
|
-
|
|
103
|
-
## Installation
|
|
104
|
-
|
|
105
|
-
### npm (recommended)
|
|
17
|
+
## Install
|
|
106
18
|
|
|
107
19
|
```bash
|
|
20
|
+
# npm
|
|
108
21
|
npm install -g @build-astron-co/nimbus
|
|
109
|
-
```
|
|
110
22
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
### Homebrew (macOS / Linux)
|
|
114
|
-
|
|
115
|
-
```bash
|
|
23
|
+
# Homebrew (use the fully-qualified tap name to avoid name conflicts)
|
|
116
24
|
brew tap the-ai-project-co/tap
|
|
117
|
-
brew install nimbus
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### Shell script (auto-detects best method)
|
|
25
|
+
brew install the-ai-project-co/tap/nimbus
|
|
121
26
|
|
|
122
|
-
|
|
27
|
+
# Shell script (auto-detects best method)
|
|
123
28
|
curl -fsSL https://raw.githubusercontent.com/the-ai-project-co/nimbus/main/scripts/install.sh | bash
|
|
124
29
|
```
|
|
125
30
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
Pre-built standalone binaries for macOS, Linux, and Windows are available on the
|
|
129
|
-
[GitHub Releases](https://github.com/the-ai-project-co/nimbus/releases) page.
|
|
130
|
-
Standalone binaries bundle the Bun runtime (~68 MB), so no extra dependencies
|
|
131
|
-
are needed.
|
|
132
|
-
|
|
133
|
-
> Note: compiled binaries use the readline chat interface. Install via Bun or
|
|
134
|
-
> npm for the full Ink TUI.
|
|
135
|
-
|
|
136
|
-
---
|
|
137
|
-
|
|
138
|
-
## Getting Started
|
|
139
|
-
|
|
140
|
-
### First run / onboarding
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
nimbus
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
The first time you run Nimbus, it launches an interactive onboarding that helps
|
|
147
|
-
you select an LLM provider and configure your API key. Credentials are stored in
|
|
148
|
-
`~/.nimbus/auth.json`.
|
|
149
|
-
|
|
150
|
-
### Setting up providers
|
|
151
|
-
|
|
152
|
-
You can configure providers through onboarding or by setting environment
|
|
153
|
-
variables directly:
|
|
154
|
-
|
|
155
|
-
```bash
|
|
156
|
-
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
Or log in interactively:
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
nimbus login
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
### Initialize a project
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
nimbus init
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
This detects your project type (TypeScript, Go, Python, Rust, Java, JavaScript),
|
|
172
|
-
infrastructure tooling (Terraform, Kubernetes, Helm, Docker, CI/CD), and cloud
|
|
173
|
-
providers (AWS, GCP, Azure), then generates a `NIMBUS.md` file with project
|
|
174
|
-
context that Nimbus uses to tailor its responses.
|
|
175
|
-
|
|
176
|
-
### Interactive chat
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
nimbus chat
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
Or just `nimbus` -- it launches the Ink TUI with the full agent loop, tool
|
|
183
|
-
execution, and streaming responses.
|
|
184
|
-
|
|
185
|
-
### Non-interactive mode
|
|
186
|
-
|
|
187
|
-
```bash
|
|
188
|
-
nimbus run "Create a Terraform module for an S3 bucket with versioning and encryption"
|
|
189
|
-
nimbus run "Fix the failing test in src/__tests__/router.test.ts" --auto-approve
|
|
190
|
-
nimbus run "Explain the architecture of this project" --format json
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
### One-off questions
|
|
194
|
-
|
|
195
|
-
```bash
|
|
196
|
-
nimbus ask "How do I set up an S3 bucket with versioning?"
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
### Check your environment
|
|
200
|
-
|
|
201
|
-
```bash
|
|
202
|
-
nimbus doctor
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
Verifies that required tools (git, terraform, kubectl, helm, cloud CLIs) are
|
|
206
|
-
available and that provider credentials are configured.
|
|
207
|
-
|
|
208
|
-
---
|
|
209
|
-
|
|
210
|
-
## Commands
|
|
211
|
-
|
|
212
|
-
### Chat and AI
|
|
213
|
-
|
|
214
|
-
| Command | Description |
|
|
215
|
-
| ----------------------- | ----------------------------------------- |
|
|
216
|
-
| `nimbus` | Launch interactive chat (default) |
|
|
217
|
-
| `nimbus chat` | Interactive AI chat session |
|
|
218
|
-
| `nimbus run "prompt"` | Non-interactive mode with a single prompt |
|
|
219
|
-
| `nimbus ask "question"` | Ask a one-off question |
|
|
220
|
-
| `nimbus explain <file>` | Explain a file or code snippet |
|
|
221
|
-
| `nimbus fix <file>` | Analyze and fix issues in a file |
|
|
222
|
-
| `nimbus analyze` | Analyze the current project |
|
|
223
|
-
|
|
224
|
-
### Configuration
|
|
225
|
-
|
|
226
|
-
| Command | Description |
|
|
227
|
-
| ---------------- | ------------------------------------------------------ |
|
|
228
|
-
| `nimbus init` | Initialize a project (detect type, generate NIMBUS.md) |
|
|
229
|
-
| `nimbus config` | View or set configuration |
|
|
230
|
-
| `nimbus login` | Authenticate with an LLM provider |
|
|
231
|
-
| `nimbus logout` | Remove stored credentials |
|
|
232
|
-
| `nimbus auth` | Manage authentication |
|
|
233
|
-
| `nimbus doctor` | Check environment and provider status |
|
|
234
|
-
| `nimbus upgrade` | Self-update to the latest version |
|
|
235
|
-
|
|
236
|
-
### Infrastructure Generation
|
|
237
|
-
|
|
238
|
-
| Command | Description |
|
|
239
|
-
| --------------------------- | ------------------------------------------------------- |
|
|
240
|
-
| `nimbus generate terraform` | Generate Terraform configurations from natural language |
|
|
241
|
-
| `nimbus generate k8s` | Generate Kubernetes manifests |
|
|
242
|
-
| `nimbus generate helm` | Generate Helm charts |
|
|
243
|
-
|
|
244
|
-
### Cloud Providers
|
|
245
|
-
|
|
246
|
-
| Command | Description |
|
|
247
|
-
| ------------------------ | -------------------------------------- |
|
|
248
|
-
| `nimbus aws <service>` | AWS operations (S3, EC2, Lambda, etc.) |
|
|
249
|
-
| `nimbus gcp <service>` | Google Cloud operations |
|
|
250
|
-
| `nimbus azure <service>` | Azure operations |
|
|
251
|
-
|
|
252
|
-
### Infrastructure Management
|
|
253
|
-
|
|
254
|
-
| Command | Description |
|
|
255
|
-
| ----------------------------------------------------- | -------------------------------------- |
|
|
256
|
-
| `nimbus tf init/plan/apply/validate/destroy/fmt` | Terraform operations |
|
|
257
|
-
| `nimbus k8s get/apply/delete/logs/scale/exec` | Kubernetes operations |
|
|
258
|
-
| `nimbus helm list/install/upgrade/uninstall/rollback` | Helm operations |
|
|
259
|
-
| `nimbus cost estimate/history` | Cost estimation and tracking |
|
|
260
|
-
| `nimbus drift detect/fix` | Configuration drift detection |
|
|
261
|
-
| `nimbus preview` | Deploy preview (blast radius analysis) |
|
|
262
|
-
|
|
263
|
-
### Git and Files
|
|
264
|
-
|
|
265
|
-
| Command | Description |
|
|
266
|
-
| ----------------------------------------------- | ---------------------- |
|
|
267
|
-
| `nimbus git status/add/commit/push/merge/stash` | Git operations |
|
|
268
|
-
| `nimbus fs read/write/list/search` | File system operations |
|
|
269
|
-
|
|
270
|
-
### GitHub
|
|
271
|
-
|
|
272
|
-
| Command | Description |
|
|
273
|
-
| ---------------------------------------- | ----------------------- |
|
|
274
|
-
| `nimbus gh pr list/create/view/merge` | Pull request operations |
|
|
275
|
-
| `nimbus gh issue list/create/view/close` | Issue operations |
|
|
276
|
-
| `nimbus gh repo view/clone` | Repository operations |
|
|
277
|
-
|
|
278
|
-
### Enterprise
|
|
279
|
-
|
|
280
|
-
| Command | Description |
|
|
281
|
-
| ---------------- | ----------------------------------- |
|
|
282
|
-
| `nimbus team` | Team management |
|
|
283
|
-
| `nimbus billing` | Billing and subscription management |
|
|
284
|
-
| `nimbus usage` | Usage statistics and token tracking |
|
|
285
|
-
| `nimbus audit` | Audit logs and compliance reports |
|
|
286
|
-
|
|
287
|
-
### Server
|
|
288
|
-
|
|
289
|
-
| Command | Description |
|
|
290
|
-
| -------------- | -------------------------------------------------- |
|
|
291
|
-
| `nimbus serve` | Start the HTTP API server (Elysia, SSE streaming) |
|
|
292
|
-
| `nimbus web` | Start the API server and open the browser-based UI |
|
|
293
|
-
|
|
294
|
-
### Utilities
|
|
295
|
-
|
|
296
|
-
| Command | Description |
|
|
297
|
-
| ----------------------- | ----------------------------------- |
|
|
298
|
-
| `nimbus version` | Print version and build date |
|
|
299
|
-
| `nimbus help` | Show help for all commands |
|
|
300
|
-
| `nimbus help <command>` | Show help for a specific command |
|
|
301
|
-
| `nimbus doctor` | Verify environment and dependencies |
|
|
302
|
-
| `nimbus upgrade` | Update Nimbus to the latest version |
|
|
303
|
-
|
|
304
|
-
Run `nimbus help` for the full command list, or `nimbus help <command>` for
|
|
305
|
-
details on any command.
|
|
306
|
-
|
|
307
|
-
---
|
|
308
|
-
|
|
309
|
-
## Modes
|
|
310
|
-
|
|
311
|
-
Nimbus uses a three-mode system that controls which tools are available,
|
|
312
|
-
enforcing a progressive trust model. Switching modes resets the permission
|
|
313
|
-
session so that previously approved tools require re-approval.
|
|
314
|
-
|
|
315
|
-
### Plan mode
|
|
316
|
-
|
|
317
|
-
Read-only exploration and analysis. The agent can read files, search codebases,
|
|
318
|
-
estimate costs, detect drift, and propose changes -- but it cannot modify
|
|
319
|
-
anything.
|
|
320
|
-
|
|
321
|
-
**Available tools:** `read_file`, `glob`, `grep`, `list_dir`, `webfetch`,
|
|
322
|
-
`cost_estimate`, `drift_detect`, `todo_read`, `todo_write`, `cloud_discover`
|
|
323
|
-
|
|
324
|
-
### Build mode (default)
|
|
325
|
-
|
|
326
|
-
Everything in Plan, plus file editing, shell access, git operations, and
|
|
327
|
-
non-destructive DevOps commands. The agent can generate Terraform configs, write
|
|
328
|
-
Kubernetes manifests, and validate them, but it cannot apply changes to live
|
|
329
|
-
infrastructure.
|
|
330
|
-
|
|
331
|
-
**Additional tools:** `edit_file`, `multi_edit`, `write_file`, `bash`, `git`,
|
|
332
|
-
`task`, `deploy_preview`, `terraform` (validate/fmt/plan only), `kubectl`
|
|
333
|
-
(get/describe only), `helm` (list/status/template only)
|
|
334
|
-
|
|
335
|
-
### Deploy mode
|
|
336
|
-
|
|
337
|
-
Full access to all 20 tools, including infrastructure-mutating operations.
|
|
338
|
-
Destructive actions still go through the permission engine and require explicit
|
|
339
|
-
user approval.
|
|
340
|
-
|
|
341
|
-
**Additional tools:** All terraform subcommands (apply, destroy), all kubectl
|
|
342
|
-
subcommands (apply, delete), all helm subcommands (install, upgrade, uninstall)
|
|
343
|
-
|
|
344
|
-
Switch modes in the TUI by pressing **Tab**, or use the `/mode` slash command.
|
|
345
|
-
|
|
346
|
-
---
|
|
347
|
-
|
|
348
|
-
## LLM Providers
|
|
349
|
-
|
|
350
|
-
Nimbus routes requests through an intelligent LLM router with automatic
|
|
351
|
-
fallback, cost optimization, circuit breaking, and retry with exponential
|
|
352
|
-
backoff.
|
|
353
|
-
|
|
354
|
-
| Provider | Environment Variable(s) | Notes |
|
|
355
|
-
| ------------ | ------------------------------ | ------------------------------------------------------ |
|
|
356
|
-
| Anthropic | `ANTHROPIC_API_KEY` | Claude models (Sonnet, Opus, Haiku). Default provider. |
|
|
357
|
-
| OpenAI | `OPENAI_API_KEY` | GPT-4o, GPT-4, GPT-3.5 |
|
|
358
|
-
| Google | `GOOGLE_API_KEY` | Gemini models |
|
|
359
|
-
| AWS Bedrock | `AWS_REGION` + IAM credentials | Claude, Llama, and others via AWS |
|
|
360
|
-
| Ollama | `OLLAMA_BASE_URL` (optional) | Local models, no API key needed |
|
|
361
|
-
| Groq | `GROQ_API_KEY` | Fast inference (Llama, Mixtral) |
|
|
362
|
-
| DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek models |
|
|
363
|
-
| OpenRouter | `OPENROUTER_API_KEY` | Multi-model proxy, access 100+ models |
|
|
364
|
-
| Together AI | `TOGETHER_API_KEY` | Llama, Mixtral, and more |
|
|
365
|
-
| Fireworks AI | `FIREWORKS_API_KEY` | Fast open-source model inference |
|
|
366
|
-
| Perplexity | `PERPLEXITY_API_KEY` | Online search-augmented models |
|
|
367
|
-
|
|
368
|
-
Any OpenAI-compatible endpoint can be added via the `OpenAICompatibleProvider`
|
|
369
|
-
class.
|
|
370
|
-
|
|
371
|
-
You can also configure providers through `nimbus login`, which stores
|
|
372
|
-
credentials in `~/.nimbus/auth.json`. The router checks `auth.json` first, then
|
|
373
|
-
falls back to environment variables.
|
|
374
|
-
|
|
375
|
-
### Model aliases
|
|
376
|
-
|
|
377
|
-
Nimbus supports short aliases for common models:
|
|
378
|
-
|
|
379
|
-
```bash
|
|
380
|
-
nimbus chat --model sonnet # resolves to claude-sonnet-4-20250514
|
|
381
|
-
nimbus chat --model opus # resolves to claude-opus-4-20250514
|
|
382
|
-
nimbus chat --model gpt4o # resolves to gpt-4o
|
|
383
|
-
nimbus chat --model gemini # resolves to gemini-pro
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
### Cost optimization
|
|
387
|
-
|
|
388
|
-
When enabled (`ENABLE_COST_OPTIMIZATION=true`), the router automatically selects
|
|
389
|
-
cheaper models for simple tasks (summarization, classification) and more capable
|
|
390
|
-
models for complex tasks (code generation, planning).
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## MCP Support
|
|
395
|
-
|
|
396
|
-
Nimbus supports the [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
397
|
-
for extending the agent with external tools. Configure MCP servers in
|
|
398
|
-
`.nimbus/mcp.json` (project-level) or `~/.nimbus/mcp.json` (global):
|
|
399
|
-
|
|
400
|
-
```json
|
|
401
|
-
{
|
|
402
|
-
"mcpServers": {
|
|
403
|
-
"filesystem": {
|
|
404
|
-
"command": "npx",
|
|
405
|
-
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
|
|
406
|
-
},
|
|
407
|
-
"github": {
|
|
408
|
-
"command": "npx",
|
|
409
|
-
"args": ["-y", "@modelcontextprotocol/server-github"],
|
|
410
|
-
"env": {
|
|
411
|
-
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
|
|
412
|
-
}
|
|
413
|
-
},
|
|
414
|
-
"remote-server": {
|
|
415
|
-
"type": "http",
|
|
416
|
-
"url": "https://mcp.example.com",
|
|
417
|
-
"token": "your-auth-token"
|
|
418
|
-
}
|
|
419
|
-
}
|
|
420
|
-
}
|
|
421
|
-
```
|
|
422
|
-
|
|
423
|
-
MCP servers are discovered from three locations, searched in order:
|
|
424
|
-
|
|
425
|
-
1. `.nimbus/mcp.json` (project directory)
|
|
426
|
-
2. `nimbus.json` (project directory)
|
|
427
|
-
3. `~/.nimbus/mcp.json` (global)
|
|
428
|
-
|
|
429
|
-
Servers support two transport modes: **command** (JSON-RPC over stdio) and
|
|
430
|
-
**http** (JSON-RPC over HTTP). Tools from connected servers are automatically
|
|
431
|
-
registered into the Nimbus tool registry and become available to the agent.
|
|
432
|
-
|
|
433
|
-
---
|
|
434
|
-
|
|
435
|
-
## Project Configuration (NIMBUS.md)
|
|
436
|
-
|
|
437
|
-
Running `nimbus init` in your project directory generates a `NIMBUS.md` file
|
|
438
|
-
that provides project-specific context to the AI agent. Nimbus auto-detects:
|
|
439
|
-
|
|
440
|
-
- **Project type** -- TypeScript, JavaScript, Go, Python, Rust, Java
|
|
441
|
-
- **Infrastructure tools** -- Terraform, Kubernetes, Helm, Docker, CI/CD
|
|
442
|
-
pipelines
|
|
443
|
-
- **Cloud providers** -- AWS, GCP, Azure (from config files and Terraform
|
|
444
|
-
providers)
|
|
445
|
-
- **Package manager** -- npm, yarn, pnpm, bun
|
|
446
|
-
- **Test framework** -- jest, vitest, mocha, pytest, go test, cargo test
|
|
447
|
-
- **Git repository status**
|
|
448
|
-
|
|
449
|
-
The generated `NIMBUS.md` file is included in the system prompt so the agent
|
|
450
|
-
understands your project's technology stack, conventions, and infrastructure
|
|
451
|
-
setup.
|
|
452
|
-
|
|
453
|
-
```bash
|
|
454
|
-
nimbus init # auto-detect and generate
|
|
455
|
-
nimbus init --force # overwrite existing NIMBUS.md
|
|
456
|
-
nimbus init --quiet # suppress console output
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
---
|
|
460
|
-
|
|
461
|
-
## Keyboard Shortcuts (TUI)
|
|
462
|
-
|
|
463
|
-
| Shortcut | Action |
|
|
464
|
-
| ------------- | --------------------------------------------- |
|
|
465
|
-
| **Tab** | Cycle modes (Plan -> Build -> Deploy -> Plan) |
|
|
466
|
-
| **Ctrl+C** | Interrupt current operation or exit |
|
|
467
|
-
| **Escape** | Cancel current operation |
|
|
468
|
-
| **Up / Down** | Browse input history |
|
|
469
|
-
| **Enter** | Send message |
|
|
470
|
-
| `/mode` | Switch mode via slash command |
|
|
471
|
-
| `/clear` | Clear the conversation |
|
|
472
|
-
| `/compact` | Manually trigger context compaction |
|
|
473
|
-
| `/help` | Show available slash commands |
|
|
31
|
+
Pre-built standalone binaries (~68 MB, no Node.js required) are on the [Releases](https://github.com/the-ai-project-co/nimbus/releases) page.
|
|
474
32
|
|
|
475
33
|
---
|
|
476
34
|
|
|
477
|
-
##
|
|
478
|
-
|
|
479
|
-
### Prerequisites
|
|
480
|
-
|
|
481
|
-
- Node.js >= 18
|
|
482
|
-
- Git
|
|
483
|
-
|
|
484
|
-
### Setup
|
|
485
|
-
|
|
486
|
-
```bash
|
|
487
|
-
git clone https://github.com/the-ai-project-co/nimbus.git
|
|
488
|
-
cd nimbus
|
|
489
|
-
npm install
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
### Run from source
|
|
493
|
-
|
|
494
|
-
```bash
|
|
495
|
-
# Run directly
|
|
496
|
-
npm run nimbus
|
|
497
|
-
|
|
498
|
-
# Run with arguments
|
|
499
|
-
npm run nimbus -- --help
|
|
500
|
-
npm run nimbus -- chat
|
|
501
|
-
npm run nimbus -- ask "explain this project"
|
|
502
|
-
```
|
|
503
|
-
|
|
504
|
-
### Test
|
|
35
|
+
## Quick Start
|
|
505
36
|
|
|
506
37
|
```bash
|
|
507
|
-
#
|
|
508
|
-
npm test
|
|
509
|
-
|
|
510
|
-
# Run with coverage
|
|
511
|
-
npm run test:coverage
|
|
512
|
-
|
|
513
|
-
# Watch mode
|
|
514
|
-
npm run test:watch
|
|
38
|
+
nimbus # launches onboarding on first run, TUI on subsequent runs
|
|
515
39
|
```
|
|
516
40
|
|
|
517
|
-
|
|
41
|
+
1. **First run** — onboarding wizard walks you through provider + API key setup
|
|
42
|
+
2. **Initialize your project** — `nimbus init` detects your stack and generates `NIMBUS.md`
|
|
43
|
+
3. **Start asking** — describe what you want in natural language
|
|
518
44
|
|
|
519
|
-
```bash
|
|
520
|
-
npm run lint
|
|
521
|
-
npm run format
|
|
522
|
-
npm run type-check
|
|
523
45
|
```
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
```bash
|
|
528
|
-
# Build standalone binary for current platform
|
|
529
|
-
./scripts/build-binary.sh
|
|
530
|
-
|
|
531
|
-
# Or
|
|
532
|
-
npm run build
|
|
46
|
+
"Run terraform plan and show me what will change"
|
|
47
|
+
"Check for pod restarts in the production namespace"
|
|
48
|
+
"Is there any infrastructure drift in my staging workspace?"
|
|
533
49
|
```
|
|
534
50
|
|
|
535
|
-
|
|
51
|
+
If `ANTHROPIC_API_KEY` (or any [supported provider key](docs/guides/configuration.md#llm-providers)) is already set, onboarding is skipped and you go straight to the agent.
|
|
536
52
|
|
|
537
53
|
---
|
|
538
54
|
|
|
539
|
-
##
|
|
540
|
-
|
|
541
|
-
Nimbus runs on Node.js >= 18 (with optional Bun support for compiled binaries).
|
|
542
|
-
All functionality runs in-process -- there are no HTTP microservices, no Docker
|
|
543
|
-
containers, and no external orchestrators. The entire application is a single
|
|
544
|
-
TypeScript process that manages LLM routing, tool execution, state persistence,
|
|
545
|
-
and the TUI.
|
|
55
|
+
## Learn More
|
|
546
56
|
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
agent/ Agent loop, system prompt, permissions, modes, subagents
|
|
555
|
-
llm/ LLM router, 11+ providers, model aliases, cost calculator
|
|
556
|
-
tools/ Tool implementations and schemas (11 standard + 9 DevOps)
|
|
557
|
-
state/ SQLite WAL database (16 tables at ~/.nimbus/nimbus.db)
|
|
558
|
-
ui/ Ink/React TUI components (8 components)
|
|
559
|
-
commands/ CLI command implementations
|
|
560
|
-
|
|
561
|
-
engine/ Planner, executor, orchestrator, verifier, safety, drift, cost
|
|
562
|
-
generator/ Terraform, Kubernetes, Helm generators with best practices
|
|
563
|
-
enterprise/ Auth, teams, billing, audit
|
|
564
|
-
auth/ Authentication (OAuth, SSO, credential store)
|
|
565
|
-
hooks/ Pre/post tool-use hooks (YAML config)
|
|
566
|
-
snapshots/ Git write-tree undo/redo
|
|
567
|
-
audit/ Security scanner, compliance checker, cost tracker, activity log
|
|
568
|
-
lsp/ Language server protocol (6 languages: TS, Go, Python, HCL, YAML, Docker)
|
|
569
|
-
sessions/ Multi-session management with conflict detection
|
|
570
|
-
sharing/ Session sharing (URL-safe IDs, 30-day TTL)
|
|
571
|
-
mcp/ MCP client (JSON-RPC over stdio/HTTP)
|
|
572
|
-
cli/ Non-interactive run, serve, web, init commands
|
|
573
|
-
compat/ Runtime compatibility layer (Bun / Node.js)
|
|
574
|
-
context/ Context database for long-term memory
|
|
575
|
-
watcher/ Filesystem watcher for live file tracking
|
|
576
|
-
|
|
577
|
-
build.ts Binary build script
|
|
578
|
-
__tests__/ 1408 tests
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
### Key design decisions
|
|
582
|
-
|
|
583
|
-
- **Single process** -- No IPC overhead. LLM calls, tool execution, and state
|
|
584
|
-
writes all happen in the same event loop.
|
|
585
|
-
- **SQLite with WAL** -- All state (sessions, usage, audit, config, sharing) is
|
|
586
|
-
stored in a single SQLite database at `~/.nimbus/nimbus.db` using WAL mode for
|
|
587
|
-
concurrent read/write.
|
|
588
|
-
- **Streaming-first** -- The agent loop streams LLM responses token-by-token
|
|
589
|
-
through the TUI. Tool calls appear inline as they execute.
|
|
590
|
-
- **Progressive trust** -- The three-mode system (Plan/Build/Deploy) combined
|
|
591
|
-
with the 4-tier permission engine ensures that destructive operations always
|
|
592
|
-
require explicit approval.
|
|
593
|
-
- **Provider fallback** -- The LLM router tries providers in order with circuit
|
|
594
|
-
breakers, exponential backoff, and automatic failover.
|
|
57
|
+
| Topic | Description |
|
|
58
|
+
|---|---|
|
|
59
|
+
| [Configuration & Providers](docs/guides/configuration.md) | LLM providers, API keys, config profiles, MCP servers |
|
|
60
|
+
| [Hooks & Extensibility](docs/guides/hooks.md) | Hook system, NIMBUS.md format, MCP plugins |
|
|
61
|
+
| [CLI Commands](docs/reference/commands.md) | Full CLI command reference with examples |
|
|
62
|
+
| [Tools Reference](docs/reference/tools.md) | All 33+ built-in tools with parameters |
|
|
63
|
+
| [Architecture](docs/architecture.md) | How Nimbus works internally, component flow, design decisions |
|
|
595
64
|
|
|
596
65
|
---
|
|
597
66
|
|
|
598
67
|
## License
|
|
599
68
|
|
|
600
69
|
[MIT](LICENSE)
|
|
601
|
-
|
|
602
|
-
---
|
|
603
|
-
|
|
604
|
-
## Links
|
|
605
|
-
|
|
606
|
-
- [npm Package](https://www.npmjs.com/package/@build-astron-co/nimbus)
|
|
607
|
-
- [GitHub](https://github.com/the-ai-project-co/nimbus)
|
|
608
|
-
- [Issues](https://github.com/the-ai-project-co/nimbus/issues)
|
|
609
|
-
- [Releases](https://github.com/the-ai-project-co/nimbus/releases)
|
|
610
|
-
- [Homebrew Tap](https://github.com/the-ai-project-co/homebrew-tap)
|
|
@@ -80,18 +80,24 @@ export async function runCompaction(messages, contextManager, options) {
|
|
|
80
80
|
if (options.infraContext) {
|
|
81
81
|
const ic = options.infraContext;
|
|
82
82
|
const infraLines = [];
|
|
83
|
-
if (ic.terraformWorkspace)
|
|
83
|
+
if (ic.terraformWorkspace) {
|
|
84
84
|
infraLines.push(`- Terraform workspace: ${ic.terraformWorkspace}`);
|
|
85
|
-
|
|
85
|
+
}
|
|
86
|
+
if (ic.kubectlContext) {
|
|
86
87
|
infraLines.push(`- kubectl context: ${ic.kubectlContext}`);
|
|
87
|
-
|
|
88
|
+
}
|
|
89
|
+
if (ic.awsProfile) {
|
|
88
90
|
infraLines.push(`- AWS profile: ${ic.awsProfile}`);
|
|
89
|
-
|
|
91
|
+
}
|
|
92
|
+
if (ic.awsRegion) {
|
|
90
93
|
infraLines.push(`- AWS region: ${ic.awsRegion}`);
|
|
91
|
-
|
|
94
|
+
}
|
|
95
|
+
if (ic.gcpProject) {
|
|
92
96
|
infraLines.push(`- GCP project: ${ic.gcpProject}`);
|
|
93
|
-
|
|
97
|
+
}
|
|
98
|
+
if (ic.azureSubscription) {
|
|
94
99
|
infraLines.push(`- Azure subscription: ${ic.azureSubscription}`);
|
|
100
|
+
}
|
|
95
101
|
if (infraLines.length > 0) {
|
|
96
102
|
userPrompt += `\n\n## ALWAYS PRESERVE IN SUMMARY (do not omit):\n${infraLines.join('\n')}`;
|
|
97
103
|
}
|
|
@@ -119,18 +125,24 @@ export async function runCompaction(messages, contextManager, options) {
|
|
|
119
125
|
if (options.infraContext) {
|
|
120
126
|
const ic = options.infraContext;
|
|
121
127
|
const infraLines = [];
|
|
122
|
-
if (ic.terraformWorkspace)
|
|
128
|
+
if (ic.terraformWorkspace) {
|
|
123
129
|
infraLines.push(`- Terraform workspace: ${ic.terraformWorkspace}`);
|
|
124
|
-
|
|
130
|
+
}
|
|
131
|
+
if (ic.kubectlContext) {
|
|
125
132
|
infraLines.push(`- kubectl context: ${ic.kubectlContext}`);
|
|
126
|
-
|
|
133
|
+
}
|
|
134
|
+
if (ic.awsProfile) {
|
|
127
135
|
infraLines.push(`- AWS profile: ${ic.awsProfile}`);
|
|
128
|
-
|
|
136
|
+
}
|
|
137
|
+
if (ic.awsRegion) {
|
|
129
138
|
infraLines.push(`- AWS region: ${ic.awsRegion}`);
|
|
130
|
-
|
|
139
|
+
}
|
|
140
|
+
if (ic.gcpProject) {
|
|
131
141
|
infraLines.push(`- GCP project: ${ic.gcpProject}`);
|
|
132
|
-
|
|
142
|
+
}
|
|
143
|
+
if (ic.azureSubscription) {
|
|
133
144
|
infraLines.push(`- Azure subscription: ${ic.azureSubscription}`);
|
|
145
|
+
}
|
|
134
146
|
if (infraLines.length > 0) {
|
|
135
147
|
finalSummary = `## Infrastructure Context\n${infraLines.join('\n')}\n\n${summary}`;
|
|
136
148
|
}
|