nubos-pilot

Appearance

Installation ​

nubos-pilot ships through npx. The single binary is bin/install.js, exposed as the nubos-pilot command. There is no global install step — every invocation runs against the current working directory.

Prerequisites ​

  • Node.js ≥ 22.
  • git available on $PATH.
  • A host CLI: Claude Code, Codex, Gemini, or OpenCode.

First install ​

Run from the project root:

bash
npx nubos-pilot

The installer:

  1. Detects which runtime is active (config file, env var, finally a default of codex).
  2. Asks an eleven-question interview (runtime, model profile, branching strategy, parallelization toggle, response language, …).
  3. Writes the answers to .nubos-pilot/config.json.
  4. Stages the install payload in .nubos-pilot/.staging.tmp/, manifests every file with a SHA-256, and atomically swaps it into .claude/nubos-pilot/.
  5. If an opencode/payload source exists, also installs .opencode/nubos-pilot/ and writes opencode.json when missing.
  6. Maintains a managed block in CLAUDE.md, AGENTS.md and GEMINI.md pointing at the installed tool.
  7. Repairs a known trapped [features] table in ~/.codex/config.toml if present.

The end state is three trees (ADR-0005):

  • Source — the nubos-pilot git repo (only contributors see this).
  • Install-Payload — .claude/nubos-pilot/ and optionally .opencode/nubos-pilot/ on the user machine.
  • Project-State — .nubos-pilot/ next to the user's code, mutated only by workflows.

Re-install / update ​

bash
npx nubos-pilot update

Re-runs the install in update mode. The interview is skipped (config.json already exists). The manifest diff drives three operations:

  • Added — file is new in the payload, written verbatim.
  • Changed — if the file on disk differs from both the old and new manifest hashes (i.e. user-modified), it is backed up to a .bak.<n> sidecar before being overwritten.
  • Stale — file present in the old manifest but missing in the new one is deleted.

Use npx nubos-pilot --dry-run to see the diff without touching the filesystem.

Doctor ​

bash
npx nubos-pilot doctor

Five-check integrity scan: manifest hash check, runtime presence, config schema, gitignore guard, payload symlink check. Use --fix to apply auto-safe fixes.

Uninstall ​

bash
npx nubos-pilot uninstall

Walks the manifest, unlinks every shipped file, removes the .claude/nubos-pilot/ and .opencode/nubos-pilot/ directories, and strips the managed block from CLAUDE.md / AGENTS.md / GEMINI.md. User-created backups (*.bak, *.bak.*) are preserved and listed.

The Project-State tree (.nubos-pilot/) is never touched by uninstall — your plans, ROADMAP and history survive.

What gets shipped ​

package.json declares the published files explicitly:

  • bin/install.js
  • bin/np-tools/
  • lib/install/
  • lib/askuser.cjs, lib/next.cjs, lib/progress.cjs
  • lib/runtime/
  • templates/
  • workflows/

Everything else in the repo (tests, ADRs, internal docs, .planning/) is contributor-only and never reaches an end-user install.