agent-bios

Single source of truth for the global instructions and scoped guides that drive multiple LLM CLI agents (Claude Code, Codex CLI) under one working discipline. Edit once; it applies to every agent in every environment.

Korean reference: ko/ mirrors every doc below — reference only, never installed or loaded.

Model

Two layers:

• Global instructions — claude/CLAUDE.md ↔ codex/AGENTS.md (mutual mirrors). Loaded every session. Hold only always-on invariants, decision principles, and guide pointers. Admission rule: a rule earns global placement only if it must work even when the agent fails to recognize the situation — a rule whose failure mode is recognition failure dies behind a pointer.
• Scoped guides — claude/guides/, codex/guides/. Loaded when a global pointer fires. All procedures, tables, numbers, and environment-specific content live here.

Principles

• Rule bodies never name concrete models or tools — only role slots and tiers. Bindings live in each guide's Environment Binding (dated; expire ~8 weeks or on a newer model). New model → update that row + date; leave rules alone. Declared exceptions: sections whose subject is a concrete tool surface (the cli guide's Codex direct-drive section) and optional-capability names inventoried in DEPENDENCIES.md (e.g. the spreadsheet-processing skill) — the Adopting checklist below covers swapping both.
• The two CLIs' files are mirrors — differing only in title and config-home variable ($CLAUDE_CONFIG_DIR ↔ $CODEX_HOME), plus one declared Codex-only standing-dispatch authorization required by Codex's trigger contract. scripts/check-parity.sh enforces that exact exception, mirror parity, pointer resolvability, frontmatter, shared anchor phrases on the global↔guide restatement pairs that remain, and Codex role-binding / wrapper-default projections. Parity enforces content synchronization only; it does not guarantee both harnesses respond to the same wording with the same strength.
• The global is a per-session token budget — it is re-sent every session and to every subagent, and each added bullet dilutes every other rule. A new global bullet must name the bullet it displaces (or why none does); procedures, tables, numbers, and worked examples belong in guides.
• Evidence Base (per guide) is the single owner of numbers. Measure with scripts/session-cost.py.
• English is canonical and installed; Korean (ko/) is reference only. The harness loads only fixed-name English files; the installer deploys English only.

Layout

