[Feature] Codex Support

[carlkibler]

Problem

Want to get same benefits from OpenAI Codex-cli. Claude Code is still my primary, but the recent quick exhaustion of session tokens led me to try Codex side-by-side.

Proposed solution

Adding Codex-specific tweaks to hooks, audit, and doctor commands, plus tests. That's really it. The hook behaviors are different in Codex from Claude Code so I am testing with real use to hopefully submit a PR in next day or two. I just want to clearly validate it.

Main question: will it be accepted / are you open to it?

Token savings

How does this save tokens compared to the current approach?

TODO: will report back after verifying it works.

Current approach: read entire file      → ~2,000 tokens
With this tool:   tl-<name> <args>      → ~200 tokens

Alternatives considered

Any other ways to solve this?

[edimuj]

Hey, welcome! Yes, PRs are definitely welcome.

Before you dig in though, worth knowing what's already landed so you don't redo work that's done:

MCP server (v0.34.0+): tl-mcp already exposes 8 core tools (symbols, snippet, run, impact, browse, tail, guard, diff) as an MCP server. Works with both Claude Code and Codex. Config is just:

{
  "mcpServers": {
    "tokenlean": {
      "command": "npx",
      "args": ["-y", "tokenlean@latest", "mcp"]
    }
  }
}

There's also a --tools filter if you only want a subset per project.

Codex skills: skills/codex/ already has 9 agent skill files (code-review, debug-bug, explore-codebase, etc.) that reference tokenlean tools.

What would actually be valuable in a PR:

• More MCP tools: we currently only expose 8 of 40+ CLI tools via MCP. Adding MCP wrappers for more tools is always welcome. The --tools filter means there's no risk of bloat, users just pick the tools they need for their workflow
• Codex-specific hooks if you've found patterns that work well
• Better AGENTS.md guidance (I've been running something similar to what you're describing and it works well)
• Tests, always welcome
• Anything you found that doesn't work or needs tweaking for Codex specifically

The CLI tools themselves are agent-agnostic, so they should just work. The interesting part is really the integration layer, how Codex discovers and uses them effectively.

Looking forward to seeing what you've got!

[carlkibler]

Great, thanks for the response and details. I did switch gears to trying the MCP for Codex. With the instructions (at that time anyway, updating to latest now) the method installing it meant every invocation of a codex session was pulling the latest tokenlean from npm and running it; each subagent too.

I have some different tweaks than initially mentioned make it easy to run the mcp in background for all agent session to use without a startup cost. After I update and re-verify the efficacy I'll share that back.

[edimuj]

Good catch on the startup cost. npx -y tokenlean@latest hits npm every time, and that adds up when Codex keeps spawning subagents.

Simplest fix: install globally with npm i -g tokenlean, then point the config at the installed binary:

{
  "mcpServers": {
    "tokenlean": {
      "command": "tl-mcp",
      "args": []
    }
  }
}

Instant startup, no npm resolution. You just run npm update -g tokenlean when you want to pull a new version.

I'm curious about your background daemon setup though. The MCP server right now is stdio-based, so it's one process per connection. If you've got it running as a shared persistent process that multiple sessions tap into, that's a different architecture and I'd love to see what you came up with.

Also, v0.37.0 just shipped with tl parallel for running multiple commands concurrently with structured output. The skills all got updated to use it too. Worth grabbing the latest before you test.