Codex is OpenAI's assistant, wired into the same shared memory as my other assistants: it connects to the Fulltrace MCP server over HTTP, with portfolio reads, git operations and VSCode extension tools all callable. It pays per use rather than by subscription too: four role profiles route planning, tooling and agentic work to OpenRouter-hosted models (DeepSeek, Qwen, Kimi), picking a cheaper or stronger model depending on the job. A managed config fragment keeps its setup in sync with the rest of Fulltrace, while leaving machine-specific settings intact.
Codex's most distinctive role in Fulltrace is not writing code, it is refusing designs. Before anything risky gets built, it is handed the design and briefed to tear it apart rather than agree with it. Using the same model to check its own homework is worthless, so the reviewer is always a different model from a different company, holding the red pen.
The verdicts are real, not ceremonial. The local-fleet write surface drew a pre-implementation NO-GO with three blocker findings, all folded before a line of code existed: the ledger write resequenced to close a crash window, tag validation moved host-side rather than trusting the webview, and a guard added against double-submission. A review that can only ever say yes is theatre.
The local-model design went further: the plan for authoring the document was itself refuted first, two rounds and sixteen findings, all folded. Then the document drew two more rounds and thirteen findings, with zero resurfacings at round two. Rounds that stop turning up new material are the signal the design is done.
A finding is an argument, not an order. One recent review returned NO-GO with nine findings: three blockers were rejected on adjudication with sharpening folds, and the rest were taken. Another had twelve of thirteen folded and one rejected and upheld. The reviewer does not get a veto, because handing a model the ship call is just a different way of not deciding.
The rulebook records the review as recommended for the riskiest slices rather than mandatory. In practice every one of them has had it. The protocol is written down as its own document, so the review is a repeatable procedure rather than a mood.
There is no separate Codex-specific server. Codex connects directly to the shared mcp-server/server.js instance already running for Claude Code. Same endpoint, same telemetry, same portfolio data.
Registered in ~/.codex/config.toml under [mcp_servers.agentOS-portfolio].
StreamableHTTP transport (stateless). Same endpoint and transport as Claude Code. Server must be running under pm2 before Codex can connect.
All tools served by mcp-server/server.js. Portfolio tools give Codex access to the same context portfolio that Claude Code reads. The operational tools expose git and VSCode extension operations, and the filesystem tools give agent loops controlled file access confined to an explicit roots allow-list.
| Tool | Description |
|---|---|
| list_portfolio_files | Lists all files in AgentOS/context-portfolio/. Returns filenames and metadata. |
| read_portfolio_file | Reads any portfolio file by name, filename, or portfolio:// URI. Returns full file contents from disk. Always current, never cached. |
| agentOS_git_commit | Runs git add -A && git commit -m in a specified working directory. Accepts the working directory and commit message as arguments. |
| agentOS_git_push | Runs git push in a specified working directory. |
| agentOS_ext_compile | Runs npm run compile for the VSCode extension in its directory. |
| agentOS_ext_package | Runs npm run package (via vsce) to produce a .vsix artefact. |
| agentOS_ext_install | Finds the latest .vsix in the extension directory and installs it via code.cmd. |
| agentOS_fs_list | Lists directory contents inside the AGENTOS_FS_ROOTS allow-list. Every filesystem tool refuses paths outside the configured roots. |
| agentOS_fs_read | Reads a file within the allowed roots and returns its contents. |
| agentOS_fs_search | Searches for text across files within the allowed roots. |
| agentOS_fs_write | Writes a file within the allowed roots. Used by agent loops where code, not the model, performs the write. |
| agentOS_fs_replace | Exact-snippet replace within a file: the edit applies only if the target snippet matches exactly, so a stale proposal fails instead of corrupting the file. |
The repo tracks a managed Codex config fragment, and sync.ps1 injects it between managed markers in ~/.codex/config.toml rather than replacing the file outright, so machine-specific settings outside the markers are left alone.
The MCP server must be running under pm2 before Codex can use these tools. If it is not running, tool calls fail silently or with a connection error. Run pm2 status to verify before starting a Codex session.
Codex CLI itself is free, open-source software: no OpenAI subscription required. A managed config block adds OpenRouter as a pay-per-token provider on top of it, so one API key unlocks DeepSeek, Qwen, and Kimi, and each kind of job goes to the model that suits it best: cheap for routine work, stronger where it matters. Four role profiles map models to jobs, invoked with codex --profile <name>. The key itself lives in the OPENROUTER_API_KEY environment variable and is never stored in the repo or its config.
Four roles cover the work: a planner for thinking through a job, a workhorse for everyday coding, a stronger model for long multi-step jobs, and a free option for throwaway tasks.
| Profile | Model | Role |
|---|---|---|
| planner | deepseek/deepseek-v4-flash | Planning and reasoning. 1M context at a fraction of frontier pricing. |
| tools | qwen/qwen3-coder | Tool-calling workhorse for coding tasks. 1M context. |
| agentic | moonshotai/kimi-k2.5 | Multi-step agentic loops. 262K context. |
| cheap | qwen/qwen3-coder:free | One-shot cheap tasks at $0. Rate-limited free tier, unsuitable for agentic loops. |
Every Codex session writes rollout logs that the dashboard's analytics adapter parses, so OpenRouter usage shows up there too: per-model token counts and cost estimates, right alongside Claude usage.
Codex uses a file-backed memory model rather than Claude Code's project-memory system. The same shared memory files used by Claude and Cursor (the Claude page maps them file by file) deploy from clients/shared/memory/ to ~/.codex/memories/ on push-runtime.
The dashboard Memory tab reads the same directory, so Codex entries appear alongside Claude's, each tagged with a Codex badge: cross-client memory in one place without leaving VSCode.
A PowerShell script keeps the local Codex install in step with the repo: pushing config, memory and skills out, pulling runtime state back in for inspection, and reporting drift if the two fall out of sync.
| Command | What it does |
|---|---|
| push-runtime | Deploys the Fulltrace-managed Codex block, shared memories from clients/shared/memory/, and shared skills to ~/.codex/. Injects the TOML fragment between managed markers. Deployed skills are token-expanded per client and carry an injected /command-log block, so Codex command invocations report to the dashboard. |
| pull-runtime | Copies the managed Codex block plus runtime memories and skills back into clients/codex/ for inspection. Skill sync excludes .codex/skills/.system so bundled system skills are not copied into the repo. |
| clean-runtime | Removes Fulltrace-managed Codex state from ~/.codex/ and redeploys the canonical repo copy. Use on restructures or to resolve drift. |
| check-sync | Reports drift between the repo copy and ~/.codex/. Exits non-zero when something is out of sync, suitable for CI or pre-session checks. |
This setup is designed for a trusted local workstation. The constraints and tradeoffs are deliberate.
The MCP server binds to 127.0.0.1 only. It is not reachable from other machines on the network. Do not change the binding address without adding authentication first.
The /mcp tool endpoint requires a Bearer token from ~/.agentos/token; sync.ps1 keeps the AGENTOS_TOKEN environment variable in step with it. Dashboard write endpoints (/portfolio-read, /command-log, /set-project) remain unauthenticated, so treat dashboard data as local telemetry, not an audit log.
sync.ps1 pull-runtime copies ~/.codex/memories and ~/.codex/skills into the repo. Review memory and skill files before committing if they may contain client data, secrets, or machine-specific details.