Codex connects to the shared AgentOS MCP server over HTTP. Portfolio reads, git operations, and VSCode extension tools are all exposed as callable MCP tools. Config is managed via a TOML fragment that sync.ps1 injects into the Codex config file, leaving machine-specific settings intact. The managed block also routes Codex to OpenRouter-hosted models via four role profiles: pay-per-token access to DeepSeek, Qwen, and Kimi with no subscriptions.
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 in clients/codex/config-fragment.toml. Rather than replacing the entire Codex config, sync.ps1 injects it between managed markers in ~/.codex/config.toml, preserving machine-specific settings outside the markers.
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 is free open-source software: no OpenAI subscription required. The managed block adds OpenRouter as a pay-per-token provider, so one API key unlocks DeepSeek, Qwen, and Kimi. Four role profiles map models to jobs, invoked with codex --profile <name>. The key lives in the OPENROUTER_API_KEY environment variable and is never stored in the repo or config.
| 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 analytics adapter parses, so OpenRouter model usage shows up with per-model token counts and cost estimates alongside Claude usage.
Codex uses a file-backed memory model rather than Claude Code's project-memory system. Portable AgentOS memory (the same files used by Claude and Cursor) lives in clients/shared/memory/ and is deployed to ~/.codex/memories/ by sync.ps1.
The VSCode dashboard Memory tab reads ~/.codex/memories/. Any .md entries found there appear alongside Claude Code memory entries, each tagged with a Codex tool badge. Cross-client memory is visible in one place without leaving VSCode.
| Command | What it does |
|---|---|
| push-runtime | Deploys the AgentOS-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 AgentOS-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.