Codex Agent Ops: A Portable Operating System for AI Agents

Codex Agent Ops is a portable operating system designed for Codex AI agents. It transforms Git repositories into working infrastructure for agents, addressing challenges in cross-session and cross-machine context continuity, project coordination, and knowledge accumulation. Its core is to turn agent sessions into portable and recoverable forms, providing structured directories, collaboration protocols, etc., to support efficient multi-agent collaboration.

As the capabilities of AI programming agents like Codex grow, managing context continuity across multiple sessions, project coordination, and knowledge accumulation has become a key issue. Traditional sessions are often tied to specific machines or chat histories, leading to pain points such as repeated setup, scattered states, unorganized workflows, and unclear roles in multi-agent collaboration. Codex Agent Ops, as an open-source project, aims to build cross-session working infrastructure.

Codex Agent Ops uses a hierarchical directory structure:

• Project Layer (projects/): Each project has an independent folder containing an introduction, status, next actions, etc., with clear code repository locations.
• Knowledge Layer (knowledge/): Stores cross-project reusable knowledge (e.g., release processes, checklists).
• Metadata Layer (metadata/): Provides machine-searchable metadata such as context_index.md and repo_catalog.jsonl to help agents quickly locate information.
• Coordination Layer (coordination/): Core of multi-agent collaboration, used for heartbeats, task claiming, role division, etc. autonomy_roadmap.md defines priorities.
• Skills & Scripts Layer (skills/, scripts/): Stores reusable workflows, prompt patterns, and helper scripts.
• Inbox Layer (inbox/): current_focus.md records the current operation context, supporting session handover.

Codex Agent Ops defines a multi-agent collaboration model:

• Role Division: The lead agent is responsible for project channels, user communication, task prioritization, and decision-making; expert agents focus on narrow domains (e.g., web research, code audits) and output concise result reports.
• Persistent Handover: Task assignments and results are written to persistent storage (project introductions to projects/, lessons learned to knowledge/, handover information to coordination/), avoiding reliance on chat history.

Two innovative features:

1. Startup Layer & Machine Synchronization: Startup configurations are managed via the templates/codex-home/ directory. scripts/refresh_codex_home.ps1 synchronizes configurations to ~/.codex, and install_codex_bootstrap.ps1 installs wrappers and automatically checks for updates, enabling cross-machine configuration migration.
2. Automated Monitoring: Uses GitHub Actions workflows (biweekly-watch.yml) to regularly monitor changes in Codex, App Store, and Play Store. Reports are stored in reports/, and logs are recorded in knowledge/biweekly_watch_log.md.

When starting a new session, agents should read documents in the following order:

1. README.md (Overall Introduction)
2. knowledge/new_machine_bootstrap.md (New Machine Setup)
3. inbox/current_focus.md (Current Focus)
4. metadata/context_index.md (Context Index)
5. Relevant Project Introductions
6. Coordination Protocols
7. Matching Knowledge, Skills, or Script Notes This process ensures agents quickly obtain necessary context and avoid information overload.

Codex Agent Ops represents a new paradigm for AI collaboration: treating agents as computing entities that require OS support, rather than just chat backends. Its value lies not only in implementation but also in the shift in design philosophy, which is of great significance for building reliable and scalable AI-assisted workflows. It provides a reference implementation for teams exploring multi-agent collaboration, cross-session management, and AI-native workflows.