---
source: CrewKit integrations
url: https://crewkit.io/integrations/codex.md
title: "CrewKit for Codex"
description: "Give Codex the same project context, conventions and playbooks your other AI coding agents already inherit."
---


## What CrewKit adds to Codex

A team that runs more than one coding agent usually ends up with more than one
set of standards. CrewKit keeps the standards in one place: conventions and
project memory live on the project, not in a single tool's config, and any
MCP-capable agent — Codex included — can pull them mid-session through
`crewkit mcp serve`.

Concretely, that means Codex can ask which conventions govern this project,
search the project's uploaded docs, transcripts and indexed past sessions, and
see who on the team is already working on what, without any of that being
re-typed into a second configuration file.

## Before you start

- **The CrewKit CLI**, installed and logged in.
- **Git** — CrewKit resolves your organization and project from the git remote
  of the working directory.
- **Node.js 18+** if you install through npm.

Claude Code is *not* a prerequisite here. `crewkit mcp serve` asks for three
things and no more: your CLI login, your acceptance of the acceptable-use policy,
and a project the CLI can resolve. Claude Code is required only if you also want
observed `crewkit code` sessions. Builds ship for macOS arm64 and Linux x64;
Windows runs the Linux build under WSL.

## Connect your project

Install the CLI — Homebrew, npm or the install script, whichever suits the
machine — then sign in through the device flow:

```bash
brew install karibew/tap/crewkit
npm install -g @crewkit/cli
curl -fsSL https://crewkit.io/install.sh | sh
```

```bash
crewkit --version
crewkit auth login
```

Then pin the project. `crewkit init` writes the detected mapping to
`.agent/config.yml` locally; it does not register anything server-side, even
with `--yes`. Registration is its own prompt-free command:

```bash
cd my-project
crewkit init
crewkit project create "My Project" --org acme
crewkit status
```

With the project registered, point Codex at the MCP server so it can reach the
context:

```json
{
  "mcpServers": {
    "crewkit": {
      "command": "crewkit",
      "args": ["mcp", "serve"]
    }
  }
}
```

## What gets synced

CrewKit resolves agents, skills, commands and rules through a three-tier model:
a platform tier maintained by CrewKit, an organization tier owned by your team,
and a project tier. A resource can be **standalone** (no parent), **inherit**
(its content concatenates onto the parent chain) or **forked** (a snapshot that
stops tracking upstream). The API computes the merged **effective content**; the
CLI writes that result to disk and checksums it, backing a locally modified file
up to `.claude/.backups/` rather than overwriting it.

The written paths are Claude Code's: `.claude/agents/`, `.claude/skills/`,
`.claude/commands/` and `.claude/rules/`. Rules in particular are path-scoped
markdown — `backend.md` loads when you edit files under `backend/`, `general.md`
loads for everything — and the file name is the whole routing rule; pointing your
agent at that convention is up to you. Codex does not read `.claude/agents/`, `.claude/skills/`,
`.claude/commands/` or `.claude/rules/` — those stay filesystem paths written
for Claude Code. What does reach Codex over [MCP](/docs/mcp) is playbook
conventions through `get_conventions`, plus project memory, prior work, active
work and blueprint state. See [Rules](/docs/rules) and
[Inheritance](/docs/inheritance).

## Conventions and playbooks

Playbooks are collections of conventions: structured rules with a category
(testing, architecture, style, security), a key such as `use-minitest`, the
convention text, and anti-patterns. CrewKit publishes platform playbooks for
common frameworks, your organization subscribes to the ones it wants, and
playbooks are assigned to projects — automatically by stack matching against
package manifests, framework indicators and directory structure, or by hand.

```bash
crewkit playbooks list --detail
```

The `get_conventions` MCP tool returns the conventions that apply to this
project's stack, which is how Codex gets them.

A **convention challenge** is what CrewKit records when an agent deviates from a
convention during a session: the hook system detects it and logs the challenge,
and the log feeds analytics so you can see which conventions are challenged
often enough to be worth revising. Challenges also surface in the CrewKit
terminal interface's Conventions section during a session.

## What this does not do yet

- **The telemetry path is Claude Code's.** Turn counts, token and cost rollups,
  subagent task stats and post-session analysis all come from Claude Code hooks.
  Codex sessions run outside that path, so they do not appear in the dashboard's
  session and analytics views.
- **Convention challenges are logged from hooks.** Since the challenge detector
  sits in the hook system, a Codex session produces no challenge log — and
  convention handler dispatch is itself still being rolled out progressively.
- **No Codex-specific sync target.** Resources are written to `.claude/`; there
  is no option to write them anywhere else, because that directory is the sync
  writer's only root.
- **Session import covers Claude Code transcripts.** `crewkit sessions import`
  reads local Claude Code JSONL conversations; there is no importer for other
  agents' history.
- **`add_note` needs a CrewKit-launched session.** The MCP tool that writes a
  durable note into project memory reads a session id only `crewkit code` sets,
  so a hand-registered Codex client calling it gets an error rather than a note.
  The read tools are unaffected.

The MCP surface is the same one every agent uses — see
[the CrewKit MCP server](/integrations/mcp) for the full tool list.