Connecting Codex CLI

Using a different agent? See Connecting Claude Code, Connecting OpenCode, or Connecting Cursor.

How It Works

When you run ./install.sh --target=codex, it handles the full connection setup:

Instance selection — Choose Tandemu Cloud or provide a self-hosted URL
Browser authorization — Your browser opens to the Tandemu dashboard. Log in and click Allow.
Auth saved — Token and org info saved to ~/.config/tandemu/codex-auth.json
Universal env loader installed — ~/.config/tandemu/lib/tandemu-env.sh (shared across every agent)
MCP registered — [mcp_servers.tandemu] section added to ~/.codex/config.toml
Personality — ~/.codex/AGENTS.md is written (or the Tandemu personality section is merged into your existing one via HTML markers)
Skills installed — /morning, /finish, /pause, /create, /standup copied into ~/.codex/prompts/ as native slash prompts

No per-editor plugin — Codex reads slash prompts and AGENTS.md directly from those well-known paths.

Installation Methods

Install script


git clone https://github.com/sebastiangrebe/tandemu.git
cd tandemu
./install.sh --target=codex

The installer authenticates you and configures everything.

Multiple agents at once


./install.sh --target=codex,cursor     # comma-separated
./install.sh --target=all              # everything detected
./install.sh                           # auto-detect installed agents and prompt

Using the skills

Open the Codex REPL in any project and type a slash prompt:


/morning

Codex reads ~/.codex/prompts/morning.md and runs the skill — same /morning → /finish flow as Claude Code and OpenCode. The five slash commands available:

/morning — Pick a task and start working
/finish — Complete the task, measure work, send telemetry
/pause — Pause the current task for later
/create — Create a new task in your ticket system
/standup — Generate a team standup report

Codex specifics: Codex CLI’s prompt mechanism may surface skills under a namespaced path (e.g. /prompts:morning) depending on your CLI version. The skill markdown’s allowed-tools frontmatter is a Claude Code concept and is ignored by Codex. AskUserQuestion (a Claude Code built-in) degrades to a plain chat question; the data flow is identical, just no structured picker UI.

Configuration Files

~/.config/tandemu/codex-auth.json

Authentication and API config:


{
  "auth": { "token": "eyJhbG..." },
  "user": { "id": "uuid", "email": "you@company.com", "name": "Your Name" },
  "organization": { "id": "uuid", "name": "Acme Engineering" },
  "team": { "id": "uuid", "name": "Frontend Team" },
  "api": { "url": "https://api.tandemu.dev" }
}

~/.config/tandemu/lib/tandemu-env.sh

The universal env loader. Sourced by every skill at the top of its first bash block. Reads codex-auth.json, exports TANDEMU_TOKEN, TANDEMU_API, TANDEMU_TASKS_DIR, TANDEMU_OTEL_ENDPOINT, and the team IDs. Shared with the Claude Code and Cursor installs — single source of truth.

~/.codex/config.toml

MCP server registration, merged with any existing config:


[mcp_servers.tandemu]
url = "https://memory.tandemu.dev/mcp/tandemu/sse/<your-user-id>"
 
[mcp_servers.tandemu.headers]
Authorization = "Bearer <token>"

Memory tools (add_memory, search_memories, get_memories, update_memory, delete_memory) become available to the Codex agent automatically.

~/.codex/AGENTS.md

Personality file. If you already have an AGENTS.md, the Tandemu personality section is appended between  and  markers so your own content is preserved.

~/.codex/prompts/

The five slash commands as native Codex custom prompts. Filenames are morning.md, finish.md, pause.md, create.md, standup.md.

~/.config/tandemu/active-tasks/

Branch-keyed active task files (tandemu-active-task-<branch-slug>.json). Universal location used by every agent.

Reconnecting

If your token expires (30 days) or you need to switch organizations, run the installer again:


./install.sh --target=codex

It detects existing config and re-authorizes.

Troubleshooting

Slash commands don’t appear — Restart the Codex REPL after install so it picks up new files in ~/.codex/prompts/.

Slash command shows up under a namespace (e.g. /prompts:morning) — That’s Codex CLI’s default for the prompts directory. You can still invoke them; the namespace prefix is cosmetic.

Memory tools missing — Check ~/.codex/config.toml has the [mcp_servers.tandemu] block. Restart Codex so it re-reads the config.

“Could not reach Tandemu API” — Check that your Tandemu instance is running and the URL in ~/.config/tandemu/codex-auth.json is correct.

Token expired — Run ./install.sh --target=codex again to re-authorize.