Runtimes

nubos-pilot ships one source tree, one install payload, and a runtime-adapter layer that currently supports fourteen host CLIs. The same workflows and agents work in every supported runtime.

Supported runtimes

First-class runtimes (full adapter + managed-markdown):

Runtime	id	Local install path	Managed Markdown
Claude Code	claude	.claude/nubos-pilot	CLAUDE.md
Codex	codex	.codex/nubos-pilot	AGENTS.md
Gemini	gemini	.gemini/nubos-pilot	GEMINI.md
OpenCode	opencode	.opencode/nubos-pilot	AGENTS.md

Additional runtimes (selectable via --agent <id>):

Runtime	id	Local install path	Managed Markdown
Antigravity	antigravity	.agent/nubos-pilot	AGENTS.md
Augment	augment	.augment/nubos-pilot	AGENTS.md
Cline	cline	./.clinerules-nubos-pilot	.clinerules
CodeBuddy	codebuddy	.codebuddy/nubos-pilot	AGENTS.md
Copilot	copilot	.github/nubos-pilot	copilot-instructions.md
Cursor	cursor	.cursor/nubos-pilot	rules/nubos-pilot.mdc
Kilo	kilo	.kilo/nubos-pilot	AGENTS.md
Qwen Code	qwen	.qwen/nubos-pilot	AGENTS.md
Trae	trae	.trae/nubos-pilot	AGENTS.md
Windsurf	windsurf	.windsurf/.windsurf-nubos-pilot	.windsurfrules

Total: 14 runtimes.

The tables above are regenerated from lib/install/runtimes-registry.cjs by scripts/generate-docs.cjs. The list is closed: adding a runtime requires an adapter that implements the contract enforced by _contract.test.cjs, plus an entry in the registry.

Detection

detect({ cwd }) resolves the active runtime in priority order:

1. .nubos-pilot/config.json — if runtime is set and known, win.
2. Live env — lib/askuser.getRuntime() introspects the host process (e.g. environment markers Claude Code, Codex etc. set).
3. Fallback — codex (source: 'default').

The source field on the result tells you which path won — useful for np:doctor diagnostics.

What an adapter does

Adapters encapsulate runtime-specific concerns:

• Slash-command syntax — how the host CLI registers a np:* command.
• Question/answer transport — askUser over the host's prompt UI.
• Tool surface — which built-in tools (Read, Write, Bash, …) are exposed and under what names.
• Hook lifecycle (where supported).

Anything that would be runtime-specific in workflow Markdown or agent frontmatter is forbidden; it lives here, in the per-runtime adapter file. This is the seam that keeps ADR-0001 (no daemon) and the portability story honest.

Per-runtime payload directories

Each runtime installs its payload into its own directory, named in the localDir field of lib/install/runtimes-registry.cjs: .claude/nubos-pilot for Claude Code, .codex/nubos-pilot for Codex, .gemini/nubos-pilot for Gemini, .opencode/nubos-pilot for OpenCode (see the Local install path column in the tables above). The payloads do not share a directory.

The managed-block instructions live in a separate file per runtime: CLAUDE.md for Claude Code, AGENTS.md for Codex and OpenCode, GEMINI.md for Gemini. The installer auto-generates AGENTS.md / GEMINI.md from CLAUDE.md (via lib/install/agents-md.cjs) when they are absent.

OpenCode

OpenCode also gets a default opencode.json written at the project root if none exists:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "paths": [".claude/agents/"]
  }
}

Runtime-specific config repair

The installer does one runtime-specific repair: if ~/.codex/config.toml contains the well-known trapped [features] table, it rewrites the section in place via lib/install/codex-toml.cjs. The repair is idempotent and logged on stderr.