# shanraisshan/codex-cli-best-practice architecture

> Architecture diagram of the GitHub repository shanraisshan/codex-cli-best-practice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shanraisshan/codex-cli-best-practice
- Repository: https://github.com/shanraisshan/codex-cli-best-practice

## Overview

This repository is a Codex CLI practices guide with selected configuration examples, not the implementation of Codex itself. Its main user workflow is to consult a practice or workflow, configure Codex with the relevant project files, then use Codex features such as agents, skills, hooks, or MCP tools. The graph preserves the README’s major capability areas; relationships are documented at a high level because no source excerpts were provided.

Main entry points: [`best-practice`](https://github.com/shanraisshan/codex-cli-best-practice/tree/main/best-practice) (Best practices), [`.codex/hooks/scripts/hooks.py`](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/hooks/scripts/hooks.py) (Hook scripts), [`.codex/config.toml`](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/config.toml) (Config and profiles), [`AGENTS.md`](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/AGENTS.md) (Project context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Guides and workflows"]
  node_best_practices["Best practices"]
  node_workflows["Workflow examples"]
end

subgraph group_project_setup["Project setup"]
  node_config["Config and profiles<br/>[config.toml]"]
  node_project_context["Project context<br/>[AGENTS.md]"]
end

subgraph group_agent_tools["Agent extensions"]
  node_agent_configs["Subagent configs<br/>[weather-agent.toml]"]
  node_skills["Weather skill<br/>[SKILL.md]"]
  node_hooks["Hook scripts<br/>[hooks.py]"]
  node_hook_config["Hook configuration<br/>[hooks-config.json]"]
  node_mcp_guide["MCP guidance<br/>[codex-mcp.md]"]
end

subgraph group_codex_features["Codex capabilities"]
  node_commands["Slash commands<br/>[README.md]"]
  node_plugins["Plugins and catalog"]
  node_memory["Cross-session memory<br/>[codex-memory.md]"]
  node_rules["Execution rules"]
  node_review["Code review<br/>[README.md]"]
  node_sessions["Session lifecycle<br/>[README.md]"]
end

node_user(("Engineer"))
node_codex["Codex CLI"]

node_user -->|"consults"| node_best_practices
node_user -->|"follows"| node_workflows
node_best_practices -->|"explains"| node_config
node_best_practices -->|"explains"| node_project_context
node_best_practices -->|"explains"| node_agent_configs
node_best_practices -->|"explains"| node_skills
node_best_practices -->|"explains"| node_hooks
node_best_practices -->|"documents"| node_mcp_guide
node_user -->|"uses"| node_codex
node_config -->|"configures"| node_codex
node_project_context -->|"guides"| node_codex
node_agent_configs -->|"registers"| node_codex
node_skills -->|"extends"| node_codex
node_hook_config -->|"configures"| node_hooks
node_hooks -->|"hooks into"| node_codex
node_mcp_guide -->|"documents tools"| node_codex
node_user -->|"invokes"| node_commands
node_user -->|"browses"| node_plugins
node_user -->|"manages"| node_memory
node_user -->|"checks"| node_rules
node_user -->|"requests"| node_review
node_user -->|"manages"| node_sessions

click node_best_practices "https://github.com/shanraisshan/codex-cli-best-practice/tree/main/best-practice"
click node_workflows "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md"
click node_config "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/config.toml"
click node_project_context "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/AGENTS.md"
click node_agent_configs "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/agents/weather-agent.toml"
click node_skills "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.agents/skills/weather-svg-creator/SKILL.md"
click node_hooks "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/hooks/scripts/hooks.py"
click node_hook_config "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/hooks/config/hooks-config.json"
click node_mcp_guide "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md"
click node_commands "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md"
click node_plugins "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md"
click node_memory "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-memory.md"
click node_review "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md"
click node_sessions "https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md"

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_best_practices,node_workflows toneBlue
class node_config,node_project_context toneAmber
class node_agent_configs,node_skills,node_hooks,node_hook_config,node_mcp_guide toneMint
class node_commands,node_plugins,node_memory,node_rules,node_review,node_sessions toneRose
class node_user,node_codex toneIndigo
```

## Components

### Guides and workflows

- [Best practices](https://github.com/shanraisshan/codex-cli-best-practice/tree/main/best-practice): `best-practice`
- [Workflow examples](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md): `orchestration-workflow/orchestration-workflow.md`

### Project setup

- [Config and profiles](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/config.toml): `.codex/config.toml`
- [Project context](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/AGENTS.md): `AGENTS.md`

### Agent extensions

- [Subagent configs](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/agents/weather-agent.toml): `.codex/agents/weather-agent.toml`
- [Weather skill](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.agents/skills/weather-svg-creator/SKILL.md): `.agents/skills/weather-svg-creator/SKILL.md`
- [Hook scripts](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/hooks/scripts/hooks.py): `.codex/hooks/scripts/hooks.py`
- [Hook configuration](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/.codex/hooks/config/hooks-config.json): `.codex/hooks/config/hooks-config.json`
- [MCP guidance](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md): `best-practice/codex-mcp.md`

### Codex capabilities

- [Slash commands](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md): `README.md`
- [Plugins and catalog](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md): `best-practice/codex-marketplace.md`
- [Cross-session memory](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-memory.md): `best-practice/codex-memory.md`
- **Execution rules**
- [Code review](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md): `README.md`
- [Session lifecycle](https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md): `README.md`

### Other components

- **Engineer**
- **Codex CLI**

## Connections

- Engineer → Best practices: consults (evidence: `README.md`)
- Engineer → Workflow examples: follows (evidence: `README.md`)
- Best practices → Config and profiles: explains (evidence: `README.md`)
- Best practices → Project context: explains (evidence: `README.md`)
- Best practices → Subagent configs: explains (evidence: `README.md`)
- Best practices → Weather skill: explains (evidence: `README.md`)
- Best practices → Hook scripts: explains (evidence: `README.md`)
- Best practices → MCP guidance: documents (evidence: `README.md`)
- Engineer → Codex CLI: uses (evidence: `README.md`)
- Config and profiles → Codex CLI: configures (evidence: `README.md`)
- Project context → Codex CLI: guides (evidence: `README.md`)
- Subagent configs → Codex CLI: registers (evidence: `README.md`)
- Weather skill → Codex CLI: extends (evidence: `README.md`)
- Hook configuration → Hook scripts: configures (evidence: `README.md`)
- Hook scripts → Codex CLI: hooks into (evidence: `README.md`)
- MCP guidance → Codex CLI: documents tools (evidence: `README.md`)
- Engineer → Slash commands: invokes (evidence: `README.md`)
- Engineer → Plugins and catalog: browses (evidence: `README.md`)
- Engineer → Cross-session memory: manages (evidence: `README.md`)
- Engineer → Execution rules: checks (evidence: `README.md`)
- Engineer → Code review: requests (evidence: `README.md`)
- Engineer → Session lifecycle: manages (evidence: `README.md`)