viettran-edgeAI/codex_workflow

codex_workflow – Token‑efficient agent orchestration for Codex

What it is

A Python‑based workflow package that extends the Codex AI‑assistant (the “Codex CLI/app”) with structured, multi‑agent execution modes. It lets a user pick a light, medium, or heavy route, each defining how many sub‑agents (Explorer, Investigator, Executor, Tester, Archivist, etc.) are spawned and how they share context.
The workflow stores project‑level memory in an agent_docs/ folder, preserving goals, architecture decisions, progress notes and hand‑off summaries across sessions.

Why it matters

Large language‑model agents charge per token. By delegating work to specialised sub‑agents and batching their results, codex_workflow reduces the main agent’s token consumption while still enabling complex, multi‑step tasks.
It provides a reproducible “swarm” pattern that can be reused across many projects without writing custom orchestration code.

Quick start (installation)

Download the latest release zip from the GitHub Releases page.
Verify the download with the provided SHA256SUMS file.
Extract the archive and follow the bundled codex_workflow/operate/bootstrap.md instructions (creates the agent_docs/ framework via the archivist sub‑agent).
Restart the Codex application.

From any project directory you can now run:

codex_workflow --install   # sets up the workflow for that project

Requirements – Python 3.11+ and a working Codex CLI/app installation.

How to use the workflow

Route	When to pick it	What it does
Light	Simple Q&A, quick fixes	No extra sub‑agents; the main Codex agent answers directly.
Medium	Tasks that need research or documentation but the main agent should still implement/verify	Spins up Explorer (search), Investigator (deep dive) and Archivist (note‑taking). Main agent does the coding/verification.
Heavy	Large, multi‑disciplinary projects (e.g., front‑end design, 3D visualisation, extensive testing)	Adds Executors and Testers to the Medium stack. The main agent only orchestrates, synthesises reports, and makes final decisions.

Switching routes – In the Codex chat, type:

use medium route. <your task description>

or replace medium with heavy. The selected route stays active until you change it.

Running commands – The workflow ships a small CLI wrapper:

codex_workflow --install      # set up for current project
codex_workflow --check-update # see if a newer release exists
codex_workflow --update       # upgrade the workflow
codex_workflow --remove       # clean uninstall
codex_workflow --version      # show installed version

Core features

Persistent project memory – agent_docs/ automatically records goals, architecture, decisions, progress and hand‑offs.
Token‑aware batching – Built‑in heuristics (since v1.1.3) limit how often the main agent spawns workers, cutting down on repeated context tokens.
Parallel sub‑agents – Up to three workers can run concurrently (the Codex platform caps a session at four agents total).
Evidence‑linked reports – Workers return concise summaries that reference full logs/artifacts, keeping the main agent’s context small.
Senior Executor fallback – For especially hard problems a higher‑capacity executor can be invoked automatically.
End‑of‑session token stats – After each run you get a breakdown of how many tokens each agent used.
Customisable policy files – Global settings live in ~/.codex/AGENTS.md; per‑project overrides are stored alongside agent_docs/.

Benchmarks & performance

The repository includes a light benchmark showing how the batching guidelines reduce the main agent’s cached input tokens, which are the biggest cost driver. A visual analysis (light_benchmark/analysis.png) and a proposal for extending benchmarks are provided.

Limitations & considerations

The workflow depends on the Codex platform’s current limit of four concurrent agents; larger swarms are not possible without platform changes.
Heavy‑route tasks consume more tokens overall because more sub‑agents are active, even though the main agent’s rollout is trimmed.
The installation process requires manual download of a zip asset and verification; there is no pip‑style installer yet.
Token‑saving heuristics are tuned for the authors’ experiments; results may vary with different LLM providers or model versions.

Where to learn more

Full architecture, lifecycle, and safety notes: workflow_breakdown.md
Benchmark ideas and how to contribute new tests: benchmarks/README.md
Agent‑lifecycle details: codex_workflow/agent_lifecycle.md

Bottom line – codex_workflow is a ready‑to‑use orchestration layer that lets Codex power‑users run multi‑agent, token‑efficient pipelines for anything from quick answers to heavyweight development projects, while automatically keeping a project‑wide knowledge base.