SIMPLE ─── EASY ─── EFFICIENT
(to use) (to install) (token consumption)
Built for token-efficient agent orchestration, with swarm execution, persistent context support, and compact knowledge handoffs between agents. agent_docs/ provides durable project memory for goals, architecture, decisions, progress, and session handoffs.
⭐ For lightweight tasks, it won’t overdo things. Light route is default.
1. Quick installation ⚙️
Open Codex CLI / Codex app from your project directory
Change permision to approve for me or full access.
▶️ Send:
Download and extract the latest codex_workflow-<version>.zip asset from https://github.com/viettran-edgeAI/codex_workflow/releases. Verify it against SHA256SUMS, then read the bundled codex_workflow/operate/bootstrap.md and follow it to complete the initial installation.⭐ Recommended: use 5.6 Luna xhigh for installation.
🔄 Restart Codex after installation
The initial bootstrap will include creating the project documentation framework agent_docs/ using archivist subagent. Once that bootstrap is complete, the current project is ready to use. Whenever you need to install this workflow for a new project, simply open Codex and send: codex_workflow --install
Requires Python 3.11 or newer for deterministic lifecycle operations.
Note: If you cannot upgrade directly to a newer version. Run codex_workflow --remove to uninstall it first, then install the newer version.
2. Workflow usage
This workflow has 3 routes:
- Light route: No workflow mode, minimal context.
- Heavy route: Delegate bounded production and verification to Executors and Testers, with Explorer for context, Investigator for solution research, and Archivist for documentation. The main agent owns orchestration, synthesis, and decisions.
- Medium route: Use Explorer, Investigator, and Archivist for read-only discovery, solution research, and documentation while the main agent handles implementation and verification. Choose this route when you want workflow-mode context support without delegating production work, like front-end design, visualization, or 3D works, but it will burn tokens faster than Heavy route.
How to use
- Normally, for simple work, general Q&A, you don't need to do anything.
light routeis the default route. - Medium and Heavy retain a fast path for standalone questions, searches,
--------------------------------
- When starting a new task, tell Codex :
use medium/heavy route. [your task description]use medium/heavy route. Continue ongoing work.Codex stays on the selected route until you change it
---------------
⭐ Recommendation: Assign very large and complex tasks to the heavy route to make the most of its capabilities and maximize token usage savings. Don't hesitate to choose Sol xhigh / Astra high for this route. Using much lower reasoning efforts will not actually save tokens and will severely reduce its coordination capabilities.
In Heavy, workers return compact evidence-linked reports directly to the main agent through Codex's parent-child result channel. The main batches related workers and makes one decision after the relevant reports arrive. !Heavy route
Heavy route
What's special about the system:
- Built-in project memory in Medium and Heavy:
agent_docs/keeps project goals, architecture, progress, decisions, and the latest handoff across sessions. Its framework instructions live in those route documents. - Flexibility: The system doesn't force the main agent into a rigid process: requiring coordination in this way, that way... It provides it with resources and power (specialized agents) and fine-tuning and guidance based on hundreds of trials.
- Fine-tuned balance: Main agent's control <---> costs & task completion capabilities. based on analysis and observation, not on feeling.
- Knowledge distribution: Each task package from the main agent to the workers includes a task completion guide.
- Batching guidelines prevent excessive main agent rollout.
- For difficult or broad questions, parallel workers (e.g., 2, 3, or more) are
- Workflow policy lives in the managed user-level
~/.codex/AGENTS.mdregion;
AGENTS.md remains native, project-owned personalization.
- Worker reports preserve material evidence while referencing bulky logs and artifacts instead of copying them.
- The Senior Executor serves as a fallback for exceptionally difficult problems where stronger reasoning is required.
- Addresses the issue of the main agent waking up workers too often.
- Built-in token report: End-of-session token statistics for each agent, allowing you to monitor how much each agent rolls out and how they use their tokens.
Light benchmark
Batching guidelines techniques(since 1.1.3 version) significantly reduce the main agent's rollout, which in turn reduces the main agent's cached input tokens, a major component of the operation cost, see New workflow below :The current benchmark is an initial case study. See the benchmark coverage proposal for ideas on testing more tasks and AI providers.
3. More details
Send these exact commands to Codex from the relevant project directory:
| Command | Purpose |
| --- | --- |
| codex_workflow --install | Install workflow in the current project and initialize its documentation framework. |
| codex_workflow --check-update | Check for a newer release without installing it. |
| codex_workflow --version | Report the currently installed workflow version. |
| codex_workflow --update | Install a newer release for the user and current project, or bring the current project up to an already installed release. |
| codex_workflow --remove | Remove the installed workflow after a destructive dry-run and confirmation. |
For the complete architecture, route, lifecycle, ownership, safety, and release analysis, see workflow_breakdown.md.