| Path | Role | | --- | --- | | claude/CLAUDE.md, codex/AGENTS.md | global instructions (en) — installed & loaded | | claude/guides/*.md, codex/guides/*.md | scoped guides (en) — installed | | codex/agents/*.toml | Codex custom subagent role templates — installed | | ko/** | Korean mirror of every doc above + this README + DEPENDENCIES (reference only) | | config/agent-launch.toml, scripts/agent-launch.py, shell/agent-launch.zsh | shared Codex/Claude launch profile, preflight TUI, and zero-argument shell interception | | scripts/ | parity/cost tooling plus internal Codex wrappers deployed to $CODEX_HOME/bin/ | | DEPENDENCIES.md | external tools / host CLIs / model providers + verified versions |

config.toml and settings.json are machine-specific (trust lists, hook paths, secrets) and intentionally untracked.

Guides

| Guide | Scope | | --- | --- | | cli-multi-model-workflow | multi-model CLI workflow: Default Frame, role slots/tiers, delegation mechanics, driving Codex CLI directly, cache economy, unattended-batch safety, halt/resume, handoff contract, Environment Binding | | coding-staged-workflow | staged development: design → process → implement, review loop, severity contract, verification menus, stop conditions | | llm-capability-boundary (+ -patterns, -examples) | LLM/tool/code authority boundary: field authority, accepted output channels, structural enforcement, worked examples | | mock-realization-boundary | mock/fixture realization vs product semantic path | | svg-visualization-guide | SVG diagram / service-blueprint spec | | implementation-map | IMPLEMENTATION_MAP.html current-state dashboard |

Edit workflow

1. Edit the English canonical (claude/). Regenerate the Codex mirror, then preserve the single Codex-only standing authorization bullet under Multi-Model Workflow: sed -e '1s/# CLAUDE.md/# AGENTS.md/' -e 's|${CLAUDE_CONFIG_DIR:-$HOME/.claude}|${CODEX_HOME:-$HOME/.codex}|g' claude/CLAUDE.md > codex/AGENTS.md, and copy guides to codex/guides/.
2. Update the Korean mirror under ko/ the same way (globals under ko/claude→ko/codex, guides ko/claude/guides→ko/codex/guides, config-home swap for the codex side).
3. ./scripts/check-parity.sh must pass.
4. Commit, then deploy: agent-bios install (or agent-bios update from a clone).

Install (deploy)

The agent-bios CLI deploys this SSOT into your environment by copy — idempotent, backed up before overwrite, then verified. It ships as the npm package agent-bios; package and command are the same name. The $HOME deployment is always the explicit install command, never a postinstall side effect.

npm install -g agent-bios
agent-bios install     # deploy, back up replaced files, then verify
agent-bios onboard     # pick domain packages, packaged install, activation canary
agent-bios verify      # re-check the deployed state matches the source
agent-bios status      # show what is installed and where
agent-bios update      # git pull + reinstall (clone), or print the npm update line
agent-bios uninstall   # remove deployed files and the zsh hook

From a git clone, run ./scripts/install.sh install directly (the same CLI). install respects CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, and ZDOTDIR; --dry-run prints actions without changing anything. Deploy to every active environment in one sitting — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under ~/.local/share/agent-bios/backups/<timestamp>/, and the installed set is recorded in a manifest that uninstall consumes. The published npm package ships only the deploy set (never settings.json, config.toml, ko/, or benchmarks/).

In a TTY, zero-argument codex or claude opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use q to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via Other to type any model id the backend accepts; that text input preserves values that start with q, so Esc or Ctrl-C cancels immediately there, while submitting q cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — Software Engineer (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: Vanilla, the bare CLI with no launch contract, tier bindings, or applied permissions, plus Custom; SE-specific review defaults arrive later), Builder (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), Session distill — then a preset within it. Select Custom (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; Start with these settings is the final launch confirmation, Save these settings globally and start additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and Exit without launching cancels the launch. The rich preflight runs from a managed virtualenv (scripts/provision-venv.sh, at ~/.local/share/agent-launch/venv) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or TERM is dumb/unset, the launcher falls back to numbered prompts, where b is the back command. Backend command names are resolved from the calling environment's PATH; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in --agents JSON when delegation is enabled. Review runs cross-family by default (review_family, default cross; same restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — runs on the opposite family. The exception is slash-review, the host's own built-in review command (/code-review on Claude, with ultra for its deep multi-agent pass; /review on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under cross it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the codex-run reviewer wrapper resolved under $CODEX_HOME/bin, onto via an llmOverride to the configured openai seat, ultracode via the $ultracode-for-codex Codex skill); a Codex main dispatches Anthropic/Claude review (native via claude -p --permission-mode plan, onto via an llmOverride to the anthropic seat, ultracode via claude --effort ultracode -p — Claude Code's headless /workflows ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, llmOverride, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.

At the shell-wrapper boundary, every argument-bearing command (codex exec ..., claude -p ...) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, --dangerously-skip-permissions. codex --no-tui ... / claude --no-tui ... explicitly take that direct path, and AGENT_LAUNCH_TUI=0 disables zero-argument TUI interception for a process tree.

Direct agent-launch calls still require a valid profile to resolve the backend command and its default arguments. --preset, --custom, or --dry-run select the configured-launch path even when non-TTY or combined with --no-tui; a non-TTY bare --dry-run deterministically uses Balanced, and a custom profile without that preset must pass --preset NAME. Forwarded backend arguments are expert overrides appended after projected defaults and may supersede them; the summary discloses this when arguments are present. For scripted configured launches, call $HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ... or add $HOME/.local/bin to PATH. The summary goes to stderr so backend stdout stays machine-consumable.

Add $CODEX_DIR/bin to PATH or invoke the wrappers by absolute path. codex-helm follows the local CLI default and launches the HELM main with --dangerously-bypass-approvals-and-sandbox; an explicit --sandbox MODE disables bypass for that run regardless of flag order. AGENTS.md gives root/main local Codex sessions standing ordinary-subagent authorization when the delegation gates fire. A non-Ultra HELM main sets native multi-agent off by default and instructs HELM to send tiered dispatch through the internal codex-run adapter, where the selected model, effort, and sandbox are pinned; native multi-agent defaults on only when the HELM main itself is explicitly Ultra. FRONTIER is instructed to run as a separate gpt-5.6-sol root that is always read-only, at max by default, Ultra for genuinely divisible complex work, or a lower supported effort when cost or latency dominates. Because the HELM main has bypass authority and arbitrary expert -c by design, this dispatch route is an instruction-backed, live-E2E-verified default rather than a security boundary. Keep codex-run as the low-level internal adapter, not as a user-facing policy boundary. Both wrappers accept -c key=value as an expert override, and that override may intentionally change wrapper defaults for a single run.

agent-bios verify runs the post-deploy gate (also run at the end of install): every guides/*.md referenced by the deployed global exists in that environment's guides/; required agent files frontier.toml, workhorse.toml, sweep.toml, and reviewer.toml exist under $CODEX_DIR/agents/ and parse as TOML; frontier.toml deliberately omits model_reasoning_effort for native surfaces that accept per-spawn effort; each required codex exec --help flag in DEPENDENCIES.md is present; and $CODEX_DIR/bin/codex-helm --dry-run --mode review "probe" succeeds as a credential-free assembly check (not a live Codex call). install overwrites each guide's Environment Binding; keep per-environment binding edits in the repo copy or an untracked file.

Adopting elsewhere

Keep the rule layers. Swap checklist: each guide's Environment Binding ((private) entries are the author's examples); the response-language preference and the "설계" design-trigger word in the global file; skill/MCP names inventoried in DEPENDENCIES.md (the spreadsheet-processing skill, the review MCP). Then re-measure Evidence Base numbers in your environment before tuning.

Scope

Only stable configuration, config-managed credentials, and global agent instructions. No runtime state, logs, sessions, caches, generated artifacts, or temp paths.