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:
Priority
Match Type
When
Example
P1
Skill match
Task maps to a self-contained skill
"merge PDFs" β pdf skill
P2
Specialist agent
Domain-specific agent exists
"security audit" β security-reviewer
P3a
Boss direct
2β4 independent agents
"fix 3 bugs" β parallel spawn
P3b
Sub-orchestrator
Complex multi-step workflow
"refactor + test" β Sisyphus
P4
Fallback
No specialist matches
"explain this" β general agent
Model Routing
Complexity
Model
Used For
Deep analysis, architecture
o3 (high reasoning)
Boss, Oracle, Sisyphus, Atlas
Standard implementation
o3 (medium)
executor, debugger, security-reviewer
Quick lookup, exploration
o4-mini (low)
explore, simple advisory
3-Phase Sprint Workflow
For end-to-end feature implementation, Boss orchestrates a structured sprint:
# View current state~/.codex/bin/my-codex-packs status
# Enable a pack immediately~/.codex/bin/my-codex-packs enable marketing
# Switch profiles at install time
bash /tmp/my-codex/install.sh --profile minimal
bash /tmp/my-codex/install.sh --profile full
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.
Project overview with links to recent decisions and learnings. Auto-created on first session, refreshed periodically.
sessions/
Session summaries.*-auto.md β auto-generated scaffold refreshed during the session and finalized at stop using recorded session files, filtered status, and logged signals. <topic>.md β human or agent-written follow-up session summary prompted by the vault reminders.
decisions/
Architecture and design decisions with rationale. Write these as durable notes when a decision is important enough to keep.
learnings/
Patterns, gotchas, non-obvious solutions.*-auto-session.md β auto-generated scaffold refreshed during the session with the session's recorded file list, logged signals, and prompts for follow-up notes. <topic>.md β human or agent-written learning note.
references/
Web research URLs.references/auto-links.md is updated from WebSearch/WebFetch hook activity when those native Codex hooks are available.
agents/
Logged session signals.agent-log.jsonl β enriched entries with {ts, agent_id, agent_type, phase, seq, task_hint}. YYYY-MM-DD-summary.md β daily logged-signal breakdown derived from that log.
persona/
User work style profile.profile.md β routing/profile summary derived from logged signals. suggestions.jsonl β routing recommendations. persona-policy.json β accepted soft routing preferences. rules/workflow-*.md β workflow sequence pattern rules proposed by /boss-briefing.
state.json
Session metadata: counters, lastVaultSync, sessionStartHead. Auto-managed by hooks.
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
Open Obsidian β Open folder as vault β select .briefing/
Notes appear in graph view, linked by [[wiki-links]]
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.
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
On first install, my-codex auto-activates a recommended dev set (engineering, design, testing, marketing, support) and records it in ~/.codex/enabled-agent-packs.txt.
# Minimal profile (core agents only, no packs)
bash /tmp/my-codex/install.sh --profile minimal
# Full profile (all 21 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 = "o3"model_reasoning_effort = "medium"
[developer_instructions]
content = """You are a debugging specialist. Analyze failures systematically:1. Reproduce the issue2. Isolate the root cause3. Propose a minimal fix4. Verify the fix does not break adjacent behavior"""
config.toml
Global Codex settings in ~/.codex/config.toml:
[agents]
max_threads = 8max_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.
my-codex and my-claude share the same Boss orchestration architecture and upstream skill sources. The key difference is the runtime: my-codex targets OpenAI Codex CLI with native .toml agent format and spawn_agent delegation, while my-claude targets Claude Code with .md agent format and the Agent tool.
Can I use both my-codex and my-claude?
Yes. They install to separate directories (~/.codex/ and ~/.claude/) and do not conflict. Skills from shared upstream sources are adapted for each platform.
How do agent packs work?
Agent packs are domain-specific agent collections installed to ~/.codex/agent-packs/. On first install, a dev profile is auto-activated. Use my-codex-packs enable <pack> to activate additional packs, or reinstall with --profile full to enable all 21 categories.
How does upstream sync work?
A GitHub Actions workflow runs every Monday, pulling the latest commits from all upstream submodules and creating an auto-merge PR. You can also trigger it manually from the Actions tab.
What models does my-codex use?
Boss and sub-orchestrators (Sisyphus, Atlas, Oracle) use o3 with high reasoning effort. Standard workers use o3 with medium reasoning. Lightweight advisory agents use o4-mini.
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.
my-claudeAll-in-one agent harness for Claude Code β Boss meta-orchestrator, 200+ agents, 200+ skills, 87 rules, 3 MCP servers, 7 hooks. One plugin install.v0.46.2
meerkatMeerkat - A modular, high-performance agent harness built in Rust.v0.5.2
langfuse-mcpA Model Context Protocol (MCP) server for Langfuse, enabling AI agents to query Langfuse trace data for enhanced debugging and observabilityv0.6.5
@actwith-ai/mcp-serverGive your AI agent a career. Persistent memory, reputation, expertise, and community β for any MCP-compatible AI agent.0.15.1
llm-wikiLLM-powered knowledge base from your Claude Code, Codex CLI, Copilot, Cursor & Gemini sessions. Karpathy's LLM Wiki pattern β implemented and shipped.v1.1.0-rc8