Agent handbook
Use this guide to change or evaluate the managed stack. For day-to-day operation, start with the AI workbench.
Choose an agent
Section titled “Choose an agent”| Agent | Choose it for | Managed configuration |
|---|---|---|
| Codex | profile-led implementation, focused child roles, and managed MCP profiles | home/dot_codex/ |
| Claude Code | plugin/hook workflows and source-grounded or adversarial local roles | home/dot_claude/ |
| Cursor | IDE/Agents Window, Composer 2.5 subagents, and self-hosted computer use | home/dot_cursor/ |
| OpenCode | generated MCP namespaces and a constrained review agent | home/dot_config/opencode/ |
| Pi | its rendered local-MLX or declared cloud-provider setup | home/dot_pi/agent/ |
Choose the harness whose configuration and interaction model suit the task, then inspect the active session before relying on its tools or account state.
Start from the source of truth
Section titled “Start from the source of truth”Edit the declared input, then render or reconcile it. Repairs inside ~/.codex or an installed skill directory do not survive sync.
Wide diagrams scroll horizontally. Focus the figure to use arrow keys.
| Need | Start here | It does not establish |
|---|---|---|
| Change guidance | Instruction architecture | Tool, account, or permission availability |
| Add a capability | Inventories and ownership | A live or authorized service |
| Select Codex routing | Profiles and roles | A sandbox or guaranteed savings |
| Assess a result | Validation | Correctness beyond the performed check |
Instructions govern reasoning; skills provide procedures; MCP servers provide configured tool routes; plugins provide marketplace extensions. None independently proves a login, a live service, or permission for an external action.
A disciplined task loop
Section titled “A disciplined task loop”- Read project instructions and inspect the worktree.
- Pick the narrowest profile and skill that fit.
- Use a direct command for deterministic work; delegate only an independent bounded unit.
- Keep the command, artifact, and assertion together.
- Exercise the result in its consumer and state what that observation does and does not prove.
For persistent state, use browser workspaces or durable tasks. For an interface-specific route, see browser and desktop evidence or domain workflows.