Skip to main content
subagent CX Codex

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

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/codebase-orchestrator.toml
Open on GitHub

What 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.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/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.

codebase-orchestrator VoltAgent Community codebase-orchestrator — a subagent that runs repository-wide refactors in stages: repo map, weighted risk priorities, diff previews, and an explicit approval gate before any edit. CX Codex ★ 26,718repo stars orchestrator CloudAI-X orchestrator plans multi-step work, hands independent tasks to specialist subagents, and combines their results. Use it for changes across modules or GitHub PR workflows. CX Codex ★ 1,424repo stars workflow-orchestrator davila7 workflow-orchestrator coordinates multi-step automation workflows with task dependencies, parallel jobs, and cron scheduling directly in your project. CX Codex +1 2,341installs utility-pm-workflow-orchestrator product-on-purpose utility-pm-workflow-orchestrator is a Claude Code skill that runs a sequence of pm-skills on one input, pausing for approval after each step. It stops on an empty or failed result. CX Codex +1 630installs it-ops-orchestrator VoltAgent Community it-ops-orchestrator coordinates multi-domain IT operations by routing tasks across PowerShell, Azure, M365, and Active Directory subagents. CX Codex 194installs research-orchestrator Alireza Rezvani The research-orchestrator plugin routes research questions to one of six specialist skills or runs its own search and synthesis workflow. It makes the routing choice visible. ★ 30,251repo stars full-funnel-campaign-orchestrator realkimbarrett full-funnel-campaign-orchestrator — an orchestrator skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. It runs nine specialist skills in sequence and assembles their output into one complete campaign. CX Codex +1 ★ 790repo stars

From the same set176

The whole set →
knowledge-synthesizer knowledge-synthesizer merges reports from several agents into one picture: what is confirmed, where findings disagree, and what to do next. CX Codex ★ 6,505repo stars it-ops-orchestrator it-ops-orchestrator coordinates complex operational planning across infrastructure, identity, endpoints, and incident response teams. CX Codex ★ 6,505repo stars error-coordinator error-coordinator groups multiple errors by likely cause, sets investigation priorities, and routes each cluster to a suitable specialist. Use it when symptoms pile up and the first fault is unclear. CX Codex ★ 6,505repo stars context-manager context-manager builds a short project brief that other subagents read before starting deeper work. CX Codex ★ 6,505repo stars agent-organizer The agent-organizer subagent helps a parent agent split large work into bounded threads, choose what to delegate, and coordinate the results. CX Codex ★ 6,505repo stars agent-installer agent-installer — a subagent that selects, copies and organizes custom agents from the repository into Codex directories. Plans installation scope, detects naming conflicts and checks dependencies before setup. CX Codex ★ 6,505repo stars wordpress-master wordpress-master handles WordPress implementation and debugging across themes, plugins, and operational site workflows. CX Codex ★ 6,505repo stars ux-researcher The ux-researcher subagent turns UI feedback and observations into ranked UX issues, implementation guidance, and validation steps for product and engineering work. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open