agent-manager: Instructions file for Codex

Agent notes

Project context for coding agents. Human setup and PR conventions live in .github/CONTRIBUTING.md, and what a review looks for in REVIEW.md. Fill the Scope section of the pull request template: a review reads it to tell the change you meant from the change you made.

Product boundary

Keep agent-manager a thin wrapper around the supported TUIs. Preserve upstream defaults and user configuration; avoid hardcoded models, version-specific behavior, and recreating upstream settings. Apply the Thin Wrapper Principle to every integration, including shared controls, capability discovery, and status detection. Provider-specific features multiply ongoing maintenance. Supporting a TUI does not mean mirroring its feature set; prefer workspace features shared across tools.

What every change covers

A feature, a tool, or a fix is done when it holds on the whole matrix. The matrix is every CLI in builtinTools (internal/config/config.go), every platform .goreleaser.yaml builds plus WSL2, every terminal that reaches the manager, local or over SSH, and both input methods. A change that covers a subset names what it leaves out in the PR description and what covering the rest would take. Disclosure alone does not approve partial tool coverage. REVIEW.md defines the allowed exceptions.

• Keyboard and mouse. Every action a key performs is reachable with the mouse, and every clickable surface has a key. A new row, panel, button, or handle ships with both, and the footer and the ? key map name the key.
• Dynamic over hardcoded. Anything that varies by tool, version, or user is discovered at runtime or read from the tool itself: models, thinking modes, capabilities, prompts, screens. A maintained list of values that an upstream release can change is a defect. Where discovery has no stable, documented interface, the feature stays in the underlying TUI.
• The current CLI release. Each CLI is supported at its latest stable release. None publishes a long-term-support line. When an upstream release changes a flag, a subcommand, a file layout, or a screen, the adapter moves to the new behavior and drops the old one, with no branch for older releases. The same change sets the tool's minimum_version in internal/config/builtin.go to the first release it needs, so a spawn on an older CLI opens the update dialog instead of failing.
• Configurable in the UI, or not configurable. A setting a user can change lives in Settings (s), is stored by the manager, and takes effect from the picker, the way the keybindings and editor rows do. The value lives in state.db, where the manager, the CLI and the MCP server all read it, and agent-manager settings reads and writes it from a shell. Every key is named in ui.SettingSpecs with the values it takes, so the shell refuses what the modal would never write. A value that is a command, a token or a URL stays off the modal and is set from the shell alone, so the modal does not grow a row per knob. A new per-user file, environment variable, or hand-edited block is the wrong shape; put the choice on a Settings row, behind agent-manager settings, or pick a default in code.
• Every tool. New shared behavior covers every applicable tool in the same PR. A field, status rule, or command added to one [tools.*] block is added to every tool it applies to. A fix to one tool's adapter or support for a new CLI can stay narrow. Any other partial feature needs evidence and an explicit maintainer decision before merge. Reuse shared paths first. A working first adapter or an unchanged fallback for other tools is not coverage of the new behavior. If the contributor cannot or does not plan to cover the other applicable tools, start with an issue. An optional draft PR can provide a reference implementation linked to that issue. Mark it as reference only with its missing coverage. Keep it in draft until coverage is complete or the maintainer accepts an exception.
• Every platform. A runtime.GOOS branch, a platform-only command, or a path built from one platform's layout needs its counterpart, or the description names the platform it skips. WSL2 is a platform of its own: the binary is the Linux one, but the clipboard, notifications, and host stats go through Windows interop (internal/wsl detects it), so a Linux branch is checked there too.
• Every terminal. The manager draws through tmux into whatever terminal the user runs, and over SSH that terminal is on another machine. A feature that talks to the terminal (clipboard, links, notifications, themes, mouse) works on the plain path first, and a branch keyed on TERM_PROGRAM, TERM, or SSH_CONNECTION is an addition to that path, never the only way the feature works. A tmux version gate names the version and keeps the feature usable on tmux 3.1, the oldest docs/install.md supports.