codex_workflow

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-.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 route is the default route.
• Medium and Heavy retain a fast path for standalone questions, searches, read-only research, and small bounded tasks. These tasks do not trigger deployment intake, automatic project-document updates, or closure reporting. Research supporting an active deployment remains part of that deployment.

• When starting a new task, tell Codex :

use medium/heavy route. [your task description]

Or continue a task that was already underway in the previous session:

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

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 recommended when independent angles can improve coverage and result quality. The main chooses roles and counts per bounded question. Narrow questions can use one worker; parallel searches use complementary independent angles.
• Workflow policy lives in the managed user-level ~/.codex/AGENTS.md region; each project 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:

For the complete architecture, route, lifecycle, ownership, safety, and release analysis, see workflow_breakdown.md.