Runtimes

nubos-pilot ships one source tree, one install payload, and four runtime adapters. The same workflows and agents work in all four host CLIs.

Supported runtimes

Runtime	Adapter	Install path	Managed Markdown
Claude Code	lib/runtime/claude.cjs	.claude/nubos-pilot/	CLAUDE.md
Codex	lib/runtime/codex.cjs	reuses .claude/ payload	AGENTS.md
Gemini	lib/runtime/gemini.cjs	reuses .claude/ payload	GEMINI.md
OpenCode	lib/runtime/opencode.cjs	.opencode/nubos-pilot/	opencode.json

The list is closed: KNOWN_RUNTIMES = ['claude', 'opencode', 'codex', 'gemini'] in lib/runtime/index.cjs. Adding a fifth would require an adapter implementing the contract enforced by _contract.test.cjs.

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 one of four .cjs files. This is the seam that keeps ADR-0001 (no daemon) and the portability story honest.

Codex / Gemini reuse

Codex and Gemini do not get their own payload directory. They consume the .claude/nubos-pilot/ payload directly and read their respective AGENTS.md / GEMINI.md for the managed-block instructions. The installer auto-generates these from CLAUDE.md (via lib/install/agents-md.cjs) when they are absent.

OpenCode

OpenCode gets its own payload at .opencode/nubos-pilot/ because its agent-paths convention differs. The installer also writes a default opencode.json 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.