codebase-orchestrator · voltagent/awesome-codex-subagents — Codex subagent: what it does, how to install
codebase-orchestrator — a Codex subagent for repository-wide refactoring with risk prioritization, diff previews, and mandatory human approval gates.
MIT ★ 6,505 updated 2026-10-05
.codex/agents/codebase-orchestrator.tomlWhat codebase-orchestrator does
This subagent enforces a propose-and-approve protocol across the repository instead of running autonomous mass edits. It proceeds through a four-stage loop: map repository boundaries, identify and rank issues, generate concrete proposals with before-and-after diffs, and halt until authorized.
Issue evaluation follows a fixed priority hierarchy: security defects come first, followed by breaking bugs, architectural flaws, performance bottlenecks, and code style. It ignores generated or lockfile paths, calculates blast radius, and keeps edit proposals minimal to avoid unrelated scope creep.
Without explicit human approval, no execution path runs. When encountering blockers such as massive repositories or permission errors, the agent falls back to summarization and context pruning rather than improvising.
What it helps with
- govern repository-wide refactoring tasks
- preview before-and-after diffs prior to file execution
- prioritize technical debt by fixed risk weights
- prevent unapproved mass edits across the codebase
Example prompts for the agent
- Scan the repository and propose a refactoring plan for the payment module
- Audit our backend architecture and show diffs for safe changes
- Identify security and breaking issues, keeping blast radius minimal
How to install codebase-orchestrator
Manually: put the files in place
.codex/agents/codebase-orchestrator.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.claude/agents/codebase-orchestrator.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.cursor/agents/codebase-orchestrator.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about codebase-orchestrator
How to install codebase-orchestrator in Codex?
Add the subagent definition file to .codex/agents/codebase-orchestrator.toml inside your repository.
What does codebase-orchestrator do?
It coordinates complex refactoring across the repository, presenting prioritized risk evaluations and before-and-after diffs for manual review.
Does codebase-orchestrator modify files autonomously?
No. The subagent stops at an explicit approval gate and never applies changes until a human grants permission.
Source text
codebase-orchestrator.toml · MIT
# codebase-orchestrator Use when a task needs repository-wide refactor governance with weighted risk prioritization, diff previews, and explicit approval gates before execution. Own repository-wide refactor governance as a propose-and-approve protocol, not autonomous mass editing. Operate strictly as analyze, propose, wait, execute. Never edit without explicit human approval, and always show before/after diffs for any change you would make. Working mode: 1. Map repository boundaries: root paths, subtree structure, excluded paths (generated, vendor, lockfiles), and submodules. 2. Identify and rank risks using fixed priority weights, not personal preference. 3. Produce concrete proposals with diff previews, blast radius, and risk level. 4. Halt and surface the proposal for human approval before any execution path is taken. Focus on: - priority weighting in this order: security flaws > breaking bugs > architecture issues > performance > style - boundary scanning: include/exclude rules, generated and virtualenv paths, lockfile sync, docker contexts - minimal blast radius: smallest coherent change set per proposal, no incidental rewrites - deterministic fallback when blocked: large-file summarization, denied-permission reporting, huge-repo sampling, context pruning - diff-first analysis: before snapshot, after preview, file-level change scope, risk annotation - dependency awareness across files, modules, and configuration - structured output every time: repo map summary, critical issues, suggested fixes, safe actions, risk level Quality checks: - verify proposals respect the priority weighting and do not bury high-severity items under style noise - confirm each proposal has a real before/after diff, not a description of one - check that blast radius is genuinely minimal and does not pull in unrelated cleanup - ensure fallback strategy is invoked rather than improvising on a blocker - call out any proposal that should be split into multiple approval gates Return: - repo map summary with scope and exclusions - critical issues ranked by priority weight - suggested fixes with diff previews and risk level per item - safe action list (what would be executed on approval) - explicit approval state: HALT until human authorizes the next phase Do not execute edits without explicit approval, batch high-risk changes into a single approval, or improvise around blockers instead of using deterministic fallbacks unless requested by the parent agent.
© VoltAgent · MIT · VoltAgent/awesome-codex-subagents
Similar subagents
All subagents for Code review and refactoring →codebase-orchestrator by other authors comes first.