TeamFlow in OpenAI Codex CLI
Codex CLI has first-class remote MCP with its own login command, loads Agent Skills from the shared .agents/skills root, and reads AGENTS.md on every turn, and its hooks are Claude Code's shape field for field. The installer writes all four.
Tool OpenAI Codex CLI Reporting Automatic, via hooks
1. Install
npx -y github:macleodlabs-ai/teamflow-plugin skills install --for codexThat writes:
.agents/skills/<skill>/SKILL.md— the ten skills, in the shared skills directory this tool readsAGENTS.md— the always-on reporting instruction, as a marked block; your own instructions above and below it are kept~/.codex/config.toml— the TeamFlow MCP server, as a marked TOML table.teamflow/hooks/codex.sh— the hook itself; it callsteamflow hook --for codex, prints nothing the tool could read as a denial, and exits 0 whatever happens.codex/hooks.json— the hook registration:PostToolUseandStop
Add --scope user to install for every project on this machine, or --dry-run to see the file list without writing anything. Re-running it replaces TeamFlow's block and leaves the rest of each file alone.
2. The skills you get
The same ten the Claude Code plugin carries, generated from the same SKILL.md files. This tool loads them as skills, one directory each, with the name prefixed so they do not collide with anybody else’s in a shared directory.
| Skill | What it does |
|---|---|
teamflow-login / teamflow-logout | sign in once, or remove the session |
teamflow-status | who is signed in, what is bound, what was last sent |
teamflow-bind / teamflow-unbind | name the ticket by hand, or stop |
teamflow-sync | publish the current state now |
teamflow-doctor | transport, account, credits, tracker MCP |
teamflow-repos | register a repository so its CI can report |
teamflow-admin-code | email an invite code to an org admin; superadmins only |
macleodlabs-teamflow-client | call the paid service over MCP or REST |
Each one wraps a github:macleodlabs-ai/teamflow-plugin subcommand, so the skill and the shell command are the same thing. Inside Claude Code they are /teamflow:login, /teamflow:status and so on.
3. Sign in once
codex mcp login teamflowThat opens the browser for an OAuth 2.1 authorization-code flow with PKCE, on a loopback callback. codex mcp list then shows teamflow with its three tools.
4. By hand
The installer writes this for you. If you would rather paste it: ~/.codex/config.toml, or .codex/config.toml in a trusted project.
[mcp_servers.teamflow]
url = "https://codercat.io/mcp"Or let the CLI write it:
codex mcp add teamflow --url https://codercat.io/mcpauth defaults to oauth, so nothing else is needed. Ignore guides that tell you to set experimental_use_rmcp_client; that flag was for builds that ignored remote servers without it and is not part of the current configuration.
There is no .codex/skills. .agents/skills is Codex's only skill location, searched in the working directory, its parents up to the repository root, and $HOME. Anything written elsewhere is invisible to it.
--scope user puts the skills in ~/.agents/skills instead, which is the right choice for a machine where every repository should have them. That directory is not Codex's alone: Cursor, Copilot, Gemini CLI, Zed, Windsurf and Junie all read it, so one user-scope install covers every one of them.
5. The stages to report
| Stage | When |
|---|---|
LOCAL_DEV | code is being written on a workstation |
LOCAL_TEST | the local test suite or build passed |
LOCAL_AUDIT | a local review, lint or security audit passed |
LOCAL_REWORK | a local gate failed; pass --rework-from naming it |
MERGE | the pull request is merged, or ready to be |
CI_BUILD | CI is building the merged change |
DEPLOY_DEV | the change is deployed to the shared dev environment |
DEV_TEST | tests passed against dev |
DEV_AUDIT | an audit passed against dev |
DEV_REWORK | a dev gate failed; pass --rework-from naming it |
DEV_VERIFIED | verified in dev |
READY_PROD | waiting on the production decision |
JIRA is the thirteenth: the ticket exists and nothing has started. Statuses are running, success, waiting, blocked, failed and idle. This is the same vocabulary the Claude Code plugin derives, so a ticket moved from here sits in the same column as one moved by Claude.
6. Without the agent
Anything that runs in a shell posts the same report with no model involved. A git hook, an npm script, a run configuration, a CI step:
npx -y github:macleodlabs-ai/teamflow-plugin report --issue DAEMON-142 --stage LOCAL_TEST \
--status success --summary "42 tests, 0 failing"Same envelope, same transport, same credential. Prefer it wherever the board has to be right whether or not an agent remembered. npx -y github:macleodlabs-ai/teamflow-plugin report --help lists every flag.
7. What this is not
OpenAI Codex CLI reports automatically through its own hooks: PostToolUse and Stop. Nothing to remember. Codex adopted Claude Code’s hook shape field for field, so TeamFlow reports from it exactly as it does from Claude Code.
The hooks see this tool's own calls and nothing else. A test run in another terminal, a merge from the web UI, a deploy from a pipeline: put npx -y github:macleodlabs-ai/teamflow-plugin report in the git hook or the script that already runs on every change, and those land on the board too.
8. What leaves your machine
TeamFlow is a delivery map for Jira, Linear and GitHub issues, run by MacleodLabs. Reports carry derived state only: a ticket key, a stage, a status, a short summary and evidence links. Prompts, diffs, source code, commands and logs are never sent and are rejected before they are charged.