Configuration

Reference. .nubos-pilot/config.json is the single source of truth for runtime, model selection, and workflow toggles. This page lists every key, its default, who reads it, and how to change it.

Where the file lives

Path	Created by	Purpose
.nubos-pilot/config.json	npx nubos-pilot install interview	Project-scoped configuration; committed to git

The installer writes the initial file. After install, edit it directly or via npx nubos-pilot update (which preserves answers and refreshes the payload).

Default shape

{
  "runtime": "claude",
  "runtimes": ["claude"],
  "scope": "local",
  "mcp": false,
  "model_profile": "frontier",
  "response_language": "en",
  "workflow": {
    "commit_docs": true,
    "commit_artifacts": true,
    "worktree_isolation": false,
    "research_tools": {
      "WebFetch": true,
      "Context7": true
    }
  },
  "agents": {
    "parallelization": true,
    "research": true,
    "plan_checker": true,
    "verifier": true
  }
}

Authoritative defaults live in lib/config-defaults.cjs. Keys absent from the file fall back to the values shown above — workflows never crash on a missing key.

Top-level keys

Key	Type	Default	Who reads it	Effect
runtime	string	from install detect	lib/runtime/index.cjs::detect	Active host CLI adapter. One of the 14 ids in KNOWN_RUNTIMES.
runtimes	string[]	[runtime]	bin/install.js	List of runtimes to install for in multi-runtime mode (--agents flag).
runtime_source	string	config | env | default	lib/runtime/index.cjs	Diagnostic — which detection path won. Read-only after install.
scope	local | global	local	bin/install.js	local writes payload into project; global writes to runtime's home directory.
mcp	boolean	false	install hooks	Whether to write MCP-server config snippets during install.
model_profile	enum	frontier	np-tools.cjs resolve-model	Tier → model resolution. See Tier × Profile matrix.
response_language	ISO-639 string	en	lib/language.cjs, every workflow body	Language of workflow prose, prompts, dashboard labels, stats markdown.

workflow.*

Key	Type	Default	Who reads it	Effect
workflow.commit_docs	boolean	true	install / re-install path	Whether the installer commits managed-block updates to CLAUDE.md / AGENTS.md / GEMINI.md.
workflow.commit_artifacts	boolean	true	lib/commit-policy.cjs	Whether non-task artifacts (CONTEXT, PLAN, ROADMAP, etc.) are committed by their producing workflow. Set to false to keep planning artifacts out of git. See ADR-0004.
workflow.worktree_isolation	boolean	false	lib/worktree.cjs::worktreeIsolationEnabled	Opt-in per-slice git worktree isolation during /np:execute-phase. See ADR-0008.
workflow.text_mode	boolean	(unset)	lib/text-mode.cjs	Forces plain-text prompt rendering. When unset, falls back to process.env.CLAUDECODE. Set to true for non-TTY shells, false to override an inherited CLAUDECODE.
workflow.research_tools.WebFetch	boolean	true	np-researcher startup probe	Whether the researcher tries WebFetch. Disabling forces local-only research. Overridden by env NP_TOOLS_WEBFETCH.
workflow.research_tools.Context7	boolean	true	np-researcher startup probe	Whether the researcher tries Context7 MCP. Overridden by env NP_TOOLS_CONTEXT7.

Agent skills

config.json may carry an agent_skills map that lists additional skill files an agent should load at spawn time:

{
  "agent_skills": {
    "np-researcher": ["nubos-research-skill"],
    "np-executor":   ["nubos-rails-skill", "nubos-typescript-skill"]
  }
}

The map is read by lib/agents.cjs::getAgentSkills(name) and surfaced through np-tools.cjs agent-skills <name>. Workflows that spawn the agent embed the resolved skill list into the spawn prompt — the agent then loads each skill before performing the task.

Skills are runtime-managed: each entry is a string the host CLI can resolve to a skill file (Claude Code's skill-loader, Codex equivalent, etc.). nubos-pilot does not validate the strings — unknown skill ids are passed through and rejected by the runtime if invalid.

Default is no extra skills. Add the map only when you have project-specific skills you want every spawn of a given agent to load.

agents.*

Optional kill-switches for parts of the workflow pipeline. Default is "everything on".

Key	Type	Default	Effect when false
agents.parallelization	boolean	true	/np:execute-phase runs tasks within a slice serially instead of parallel.
agents.research	boolean	true	/np:plan-phase skips the research gate prompt.
agents.plan_checker	boolean	true	/np:plan-phase ships planner output without the adversarial review loop.
agents.verifier	boolean	true	/np:verify-work becomes a no-op stub.

These are escape hatches for constrained environments — leaving them on is the recommended default.

Reading values

Programmatically, from inside a workflow:

node np-tools.cjs config-get model_profile
node np-tools.cjs config-get workflow.commit_artifacts
node np-tools.cjs config-get workflow.research_tools.WebFetch

Dotted key paths are resolved by bin/np-tools/config.cjs. Forbidden segments (anything not matching /^[a-zA-Z0-9_-]+$/ or with a __proto__ lookalike) raise config-forbidden-key.

Writing values

There is no dedicated config-set command. To change a value:

1. Edit .nubos-pilot/config.json directly with your editor of choice.
2. Or run npx nubos-pilot update and re-answer the install questions.

The file is small enough that hand-editing is the supported path. Workflows do not mutate it during normal operation — keeping it human-owned is part of the three-trees invariant.

Environment variable overrides

A handful of values can be overridden by env vars at workflow-spawn time, useful for CI:

Env var	Overrides	Notes
CLAUDECODE	workflow.text_mode	Set automatically by Claude Code; affects prompt rendering.
NP_TOOLS_WEBFETCH	workflow.research_tools.WebFetch	0/1/true/false. Forces researcher probe on/off.
NP_TOOLS_CONTEXT7	workflow.research_tools.Context7	Same shape.

Env vars win over config.json; config.json wins over compiled defaults.

Validation

bin/np-tools/config.cjs reads the file with JSON.parse on every call — there is no schema validator. Malformed JSON throws config-parse-error; an unknown dotted-key segment returns null (not an error). New keys can be added freely; old keys can be left in place without runtime impact.