English | 한국어 | 日本語 | 中文 | Deutsch | Français

Looking for Claude Code? → my-claude — same Boss orchestration in native Claude .md agent format

my-codex

All-in-one agent harness for OpenAI Codex CLI. Install once, 17 curated agents ready.

Boss auto-discovers every agent and skill at runtime, then routes your task to the right specialist via spawn_agent. No config. No boilerplate.

Installation

For Humans

curl -fsSL https://raw.githubusercontent.com/sehoon787/my-codex/main/install.sh | bash

Clone-based install:

git clone --depth 1 https://github.com/sehoon787/my-codex.git /tmp/my-codex
bash /tmp/my-codex/install.sh
rm -rf /tmp/my-codex

Windows note:

• install.sh patches the npm-managed codex, codex.cmd, and codex.ps1 shims when they exist, so the my-codex vault pipeline still has wrapper fallback coverage even if %APPDATA%\npm resolves before ~/.codex/bin.

For AI Agents

Read https://raw.githubusercontent.com/sehoon787/my-codex/main/AI-INSTALL.md and follow every step.

How Boss Works

Boss is the meta-orchestrator at the core of my-codex. It never writes code — it discovers, classifies, matches, delegates, and verifies.

User Request
     │
     ▼
┌─────────────────────────────────────────────┐
│  Phase 0 · DISCOVERY                        │
│  Scan ~/.codex/agents/*.toml at runtime     │
│  → Build live capability registry           │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  Phase 1 · INTENT GATE                      │
│  Classify: trivial | build | refactor |     │
│  mid-sized | architecture | research | ...  │
│  → Counter-propose skill if better fit      │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  Phase 2 · CAPABILITY MATCHING              │
│  P1: Exact skill match                      │
│  P2: Specialist agent via spawn_agent       │
│  P3: Multi-agent orchestration              │
│  P4: General-purpose fallback               │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  Phase 3 · DELEGATION                       │
│  spawn_agent with structured instructions   │
│  TASK / OUTCOME / TOOLS / DO / DON'T / CTX  │
└──────────────────────┬──────────────────────┘
                       ▼
┌─────────────────────────────────────────────┐
│  Phase 4 · VERIFICATION                     │
│  Read changed files independently           │
│  Run tests, lint, build                     │
│  Cross-reference with original intent       │
│  → Retry up to 3× on failure               │
└─────────────────────────────────────────────┘

Priority Routing

Boss cascades every request through a priority chain until the best match is found:

Model Routing

3-Phase Sprint Workflow

For end-to-end feature implementation, Boss orchestrates a structured sprint:

Phase 1: DESIGN         Phase 2: EXECUTE        Phase 3: REVIEW
(interactive)            (autonomous)             (interactive)
─────────────────────   ─────────────────────   ─────────────────────
User decides scope      executor runs tasks     Compare vs design doc
Engineering review      Auto code review        Present comparison table
Confirm "design done"   Architect verification  User: approve / improve

Architecture

┌─────────────────────────────────────────────────────┐
│                    User Request                       │
└───────────────────────┬─────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────┐
│  Boss · Meta-Orchestrator (gpt-5.6 high)              │
│  Discovery → Classification → Matching → Delegation  │
└──┬──────────┬──────────┬──────────┬─────────────────┘
   │          │          │          │
   ▼          ▼          ▼          ▼
┌──────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ P3a  │ │  P3b   │ │  P1/P2 │ │Config  │
│Direct│ │Sub-orch│ │ Skill/ │ │Control │
│2-4   │ │Sisyphus│ │ Agent  │ │config. │
│spawn │ │Atlas   │ │ Direct │ │toml    │
└──────┘ └────────┘ └────────┘ └────────┘
┌─────────────────────────────────────────────────────┐
│  Agent Layer (17 installed TOML files)                │
│  Boss 1 · OMO 9 · OMX 7                               │
│  + 2 opt-in agent packs (17 agents, off by default)   │
├─────────────────────────────────────────────────────┤
│  Skills Layer (123 from ECC + gstack + superpowers)   │
│  coding-standards · security-scan · deep-research     │
│  /review · /qa · /cso · /ship                         │
├─────────────────────────────────────────────────────┤
│  MCP Layer                                            │
│  Context7 · Exa · grep.app                            │
└─────────────────────────────────────────────────────┘

What's Inside

# View current state
~/.codex/bin/my-codex-packs status

# Enable a pack immediately
~/.codex/bin/my-codex-packs enable data-ai

# Switch profiles at install time
bash /tmp/my-codex/install.sh --profile minimal   # no packs
bash /tmp/my-codex/install.sh --profile dev       # data-ai + llmops
bash /tmp/my-codex/install.sh --profile full      # every installed pack

MCP Servers (3)

Server	Purpose	Cost
Context7	Real-time library documentation	Free
Exa	Semantic web search	Free 1k req/month
grep.app	GitHub code search	Free

Briefing Vault

Obsidian-compatible persistent memory. Every project maintains a .briefing/ directory that updates during Codex sessions via native plugin hooks, with wrapper fallback for session start/end continuity.

.briefing/
├── INDEX.md                          ← Project context (auto-created once)
├── state.json                        ← Session metadata, counters, lastVaultSync (auto-managed)
├── sessions/
│   ├── YYYY-MM-DD-<topic>.md        ← Human/agent-written follow-up session summary
│   └── YYYY-MM-DD-auto.md           ← Auto-generated scaffold (recorded files, filtered status, follow-up)
├── decisions/
│   └── YYYY-MM-DD-<decision>.md     ← Human/agent-written decision record
├── learnings/
│   ├── YYYY-MM-DD-<pattern>.md      ← Human/agent-written learning note
│   └── YYYY-MM-DD-auto-session.md   ← Auto-generated scaffold (files, wrapper activity, prompts)
├── references/
│   └── auto-links.md                ← Reserved for collected research links
├── archives/                         ← PARA: completed/inactive notes (flat)
├── wiki/                             ← LLM-wiki: concept pages
│   └── _schema.md
├── agents/
│   ├── agent-log.jsonl              ← Wrapper/session log
│   └── YYYY-MM-DD-summary.md        ← Daily logged-signal breakdown
└── persona/
    ├── profile.md                   ← Routing/profile summary from logged signals
    ├── suggestions.jsonl            ← Routing suggestions (auto-generated)
    ├── persona-policy.json          ← Accepted soft routing preferences for Boss
    └── rules/                       ← Workflow pattern rules (workflow-*.md)

Sub-Vaults

Knowledge Management (v2)

BriefingVault v2 integrates three knowledge management methodologies:

Codex CLI session-end hooks automatically:

• Suggest archiving notes older than 30 days
• Propose wiki pages for frequently mentioned concepts
• Generate unique Zettelkasten IDs for new notes

Session-Specific Diffs

At session start, my-codex saves the current git HEAD and a snapshot of the working tree state. During the session, native Codex hooks refresh .briefing scaffolds after prompts, edits, searches, and subagent completions. At session end, the final scaffold summarizes diff and status only for recorded paths, while filtering hook-created noise such as .briefing/ artifacts and session-start .gitignore edits.

This keeps the scaffold focused on session-owned work instead of dumping the entire repository status. For non-git projects, a YYYY-MM-DD:cwd identifier is used as fallback.

Using with Obsidian

1. Open Obsidian → Open folder as vault → select .briefing/
2. Notes appear in graph view, linked by [[wiki-links]]
3. YAML frontmatter (date, type, tags) enables structured search
4. Timeline scaffolds for sessions and learnings build automatically; follow-up summaries, decisions, and learning notes accumulate as you write them

/boss-briefing

Run /boss-briefing during or at the end of a session to:

• Sync vault: Update profile.md, INDEX.md, and agent summaries
• Detect workflow patterns: Analyze temporal agent call sequences across sessions
• Recover from gaps: Generate recovery summaries if days have passed since the last session
• Propose persona rules: Suggest workflow-based routing preferences (not just frequency)
• Validate session notes: Check that today's session has a proper summary

The Stop hook checks whether /boss-briefing has run today. If not, it blocks session end with a reminder. The existing stop-profile-update.js continues to run as a fallback.

Behavioral Hooks

Upstream Open-Source Sources

my-codex tracks 4 upstream submodules, plus one vendored snapshot and two adapted/sister projects:

#	Source	Method	What It Provides
1	everything-claude-code — affaan-m	submodule	79 allowlisted skills across development workflows. Claude Code-specific content stripped; generic coding skills retained.
2	gstack — garrytan	submodule	27 skills for code review, QA, security audit, deployment. Includes Playwright browser daemon.
3	oh-my-codex — Yeachan Heo	submodule	7 allowlisted worker agents (executor, planner, architect, test-engineer, security-reviewer, code-reviewer, debugger), converted from Markdown prompts to Codex TOML.
4	superpowers — Jesse Vincent	submodule	13 skills covering brainstorming, TDD, systematic debugging, and plan writing. No agents installed.
5	awesome-codex-subagents — VoltAgent	vendored (MIT)	17 AI/LLM agents snapshotted into codex-agents/packs/ as 2 opt-in packs (data-ai 13, llmops 4). Submodule removed 2026-07-27.
6	oh-my-openagent — code-yeongyu	adapted	9 OMO agents (Sisyphus, Atlas, Oracle, etc.). Adapted to Codex-native TOML format and maintained in-repo.
7	my-claude — sehoon787	sister project	Same Boss orchestration in native Claude .md agent format. Skills, rules, and briefing vault shared across both projects.

Every submodule is SHA-pinned in upstream/SOURCES.json (AI-BOM), which also records the two removed submodules (agency-agents — nothing vendored; awesome-codex-subagents — 17 agents vendored).

GitHub Actions

my-codex Originals

Features built specifically for this project, beyond what upstream sources provide:

Installation Options

Quick Install

git clone --depth 1 https://github.com/sehoon787/my-codex.git /tmp/my-codex
bash /tmp/my-codex/install.sh
rm -rf /tmp/my-codex

Re-running the same command refreshes to the latest main build, replaces only my-codex-managed files in ~/.codex/, and removes stale skill copies from ~/.agents/skills/.

Agent Pack Profiles

Packs are installed but inactive by default — a fresh install enables none of them and records the empty set in ~/.codex/enabled-agent-packs.txt. Opt in per pack, or pick a profile:

# Enable one pack immediately
~/.codex/bin/my-codex-packs enable data-ai

# Minimal profile (core agents only, no packs — the default)
bash /tmp/my-codex/install.sh --profile minimal

# Dev profile (data-ai + llmops)
bash /tmp/my-codex/install.sh --profile dev

# Full profile (all 2 installed pack categories enabled)
bash /tmp/my-codex/install.sh --profile full

Codex Attribution System

install.sh installs a codex wrapper plus global git hooks in ~/.codex/git-hooks/:

• prepare-commit-msg — Records files changed during a real Codex session
• commit-msg — Appends Generated with Codex CLI: https://github.com/openai/codex when staged files intersect the recorded change set
• post-commit — Adds AI-Contributed-By: Codex trailer to qualifying commits

Opt-in Co-authored-by trailer: set both git config --global my-codex.codexContributorName '<label>' and my-codex.codexContributorEmail '<github-linked-email>'. Disable entirely: git config --global my-codex.codexAttribution false. my-codex does not change git user.name, git user.email, or commit author identity.

Agent TOML Format

Every agent is a native TOML file in ~/.codex/agents/:

name = "debugger"
description = "Focused debugging specialist — traces failures to root cause"
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

[developer_instructions]
content = """
You are a debugging specialist. Analyze failures systematically:
1. Reproduce the issue
2. Isolate the root cause
3. Propose a minimal fix
4. Verify the fix does not break adjacent behavior
"""

config.toml

Global Codex settings in ~/.codex/config.toml:

[agents]
max_threads = 8
max_depth = 1

• max_threads — Maximum concurrent sub-agents
• max_depth — Maximum nesting depth for agent-spawns-agent chains

Bundled Upstream Versions

Upstream sources managed as git submodules. Pinned commits tracked in .gitmodules.

FAQ

Troubleshooting

Skills-only recovery

If a tool reports invalid SKILL.md files under ~/.agents/skills/, the most common cause is a stale local copy or stale symlink target from an older install.

Remove the affected directories from ~/.agents/skills/ and matching entries under ~/.claude/skills/, then reinstall:

npx skills add sehoon787/my-codex -y -g

If you use the full Codex bundle, rerun install.sh once as well. The full installer refreshes ~/.codex/skills/ and removes stale my-codex-managed copies under ~/.agents/skills/.

Contributing

Issues and PRs are welcome. When adding a new agent, add a .toml file to codex-agents/core/ or codex-agents/omo/ and update the agent list in SETUP.md. See CONTRIBUTING.md for PR validation steps and Codex commit attribution behavior.

Credits

Built on the work of: my-claude (sehoon787), everything-claude-code (affaan-m), gstack (garrytan), oh-my-codex (Yeachan Heo), superpowers (Jesse Vincent), awesome-codex-subagents (VoltAgent), oh-my-openagent (code-yeongyu), openai/skills (OpenAI).

License

MIT License. See the LICENSE file for details.