Installation

How-to. 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 supported host CLI: four first-class runtimes (Claude Code, Codex, Gemini, OpenCode) plus ten additional adapters (antigravity, augment, cline, codebuddy, copilot, cursor, kilo, qwen, trae, windsurf). Full list in Runtimes.

First install

Run from the project root:

npx nubos-pilot

The installer:

1. Detects which runtime is active (config file, env var, finally a default of codex). The detected runtime pre-fills the runtime question; the resolver fallback inside lib/runtime/index.cjs::detect() is also codex.
2. Asks a four-question interview: runtime(s), installation scope (local / global), model profile (frontier / quality / balanced / budget / inherit), response language (ISO-639). Flags --agent, --scope, --yes skip the corresponding prompts.
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

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.

What survives an update

The Install-Payload (.claude/nubos-pilot/) is owned by the installer — anything under it is fair game to overwrite. The Project-State (.nubos-pilot/) is never touched by update or uninstall:

Tree	Updated?	Notes
.claude/nubos-pilot/ (workflows, agents, skills, helpers)	Yes — overwritten from new payload	User-modified files backed up to .bak.<n> first
.opencode/nubos-pilot/ (if installed)	Yes — same logic
Managed block in CLAUDE.md / AGENTS.md / GEMINI.md	Yes — block between markers rewritten	Surrounding content preserved verbatim
~/.codex/config.toml [features] table	Repaired if trapped pattern detected	Idempotent
.nubos-pilot/PROJECT.md, REQUIREMENTS.md, RULES.md	No — never touched	Hand-owned
.nubos-pilot/roadmap.yaml	No — never touched	Read on every workflow
.nubos-pilot/milestones/M*/ (CONTEXT, PLANs, SUMMARIES, VERIFICATION, …)	No — never touched	Workflow-produced, milestone history
.nubos-pilot/config.json	No — never touched	Re-run interview by deleting the file first

Schema-version migration

STATE.md carries a schema_version frontmatter field. The reader (lib/state.cjs::parseStateMd) accepts both 1 and 2:

• v1 → v2 is migrated transparently on every read. The next write persists v2.
• v2 is the current shape. No action needed.
• Anything else throws schema-version-mismatch — if you see this, you have a pre-1 prototype state, run /np:doctor and consider re-creating from roadmap.yaml.

roadmap.yaml carries its own schema_version: 2. The legacy phases[] shape (pre-v2) is read with a fallback path; new writes always emit the v2 shape with milestones[].slices[].tasks[].

Major-version upgrades

When the underlying nubos-pilot package version jumps (e.g. 0.x → 1.x), check the changelog in the release notes. The general policy:

• Workflow signatures (np:plan-phase <N>) stay stable across minor versions.
• File-format changes are versioned — any breaking parser change ships with a new schema_version and a transparent reader path.
• Forward-only: a project upgraded to v1.x cannot cleanly downgrade to v0.x once any v1-only artifact has been written.

Run /np:doctor after every major upgrade. The version-mismatch check confirms the payload matches the package, and the milestone-layout check catches any structural drift.

Doctor

npx nubos-pilot doctor

A 12-check integrity scan covering manifest hash integrity, version mismatch, missing hook files, trapped Codex [features], askuser runtime, codebase-docs freshness, milestone layout, Nubosloop Critic agents, Nubosloop knowledge store, Nubosloop config (swarm.knowledge_adapter, loop.maxRounds), orphan tmp-file sweep, and output-schema drift. Use --fix to apply the auto-safe fixes; the full check list is on the Troubleshooting page.

Uninstall

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/
• lib/
• templates/
• workflows/
• agents/
• skills/
• docs/
• np-tools.cjs
• README.md

Everything else in the repo (tests, internal .planning/, contributor docs) stays out of the published payload.

Research tools (optional)

np-researcher can use third-party research servers exposed by the host CLI. They improve research quality but are optional; nubos-pilot never writes to the host's config files — you configure them yourself.

Enable context7 for np-researcher

np-researcher probes WebFetch + mcp__context7__* at spawn time. Without context7, the agent enters the Offline-Confirm Protocol and produces a local-only ## Research Coverage annotation. To enable it:

Claude Code — add the entry to .mcp.json (project-local) or ~/.claude.json (global):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}

Codex — append to ~/.codex/config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Re-open the host CLI so the new server is registered. Verify with the next /np:research-phase <N> — the resulting M<NNN>-RESEARCH.md should not contain a ## Research Coverage section.

Two more optional servers ship in the snippets: firecrawl (web scraping) and exa (semantic search). They improve research quality but are optional; configure them only if you have API keys (FIRECRAWL_API_KEY, EXA_API_KEY as env vars).

Other agents are local

Only np-researcher uses these research servers. Every other agent (planner, executor, verifier, and the rest) reads files, runs shell commands, and reasons over local context. Skipping the research servers entirely is a supported configuration; research then falls back to whatever the host CLI exposes through WebFetch.