agentleFS
bman654bman654/clodex/CLAUDE.md

clodex

CLAUDE.md110 starsChanged 3 days agoMITView on GitHub

Guidance for coding agents and maintainers working in this repo. Read this file in full; load the deeper documents below only when you touch the subsystem they cover. clodex bridges Claude Code to non-Anthropic models — OpenAI API key (openai), ChatGPT/Codex-plan OAuth (openai-oauth), or community-supported OpenCode Go (opencode-go). Provider support tiers are documented in README. It is a trimmed fork of relay-ai (full commit history preserved). Prime directive. The translation, caching, auto-compaction, and OAuth-continuation code encodes real production failures that…

  • Installs packages
  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before opening a PR run pnpm typecheck && pnpm test && pnpm build — the same three the CI / test job runs on every pull request.

    line 55
  2. Very specific:

    Use CLODEX_HOME=$(mktemp -d) to exercise the CLI against throwaway config instead of your real ~/.clodex.

    line 68
  3. Very specific:

    Add ! after the type (feat!:) or a BREAKING CHANGE: footer for an incompatible change.

    line 85
  4. Very specific:

    Prefer a scope a user recognizes (auth, models, launch, images, openai) over one that only names an internal module (adapter, transport, …

    line 129
  5. Very specific:

    Never commit dist/ (gitignored, rebuilt by CI), never hardcode a version string (package.json is the source of truth), and never run npm …

    line 258

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Guidance for coding agents and maintainers working in this repo. Read this file in full; load the deeper documents below only when you touch the subsystem they cover.

clodex bridges Claude Code to non-Anthropic models — OpenAI API key (openai), ChatGPT/Codex-plan OAuth (openai-oauth), or community-supported OpenCode Go (opencode-go). Provider support tiers are documented in README. It is a trimmed fork of relay-ai (full commit history preserved).

Prime directive. The translation, caching, auto-compaction, and OAuth-continuation code encodes real production failures that are not visible in the diff. Prefer surgical changes over restructuring.

Where everything lives

Load thisWhen
.claude/skills/pr-verification/SKILL.mdBefore the first git push of any change — the gate it must clear, and why pushing before your review reports costs more than it saves. Load it when you start preparing the change, not when you are about to open the PR.
.claude/skills/pr-review/SKILL.mdReviewing someone else's PR: panels, proof techniques, verdicts, merging.
.claude/docs/claude-code-internals.mdBefore asserting how Claude Code itself behaves, or re-deriving it.
.claude/docs/patcher.mdChanging clodex patch, patch transforms, or backups.
.claude/docs/oauth-continuation.mdChanging src/oauth/, head matching, upstream retries, WS diagnostics.
.claude/docs/translation.mdChanging sdk-adapter.ts, provider-factory.ts, openai-adapter.ts.
.claude/docs/launch-and-wrapper.mdChanging launch, bridge modes, env, server discovery, clodex-claude, outbound proxy.
.claude/docs/registry-and-server.mdChanging src/registry/, src/server/, model or alias resolution.
CONTRIBUTING.mdOutside contributors: how to scope a PR.
RELEASING.mdMaintainers: how a release is cut and staged.

.agents is a committed symlink to .claude, so harnesses that look for .agents/ find the same skills and docs.

Toolchain and commands

corepack enable          # activates the pinned pnpm version
pnpm install
pnpm build               # compile TypeScript → dist/cli.js (tsup, ESM, shebang injected)
pnpm test                # vitest
pnpm typecheck           # tsc --noEmit
pnpm dev                 # watch mode

pnpm vitest run tests/patcher.test.ts    # a single test file

# Manual testing (after pnpm build; npm link once)
clodex claude --dry-run     # full wizard, preview instead of launch, no writes
clodex claude --trace       # debug logs to ~/.clodex/logs/
clodex models --list        # print clodex:<provider>:<model> names + aliases
clodex patch                # patch the Claude Code binary
clodex server               # foreground gateway
clodex providers            # provider registry management
clodex-claude [args...]     # second bin: launch claude bridged to a running clodex server

Before opening a PR run pnpm typecheck && pnpm test && pnpm build — the same three the CI / test job runs on every pull request. Passing them is necessary and never sufficient; see the pr-verification skill.

Development targets Node 24 (.nvmrc pins v24.14.1; CI runs 24) while the published package supports Node >= 22 (engines.node) — don't use APIs newer than Node 22 in src/. Dev package manager is pnpm, pinned via packageManager: "pnpm@10.34.5" and activated with corepack. Dependencies are exact-pinned (no ^/~). pnpm-workspace.yaml sets minimumReleaseAge: 14400 (minutes) — no direct or transitive dependency version younger than 10 days can be resolved; already-locked versions install fine, but fresh resolution of a too-new version fails with ERR_PNPM_NO_MATURE_MATCHING_VERSION. End users install with npm install -g @bman654/clodex; the dev package manager does not affect consumers.

Use CLODEX_HOME=$(mktemp -d) to exercise the CLI against throwaway config instead of your real ~/.clodex.

Commit messages

Conventional Commits, enforced by commitlint (Husky commit-msg hook locally, and in CI on every pull request).

PrefixUse for
feat:adds a feature
fix:fixes behavior
docs:documentation only
test:tests only
refactor:no behavior change
build: / ci: / chore:maintenance

Add ! after the type (feat!:) or a BREAKING CHANGE: footer for an incompatible change. Hard-wrap bodies and footers at ≤100 characters per line — commitlint's body-max-line-length is enforced by the hook and again on every push to main.

Your summary line is the release note. Changelog entries are generated from commit summary headers. Release-please renders type(scope): summary as a bullet with the scope bolded and issue/commit links appended, but the summary text itself is carried through unchanged. Get it right — it is what every user reads. (The one hand-written entry, 0.1.0, predates this and is preserved as prose.)

Ordinary commit-body wording reaches no user-facing surface, so nobody polices it. The exception is a merge commit: gh pr merge without --body "" puts the PR title into the merge-commit body, and release-please parses it as a second entry — a release has shipped with a duplicate changelog line proving it. See .claude/skills/pr-review/SKILL.md.

Today most summaries fail. Reviewing the generated entries in CHANGELOG.md against the rules below — 62 bullets, 60 distinct summaries once two duplicates are collapsed — 44 were judged unreadable to a non-technical user and only 2 clearly passed. That judgment is a review assessment, not a measurement, but the direction is not in doubt.

Write the summary line for someone who uses clodex and has never read the source. It must say what they can now do, what they stop seeing, or what got more reliable.

  1. Name the user-visible outcome, not the mechanism. Replace canonicalize, replay, strip, snapshot, serialize with what the user notices.
  2. Say why it matters — a concrete "so", "to prevent", "to avoid", or equivalent.
  3. No internal vocabulary without a plain-language gloss: module names, symbols, protocol fields, function_call, heads, nursery, canary, pty, stderr, previous_response_id, store:false, cache_control.
  4. No implementation-only detail — hash formats, dependency versions, test/CI fixes — unless tied to a visible install or runtime result.
  5. Self-contained. The reader should not need the issue, the body, or the code.
  6. The 10-second test: could a non-technical user explain the problem solved and decide whether they care, from this line alone?
  7. Conventional-commit form, lowercase imperative, whole line ≤ 100 characters.
Don'tDo
fix(openai): snapshot function_call arguments in the sanitized downstream shapefix(oauth): improve OpenAI cache hit rate by keeping tool arguments consistent
feat(openai): omitted-reasoning alignment and abandoned-head canary coveragefeat(oauth): keep long conversations working when reasoning details are omitted
fix(openai): suppress reasoning.summary for gpt-5.3-codex-sparkfix(reasoning): prevent blank responses on gpt-5.3-codex-spark
fix(proxy): isolate bridge settings from child commandsfix(proxy): prevent nested Claude commands from using a stale clodex connection
fix(patcher): include transform-set version in patch config hashfix(models): detect patch updates so new model settings take effect

Prefer a scope a user recognizes (auth, models, launch, images, openai) over one that only names an internal module (adapter, transport, sdk) where you have the choice.

Architecture map

Entry points: src/cli.ts — arg parsing (parseArgs, consumeBridgeModeFlag), help texts, and dispatch for claude, server, models/favorites, providers, patch, install-vscode-launcher — and src/claude-wrapper.ts (the clodex-claude bin). Every other module is a focused unit with no side effects at import time.

Two bridge modes, supported by both clodex claude and clodex server:

  • endpoint — a local Anthropic-format gateway; the child gets ANTHROPIC_BASE_URL.
  • proxy — selective MITM of api.anthropic.com; Claude Code keeps its normal Anthropic auth and only clodex:{provider}:{model} ids and saved aliases route to their configured providers. This is the default.

Details, including bridge-mode persistence rules, are in .claude/docs/launch-and-wrapper.md.

The single translation path is src/sdk-adapter.ts + src/provider-factory.ts (Anthropic /v1/messages ↔ Vercel AI SDK, one turn per request — Claude Code owns the tool loop). There is no hand-rolled per-provider translation; don't add one. See .claude/docs/translation.md.

Cross-cutting invariants that are easy to break

These bite from outside the subsystem that owns them, so they live here rather than in a deep doc.

  • The proxy-mode MITM forwards request bodies unrewritten so responses echo the exact model id the client sent. Substituting the canonical id made patched/alias ids miss their window config, auto-compact never fired, and agents died with "Prompt is too long". Keep it that way.

    Keep the invariant; do not reuse the mechanism that used to be written here. The claim that Claude Code reads its window from the response model field does not hold in 2.1.261, and repeating it cost a review. What the echo still buys is that the request id and the id the client keys its own state on stay the same object — which is reason enough not to rewrite bodies. Current internals live in .claude/docs/claude-code-internals.md; read that rather than re-deriving, and re-stamp it when you verify against a new release.

  • Report the provider's real context window; hold nothing back. Claude Code already reserves min(maxOutputTokens, 20,000) + 13,000 below whatever window it is told — 33,000 for every clodex identity — and applies no percentage of its own on the default path, so a window clodex shrinks first is context the user simply loses. clodex once imposed a 95% share on ChatGPT OAuth models; the catalog never asked for it. Honour a share a provider declares, never invent one.
  • Anthropic-passthrough base URLs must NOT include /v1 — the Anthropic SDK appends /v1/messages itself.
  • The alias IS the model identity once a binary is patched: the short name is what lands in the Agent-tool enum, is sent, is echoed, and keys the context-window map. Full rules in .claude/docs/patcher.md.
  • Do not restructure src/oauth/responses-websocket.ts or src/sdk-adapter.ts. The continuation and translation logic took extensive real-world testing. Surgical changes only.
  • ~/.claude/settings.json is never touched by clodex. Launch config is env-var-only (plus --model), child process only.
  • tweakcc's current node-lief loaders import prebuilds by path. The old direct node-gyp-build dependency is no longer needed. npm users have no lockfile: a new node-lief 1.x resolved at install time can repeat the 1.3.1 fault without a clodex change. If a fresh install reports Could not extract JS or `node-lief` is not available, check node-lief's loader first. See .claude/docs/patcher.md.
  • clodex always installs package undici's global fetch dispatcher with HTTP/2 disabled (installOutboundDispatcher() at the top of main()), proxy env or not. Node 26's bundled undici 8 negotiates HTTP/2 and keeps a dead pooled session forever after a fatal TLS alert, so every request to that origin fails until restart (#233); Node 24 CI cannot see that. Do not gate the install on proxy env again and do not drop the explicit allowH2: false because "undici 7 already defaults to it" — the option is what survives an undici 8 bump.
  • Never call process.exit() in src/; end through exitAfterDrain() (src/process-exit.ts). On Node 24 process.exit() can hang forever (nodejs/node#64274), so both bins set the exit code and let the event loop drain, falling back to process.exit() after one second. That only works if nothing holds the loop: background work that nothing awaits (the models.dev refresh, the pricing enrichment, a WebSocket's closing handshake, outbound connections still being opened) registers cancelOnExit() so it is cut off as process.exit() used to cut it off. Run with CLODEX_TRACE=1 to see what held the loop when the fallback fires.
  • Every AI SDK generation entry point must resolve its timeout and retry budget through src/upstream-retry.ts. Anthropic- and OpenAI-format streamText consumers abort at idle and total deadlines; generateText consumers abort at total only. Cancellation remains cooperative with the provider transport. Raw relays are not SDK generations and use no shared timeout. Details in .claude/docs/oauth-continuation.md.

Tests

tests/ is almost all pure functions — adapter, provider factory, proxy, http-proxy routes, registry, config, bridge-mode persistence, help text, and patcher (config building, hash stability, manifest staleness, lock behavior, per-site transforms).

The exception is tests/patcher-command.test.ts, a genuine end-to-end exercise of clodex patch and the only automated coverage of runPatchCommand: it drives the real command against fake claude "binaries" (shell scripts answering --version and carrying a bundle payload after a sentinel) with tweakcc's three API calls mocked, covering version resolution, backup selection, the poisoned/corrupt-backup refusals, --restore, and the manifest without touching a real install.

Interactive launch flow and real-provider behavior are verified manually.

Nothing automated touches a real Claude Code binary, so nothing automated can see a break that is specific to one executable format. That is not hypothetical: clodex patch was broken on every ELF build of Claude Code across two releases while macOS stayed green. Before changing src/bun-module-table.ts or anything else in the read/repack/publish path, run scripts/probe-patch-mechanism.mjs against a build for each format — Mach-O, ELF and PE. It needs no Linux or Windows host, because it never executes the binary. See .claude/docs/patcher.md.

A green macOS/Windows run says nothing about ELF. Claude Code 2.1.257 moved the global Bun reads its blob's address from off the 16 KiB boundary tweakcc's ELF repack scans for it, and clodex patch failed on all four ELF builds while Mach-O and PE stayed green — Mach-O and PE assign the section in place and rewrite no pointer. src/bun-compiled-pointer.ts works around it; see .claude/docs/patcher.md.

Patch anchors are not platform-independent either. Claude Code 2.1.238 minified one helper's parameter differently on its arm64 builds, so PATCH 5: model picker options matched five builds and missed linux-arm64, linux-arm64-musl and win32-arm64. The probe now applies every patch site to each build's own bundle; run it per format when you touch src/patch-transforms.ts too.

claude -p end-to-end tests are manual only — NEVER add them to the automated suite.

tests/vscode-launcher.windows.test.ts and tests/wrapper-substitution.windows.test.ts run only on the windows-launcher CI job (windows-latest, after pnpm build): the first compiles the Windows VS Code launcher with the runner's real csc.exe and drives the resulting .exe; the second patches a compiled fake claude.exe with the real clodex patch and proves the launcher runs it in place of a pristine copy, after pinning what Node reports about files on NTFS. Both are skipped everywhere else; pnpm test on macOS or Linux says nothing about them. See .claude/docs/launch-and-wrapper.md.

Key constraints

  • --dry-run skips all writes (including bridge-mode persistence).
  • The ::ts:: separator in tool_use ids encodes reasoning signatures for round-tripping; would only break if a signature literally contained ::ts::.
  • In endpoint switch-menu mode the displayed context window reflects the launch model and does not update on live /model switch (Claude Code fetches /v1/models once at startup). Proxy mode
    • clodex patch reports correct per-model windows.
  • Cost display in Claude Code is always inaccurate for routed third-party models (Claude Code applies its own pricing table).
  • MAX_MODEL_CATALOG = 20 (constants.ts) — favorites cap and max catalog routes.
  • OpenAI catalog ids may differ from upstream API ids — upstreamModelId carries the real API id.
  • Never commit dist/ (gitignored, rebuilt by CI), never hardcode a version string (package.json is the source of truth), and never run npm publish locally.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.