# arguv/codex-ai-agents architecture

> Architecture diagram of the GitHub repository arguv/codex-ai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arguv/codex-ai-agents
- Repository: https://github.com/arguv/codex-ai-agents

## Overview

This repository is a Codex agent-workflow learning project, with a small word-count CLI as its first coding exercise. Its main collaboration workflow is a user request coordinated by the main agent across Planner, Developer, Tester, and Reviewer roles; the agent-workflow skill guides those handoffs, while project-check provides local verification. The separate CLI accepts text, file, or stdin input and counts whitespace-separated tokens. Agent and skill internals are represented by their configured paths; their interactions are based on README documentation, not inspected implementation excerpts.

Main entry points: [`.agents/skills/agent-workflow/SKILL.md`](https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/agent-workflow/SKILL.md) (Agent workflow), [`word_count.py`](https://github.com/arguv/codex-ai-agents/blob/main/word_count.py) (CLI input handling), [`.codex/agents/tester.toml`](https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/tester.toml) (Tester agent), [`.agents/skills/project-check/SKILL.md`](https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/project-check/SKILL.md) (Project check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collaboration["Agent collaboration"]
  node_planner["Planner agent<br/>[planner.toml]"]
  node_developer["Developer agent<br/>[developer.toml]"]
  node_tester["Tester agent<br/>[tester.toml]"]
  node_reviewer["Reviewer agent<br/>[reviewer.toml]"]
end

subgraph group_skills["Reusable skills"]
  node_workflow_skill["Agent workflow<br/>[SKILL.md]"]
  node_check_skill["Project check<br/>[SKILL.md]"]
  node_workflow_guide["Collaboration exercise<br/>[WORKFLOW.md]"]
  node_evaluation["Workflow evaluation<br/>[EVALUATION.md]"]
  node_evaluation_results["Evaluation results"]
end

subgraph group_cli["Word-count CLI"]
  node_cli["CLI input handling<br/>[word_count.py]"]
  node_counter["Token counter<br/>[word_count.py]"]
end

node_user(("User"))
node_coordinator(("Main agent"))
node_text_input(("Text / file / stdin"))
node_count_output(("Printed count"))

node_user -->|"requests work"| node_coordinator
node_coordinator -->|"delegates planning"| node_planner
node_coordinator -->|"delegates implementation"| node_developer
node_coordinator -->|"delegates testing"| node_tester
node_coordinator -->|"delegates review"| node_reviewer
node_coordinator -->|"uses workflow"| node_workflow_skill
node_workflow_skill -->|"coordinates handoffs"| node_planner
node_workflow_skill -->|"coordinates handoffs"| node_developer
node_workflow_skill -->|"coordinates handoffs"| node_tester
node_workflow_skill -->|"coordinates handoffs"| node_reviewer
node_user -->|"requests verification"| node_check_skill
node_check_skill -.->|"runs checks"| node_tester
node_workflow_guide -->|"guides use"| node_workflow_skill
node_evaluation -->|"records evidence"| node_evaluation_results
node_user -->|"invokes"| node_cli
node_text_input -->|"provides input"| node_cli
node_cli -->|"calls count_words"| node_counter
node_counter -->|"returns count"| node_count_output

click node_planner "https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/planner.toml"
click node_developer "https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/developer.toml"
click node_tester "https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/tester.toml"
click node_reviewer "https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/reviewer.toml"
click node_workflow_skill "https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/agent-workflow/SKILL.md"
click node_check_skill "https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/project-check/SKILL.md"
click node_workflow_guide "https://github.com/arguv/codex-ai-agents/blob/main/WORKFLOW.md"
click node_evaluation "https://github.com/arguv/codex-ai-agents/blob/main/EVALUATION.md"
click node_evaluation_results "https://github.com/arguv/codex-ai-agents/blob/main/EVALUATION_RESULTS.md"
click node_cli "https://github.com/arguv/codex-ai-agents/blob/main/word_count.py"
click node_counter "https://github.com/arguv/codex-ai-agents/blob/main/word_count.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_planner,node_developer,node_tester,node_reviewer,node_user toneBlue
class node_workflow_skill,node_check_skill,node_workflow_guide,node_evaluation,node_evaluation_results toneAmber
class node_cli,node_counter toneMint
class node_coordinator,node_text_input,node_count_output toneIndigo
```

## Components

### Agent collaboration

- [Planner agent](https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/planner.toml): `.codex/agents/planner.toml`
- [Developer agent](https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/developer.toml): `.codex/agents/developer.toml`
- [Tester agent](https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/tester.toml): `.codex/agents/tester.toml`
- [Reviewer agent](https://github.com/arguv/codex-ai-agents/blob/main/.codex/agents/reviewer.toml): `.codex/agents/reviewer.toml`

### Reusable skills

- [Agent workflow](https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/agent-workflow/SKILL.md): `.agents/skills/agent-workflow/SKILL.md`
- [Project check](https://github.com/arguv/codex-ai-agents/blob/main/.agents/skills/project-check/SKILL.md): `.agents/skills/project-check/SKILL.md`
- [Collaboration exercise](https://github.com/arguv/codex-ai-agents/blob/main/WORKFLOW.md): `WORKFLOW.md`
- [Workflow evaluation](https://github.com/arguv/codex-ai-agents/blob/main/EVALUATION.md): `EVALUATION.md`
- [Evaluation results](https://github.com/arguv/codex-ai-agents/blob/main/EVALUATION_RESULTS.md): `EVALUATION_RESULTS.md`

### Word-count CLI

- [CLI input handling](https://github.com/arguv/codex-ai-agents/blob/main/word_count.py): `word_count.py`
- [Token counter](https://github.com/arguv/codex-ai-agents/blob/main/word_count.py): `word_count.py`

### Other components

- **User**
- **Main agent**
- **Text / file / stdin**
- **Printed count**

## Connections

- User → Main agent: requests work (evidence: `README.md`)
- Main agent → Planner agent: delegates planning (evidence: `README.md`)
- Main agent → Developer agent: delegates implementation (evidence: `README.md`)
- Main agent → Tester agent: delegates testing (evidence: `README.md`)
- Main agent → Reviewer agent: delegates review (evidence: `README.md`)
- Main agent → Agent workflow: uses workflow (evidence: `README.md`)
- Agent workflow → Planner agent: coordinates handoffs (evidence: `README.md`)
- Agent workflow → Developer agent: coordinates handoffs (evidence: `README.md`)
- Agent workflow → Tester agent: coordinates handoffs (evidence: `README.md`)
- Agent workflow → Reviewer agent: coordinates handoffs (evidence: `README.md`)
- User → Project check: requests verification (evidence: `README.md`)
- Project check → Tester agent: runs checks
- Collaboration exercise → Agent workflow: guides use (evidence: `README.md`)
- Workflow evaluation → Evaluation results: records evidence (evidence: `README.md`)
- User → CLI input handling: invokes (evidence: `README.md`)
- Text / file / stdin → CLI input handling: provides input (evidence: `word_count.py`)
- CLI input handling → Token counter: calls count_words (evidence: `word_count.py`)
- Token counter → Printed count: returns count (evidence: `word_count.py`)
