my-codex MCP server
Commit Nov 15, 2026An agent harness for Codex CLI that orchestrates specialized AI agents and skills to automate complex development workflows.
Also known as sehoon787/my-codex
- Stars
- 29
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is my-codex MCP?
my-codex is an agent harness for Codex CLI that orchestrates specialized AI agents and skills to automate complex development workflows.
Summary generated from the project's README
About my-codex MCP server
my-codex serves as an agent harness for the Codex CLI, designed to automate complex development workflows by orchestrating specialized AI agents and skills. It functions as a central hub where a Boss agent discovers available tools and routes tasks to specific specialists using the spawn_agent command. This setup eliminates the need for manual configuration files or boilerplate code during runtime.
Developers can install the system via a shell script that sets up a core profile containing 17 agents and a selection of skills. The harness integrates several companion tools including Serena for symbol graph management, Headroom for context compression, and codeburn for local token and cost accounting. It also supports MCP tools like context7 for retrieving live documentation. Users can customize their installation by selecting specific skill lanes, such as a web and UI profile, or by opting into different agent packs like data-ai or llmops.
What you can do with it
- 1Manage development costs and tokensDevelopers can monitor their session expenses and token usage locally without needing an external proxy.
- 2Generate architectural diagramsA developer can transform descriptions of data flows or lifecycles into self-contained HTML files with SVG exports.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesehoon787/my-codex is public and reachablegithub.com/sehoon787/my-codex ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/sehoon787/my-codex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEnglish | 한국어 | 日本語 | 中文 | Deutsch | Français
Looking for Claude Code? → my-claude — same Boss orchestration in native Claude
.mdagent format
my-codex
All-in-one agent harness for Codex CLI. One installer, 17 core agents ready.
Boss discovers every agent, skill, and MCP tool at runtime,
then routes your task to the right specialist through spawn_agent. No config files. No boilerplate.
Installation
For Humans
curl -fsSL https://raw.githubusercontent.com/sehoon787/my-codex/main/install.sh | bash
Or clone first and run the installer from the checkout:
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
The default install exposes a lean skill set on purpose: Codex truncates skill
descriptions once its skills budget is hit, so the default core profile shows
Codex 30 of the 110 installed skill entries and keeps the rest one flag away:
bash install.sh --skills=web # add the 18-skill web/UI lane
bash install.sh --full-skills # every optional lane, plus the full exposure profile
bash install.sh --skill-profile=core # back to the default exposure
The choice is saved and survives a later plain bash install.sh. See Skill Profiles and Lanes for every profile, every lane, and the my-codex-skills commands.
Interactive terminals show a checkbox selector for the three companion tools — Serena, Headroom, and codeburn — with all three selected by default. Move with ↑/↓ or j/k, toggle with Space, use a for all or n for none, and confirm the current selection with Enter or Ctrl-D/EOF. If TERM is empty or dumb, or stty is unavailable, the numbered fallback accepts Enter, all, a, y, or yes for all; none, n, no, or 0 for none; and mixed numbers or names such as 1,3 or serena codeburn. Automation selects all by default:
bash install.sh --tools=headroom # an explicit subset
bash install.sh --yes # all three, without prompting
bash install.sh --skip-tools # none
On Windows, 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.
The agent will ask which companion tools (Serena, Headroom, codeburn) to install before running the installer, because the checkbox selector only appears in an interactive terminal.
Open-Source Tools Used
Every project my-codex builds on, what it contributes, and exactly how it arrives. This table is the only place each project is described; the rest of this README lists inventories, commands, and pins.
| # | Project | What my-codex takes from it | How it arrives |
|---|---|---|---|
| 1 | everything-claude-code — affaan-m | 61 allowlisted skills: stack patterns (TypeScript, React, Python/Django/FastAPI, Spring Boot/Kotlin, SQL/Redis/Prisma, Docker/Kubernetes), AI and agent engineering, and generic codebase tooling such as onboarding, code tours, and ADRs. Claude Code-specific content is stripped, and an 18-skill web/UI lane stays out of the default install. | submodule upstream/ecc; install.sh copies only the names allowlisted in scripts/skill-allowlists.sh |
| 2 | gstack — garrytan | 30 sprint-process skill entries — browser QA (qa), scope-drift code review (review), security audit (cso), and the full plan → review → ship workflow — plus a compiled Playwright browser daemon. |
submodule upstream/gstack, vendored to ~/.codex/vendor/gstack where its own ./setup --host codex runs under bun and creates the 29 symlinks under ~/.codex/skills/ alongside the gstack root router directory; the 7 ECC skills it supersedes (benchmark, canary-watch, safety-guard, browser-qa, verification-loop, security-review, design-system) are removed so only the gstack version stays routable |
| 3 | oh-my-codex — Yeachan Heo | 7 allowlisted worker agents: executor, planner, architect, test-engineer, security-reviewer, code-reviewer, debugger. Its remaining prompts and its skills duplicate agents this repo already ships, so they are deliberately not installed. |
submodule upstream/omx; scripts/md-to-toml.sh converts the allowlisted prompts from Markdown into ~/.codex/agents/*.toml |
| 4 | superpowers — Jesse Vincent | 14 development-process skills: brainstorming, systematic debugging, test-driven development, plan writing and execution, worktree handling, and code-review etiquette. No agent is taken from it — its single code-reviewer prompt overlaps the oh-my-codex one. |
submodule upstream/superpowers; all 15 skill directories install except dispatching-parallel-agents, which duplicates the Boss delegation path this repo already owns |
| 5 | archify — tt-a1i | 1 diagram skill that turns architecture, workflow, sequence, data-flow, and lifecycle descriptions into one self-contained HTML file with inline SVG, a dark/light toggle, and PNG/JPEG/WebP/SVG export. | submodule upstream/archify, pinned to tag v3.0.1 so the sync job leaves it alone; only the repo's top-level archify/ directory is copied to ~/.codex/skills/archify, so no npx skills add runs at install time |
| 6 | awesome-codex-subagents — VoltAgent | 17 Codex-native TOML agents, shipped as the two opt-in packs data-ai (13) and llmops (4). Neither pack is enabled by a fresh install. |
vendored (MIT) into codex-agents/packs/ and installed to ~/.codex/agent-packs/; submodule removed 2026-07-27. Enable with ~/.codex/bin/my-codex-packs enable data-ai or install.sh --profile dev |
| 7 | oh-my-openagent — code-yeongyu | 9 agents — sisyphus, atlas, prometheus, oracle, metis, momus, hephaestus, librarian, multimodal-looker — covering end-to-end orchestration, plan execution and review, deep second opinions, source-backed library lookup, and reading media files. |
adapted to Codex-native TOML and maintained in-repo under codex-agents/omo/, so they install without an upstream checkout |
| 8 | agency-agents — msitarzewski | Nothing. No agent from these packs was ever spawned in this repo, so nothing was vendored. | removed (MIT) — submodule dropped 2026-07-27, still recorded in upstream/SOURCES.json |
| 9 | my-claude — sehoon787 | The same Boss orchestration in native Claude .md agent format, and the editorial baseline: scripts/skill-allowlists.sh mirrors my-claude's ECC, gstack, and superpowers lists verbatim so both harnesses expose the same upstream surface. |
sister project only — install.sh never clones, curls, or copies anything from it, so nothing is vendored and there is no pin to track. Installed side by side, the two installers coordinate codeburn and Headroom through one user-wide lock and state directory instead of fighting over the fixed ports |
| 10 | codeburn — getagentseal | Local-first token and cost accounting over the session files Codex already writes under ~/.codex/sessions — no proxy, no API key, no Codex hooks. |
npm i -g codeburn@0.9.25; install.sh starts or reuses one shared codeburn web --provider all --port 4747 --no-open process |
| 11 | ast-grep — ast-grep | Structural search and rewrite that matches on the syntax tree instead of on raw text, so agents can change code shapes without brittle regular expressions. | npm i -g @ast-grep/cli@0.45.3, skipped when an ast-grep binary is already on PATH |
| 12 | serena — oraios | A language server's symbol graph over MCP — get_symbols_overview, find_symbol, find_referencing_symbols, replace_symbol_body, insert_after_symbol — so tokens scale with the symbol rather than the whole file. The distributed package is GPL-3.0-or-later as a whole (PyPI's MIT metadata is inaccurate), so nothing is vendored. |
uv tool install --python 3.13 serena-agent==1.7.0, registered as [mcp_servers.serena] (stdio: serena start-mcp-server --project-from-cwd --context=codex --open-web-dashboard False, startup_timeout_sec = 15) |
| 13 | headroom — Headroom Labs | Apache-2.0 context compression over MCP: headroom_compress, headroom_retrieve, and headroom_stats. The headroom wrap proxy mode stays a documented manual opt-in. |
uv tool install --python 3.13 "headroom-ai[all]==0.40.0", registered as [mcp_servers.headroom] (headroom mcp serve, default_tools_approval_mode = "approve" because the server publishes no MCP annotations); the installer starts or reuses the shared agent-harness-shared profile on port 8787 and never sets ANTHROPIC_BASE_URL or OPENAI_BASE_URL |
| 14 | context7 — Upstash | Library, framework, and SDK answers from current upstream documentation instead of from model memory. It is the backend the documentation-lookup skill routes to. |
hosted MCP server at https://mcp.context7.com/mcp |
| 15 | exa — Exa Labs | Neural web search. The registered URL enables only web_search_exa, which keeps the research path to a single tool rather than Exa's full surface. |
hosted MCP server at https://mcp.exa.ai/mcp?tools=web_search_exa |
| 16 | grep.app — grep.app | Cross-repository code search over public GitHub, so an agent can look up real call sites of a library across many repositories before writing code against it. | hosted MCP server at https://mcp.grep.app |
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. The main Codex session performs the Boss role through the installed AGENTS.md, so it delegates directly to specialists instead of spawning another Boss first. Its native session identity remains Codex/root, and reinstalling refreshes managed instructions while preserving customized sections.
| Phase | What Happens |
|---|---|
| 0 · Discovery | Reads the capability registry built at session start (~/.codex/capability-registry.json) — see How Boss discovers agents and skills |
| 1 · Intent gate | Classifies the request (trivial, build, refactor, mid-sized, architecture, research, …) and counter-proposes a skill when one fits better |
| 2 · Capability matching | Cascades the priority chain below (P1 exact skill → P2 specialist agent → P3 multi-agent orchestration → P4 general-purpose fallback) |
| 3 · Delegation | Calls spawn_agent with a 6-section structured prompt: TASK / OUTCOME / TOOLS / DO / DON'T / CTX |
| 4 · Verification | Reads the changed files independently, runs tests, lint, and build, cross-references the original intent, retries up to 3× on failure |
How Boss discovers agents and skills
Boss does not have to remember to scan. At every session start, hooks/build-registry.js builds a capability registry (v2) at ~/.codex/capability-registry.json from everything installed on the machine — including agents and skills my-codex did not install:
| Source | Scope | Active when |
|---|---|---|
~/.codex/agents/*.toml |
global |
always |
~/.codex/agent-packs/<pack>/*.toml |
pack:<pack> |
the pack is enabled (its agent is also in ~/.codex/agents) |
.codex/agents/*.toml in the project |
project |
always |
~/.codex/skills/*/SKILL.md (.system excluded) |
global |
the skill manager reports it active (all, if the manager is absent) |
.codex/skills/*/SKILL.md in the project |
project |
always |
~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/skills/*/SKILL.md |
plugin:<plugin> |
config.toml enables <plugin>@<marketplace> |
Each entry keeps its name, description (capped at 200 characters), model (agents), scope and active flag. hooks/routing-map.json defines the routing intents (Architecture, Ambiguity, PlanReview, Security, Review, Debug, Testing, Research, Document, Trivial, Build) with ordered members, Advisor Group flags (oracle, metis, momus), and English + Korean keywords. The registry ranks candidates per intent by map order, scope, and description match (map members always rank ahead of description matches), so an unmanaged skill whose description fits an intent is ranked too; inactive packs, lanes, and plugins rank after every active candidate and are labeled, so they reach the top 3 only when fewer than three active candidates exist. The file is rebuilt only when an input changes or the project changes.
- SessionStart injects a compact top-3-per-intent summary (at most 6,000 characters) plus the registry path.
- UserPromptSubmit runs
hooks/route-hint.js, which classifies the prompt and adds one line such as[RouteHint] intent=Architecture → oracle[advisor], architect, $architecture-decision-records. Consult the Advisor Group when the intent calls for it.Skills appear as$name(their Codex invocation), and the Advisor Group sentence is added only when an advisor is among the picks. Unmatched prompts,/commands,$skillmentions and subagent prompts get no hint. - Stop runs
hooks/advisor-gate.js, the backstop for the Advisor Gate. When the turn's intent names an advisor (Architecture → oracle, Ambiguity → metis, PlanReview → momus), the rollout shows nospawn_agentof oracle, metis, or momus in that turn, and the final answer has noAdvisor skipped: <reason>line, it blocks the turn once and asks for the advisor. It never blocks twice per turn, never onstop_hook_active, never for a subagent, and fails open on an unreadable rollout. route-hint.js records the turn's intent for it under~/.codex/my-codex/route-intent/.
~/.omc/state/capability-registry.json belongs to my-claude; Codex never writes it.
Adoption: routing learns which results you keep
Boss records whether you adopt what an agent or skill produced, per intent, and uses it — gated — to reorder routing candidates. Call counts are never used. This is the Codex side of my-claude's adoption ledger; both write the same files.
| Piece | What it does |
|---|---|
| Offer (read from the session rollout) | On each prompt, hooks/adoption-tracker.js reads the rollout at transcript_path and collects what the previous turn ran: spawn_agent calls (by agent_type; a multi-agent v2 agent counts once its result has reached the main thread) and skills (a $skill mention's injected instructions, or a read of a SKILL.md). One per item, 5 max. Each is filed under the intent route-hint.js classified for the prompt that ran it. Process skills listed in adoption_ignore in hooks/routing-map.json (default $using-superpowers, $boss-briefing, $briefing-vault) and skills under ~/.codex/skills/.system are never offers: they run regardless of whether the advice was good |
Verdict (hooks/adoption-tracker.js verdict, UserPromptSubmit) |
Classifies your reply with the same English/Korean lists as my-claude: accept (진행해, 반영해, 좋아, 그렇게 해, 승인, 머지해, go ahead, yes, lgtm, apply it, ship it, …) or reject (아니, 틀렸, 다시 해, 그만, 하지 마, 되돌려, no,, wrong, redo, revert, stop, …); reject wins when both match, a question (…?) is never an accept, and anything else is neutral (no event). / commands, $skill prompts and subagent prompts are not replies. Prints nothing |
Ranking (adoptionWeight in hooks/build-registry.js) |
Events from the last 180 days, each weighted 0.5^(age_days/90). An (id, intent) pair counts only once its weighted sample reaches 5; its accept rate then moves it up or down by at most two slots within its band (pinned > map member > description match); active candidates still come before inactive ones. Security and Ship keep the map order and ignore adoption and pins. The SessionStart summary shows (adopted 7/9) once a pair is counted, and [pinned] for pins |
The store lives under ~/.config/agent-harness/ and is shared with my-claude:
adoption-ledger.jsonl— append-only, one event per line:{"ts": ISO-8601, "harness": "codex", "session": id, "kind": "agent"|"skill", "id": agent name or "$skill", "intent": route-hint intent or "unknown", "verdict": "accept"|"reject", "signal": "reply"|"choice"|"revert", "evidence": first 120 chars of your reply}. Codex skills are recorded as$nameand my-claude's without the$, so the two harnesses' skill rows never mix; agent rows with the same name count for both.adoption-pins.json—[{"id", "intent", "ts"}]; a pin forces that item to the top of that intent.adoption-archive.jsonl/adoption-audit.jsonl— wherereset/undomove events (nothing is hard-deleted), and a log of every CLI mutation.
Inspect or correct it with ~/.codex/bin/my-codex-adoption <cmd>: list [--intent X] (id × intent table of weighted accept/reject/n), list --events (raw events with their ts), pin <id> <intent>, unpin <id> <intent>, reset [<id>], undo <ts> [<id>]. Quote skill ids (pin '$review' Review). The ledger and pins are registry inputs, so the next session's routing summary reflects any change; while the ledger has events the registry is also rebuilt once a day so decay applies.
my-codex MCP questions
What is included in the default installation?
The default installation provides a lean skill set consisting of 30 of the 110 available skill entries and includes three companion tools: Serena, Headroom, and codeburn.