Codex CLI Subagent Demo

November 5, 2025 · View on GitHub

This repository demonstrates how to implement a subagent system for Codex CLI, enabling one Codex session to orchestrate specialized sub-agents for delegated task execution.

What This Demo Shows

This proof-of-concept implements:

  • Agent definitions as Markdown files with system prompts
  • Agent executor that spawns isolated Codex subprocesses
  • CLI wrappers for easy invocation and parent session setup
  • Two demo agents: word-counter and file-writer

Prerequisites

  • Codex CLI installed and authenticated (codex login)
  • Python 3.8+
  • PyYAML library

Setup

# Install dependencies
pip install -e .

Usage

# Launch Codex with proper configuration
bin/codex

Inside the Codex session, you can:

  • Ask it to use a specific agent: "Use the word-counter subagent to analyze this text: ..."
  • Let Codex decide when to use agents based on the task
  • See AGENTS.md for details on available subagents

The parent Codex has access to the bin/agent-exec command and knows about available subagents through the AGENTS.md documentation file.

NOTE: the first time a subagent is invoked, Codex will request network access escalation. It is recommended that you answer Yes, and don't ask again for this command to avoid repeated prompts.

How It Works

Parent Codex Session (bin/codex)
    └─> Invokes bin/agent-exec word-counter "..."
        └─> Spawns isolated Codex subprocess
            └─> Writes output to /tmp/word-counter-<pid>-<timestamp>.md
            └─> Returns result to parent

Key Components

  • agents/*.md - Agent definitions (YAML frontmatter + system prompt)
  • src/agent_executor.py - Core execution logic
  • bin/agent-exec - CLI wrapper for agent invocation
  • bin/codex - Helper to launch parent Codex with correct flags
  • tmp/codex-home/ - Isolated Codex home for sub-agents
  • AGENTS.md - Documentation that parent Codex reads to understand available subagents

Security & Isolation

  • Sub-agents run in workspace-write sandbox (no network access)
  • Credentials copied to tmp/codex-home/ (gitignored)
  • Output files written to /tmp/ with unique names
  • Each subagent runs in complete isolation from the parent

Adding New Agents

  1. Create agents/your-agent.md:
---
name: your-agent
reasoning_effort: medium
---
Your prompt here...

  1. Update AGENTS.md with documentation for the new agent

  2. The agent is immediately available via bin/agent-exec your-agent "query"

Troubleshooting

  • Authentication errors: Run codex login
  • Subagent fails: Check /tmp/<agent-name>-*.md output files for error details

Learning More

  • See AGENTS.md for detailed agent documentation (written for the parent Codex)
  • See .coding-agent/plans/ for the full implementation plan