Alloy'd

Why it exists

I built Alloy'd because I pay for two AI subscriptions, Claude and ChatGPT, and I kept burning through one plan's usage window while the other sat mostly idle. The idea is to make both Claude Code and Codex ambiently aware of a router, so that substantial work units get dispatched to whichever subscription has more headroom, through the official claude -p and codex exec interfaces, on subscription auth only.

It is important to understand that this is load-balancing rather than extra capacity. Each provider still meters and enforces its own limits, and total compute may even rise slightly by design, since dispatched work starts cold and needs a self-contained brief.

Quick start

npm install -g github:SeanL128/alloyd
alloyd setup   # wires the usage-cache hook + Codex side, prints the rest
alloyd         # which CLI should drive this session?

Requires macOS or Linux, Node 23.6+, and the Claude Code and Codex CLIs signed in on subscription auth; the dispatch pipeline refuses to run on API-key auth, since API keys bypass the meter it exists to balance. alloyd setup handles the Codex integration, the statusline cache hook, and the ambient rule in your CLAUDE.md itself, then prints the few remaining steps it cannot do for you: installing the Claude Code plugin, which registers the dispatch MCP tool and an enforcement hook, and approving Codex's one-time hook trust prompt.

Commands

Everything lives under one binary; docs/USAGE.md in the repo carries the full reference.

• alloyd / alloyd status Reads both usage meters and answers which CLI should drive this session. Flags: --json, --no-probe.
• alloyd dispatch <role> --brief <path.json> Routes one work unit: resolves the role against config and live usage, then runs the vendor command. --dry-run prints the route without executing.
• alloyd setup Wires the statusline cache hook, both ambient rules, and the whole Codex side, idempotently with backups, then prints what remains.
• alloyd update Re-runs the same wiring after upgrading alloyd, preserving your chosen dispatch mode and settings.
• alloyd mode <mcp|cli> Switches both vendors' ambient rules between MCP-tool dispatch and `alloyd dispatch` shell calls.

Dispatch defaults to the MCP tool because models invoke tools more reliably than they follow shell instructions in prose, and a missed dispatch costs more meter spread than a tool schema costs tokens. The CLI mode keeps the schema out of context entirely for anyone optimizing token use.

Configuration

Nothing is baked into code. config/default.json ships a starting map derived from published benchmarks, every part of it is user-editable, and ALLOYD_CONFIG points the router at your own file.

• roles User-defined aliases like planner, builder, and reviewer, each mapping to a vendor, model, and effort level. object
• bands Cross-vendor equivalence tiers (frontier, value, cheap) used to substitute an equal-caliber model when failing over between vendors. array
• dispatch Command templates per vendor, with required {model}, {effort}, and {prompt} placeholders. object

How it works

The routing core is a pure, deterministic primitive: given a work unit labeled with a role, it resolves the role to a vendor, model, effort, and dispatch command against the user's config and live usage, then executes it. An optional suggester can classify raw task text into a role first, but it never makes the routing decision.

Live usage comes from first-party data on both sides. A statusline hook caches Claude Code's rate-limit payload to a plain file, and the router parses Codex's local session logs for their rate-limit records. Both sources carry a staleness TTL: stale Codex data triggers an active no-op probe, while stale Claude data degrades to static role-split routing, since headless Claude cannot refresh the cache. Either CLI can drive, and either can route work to the other.

Status & roadmap

The full v1 is built and merged with 76 tests passing, and the repo is being packaged for public release.

• Routing core with usage-aware policy and cross-vendor failoverDone
• MCP dispatch server plus the alloyd CLI (status, dispatch, setup)Done
• Claude Code plugin and scripted Codex setup, each with an enforcement hookDone
• Benchmark-derived default bands and effortsDone
• Native Windows support (platform-aware dispatch quoting)Planned
• Thin CLI launcher that renders the official CLIs' streamed eventsPlanned

What I learned / what broke

The recurring theme was that the ground truth for vendor integrations lives in the binaries, not the docs. Codex's hooks file turned out to use a nested schema that I only caught by checking against the actual CLI after shipping a flat version that silently did nothing, and the usage sources on the two sides ended up asymmetric in a way I did not expect, which forced the whole policy layer to be swappable so that stale or broken data degrades to static routing rather than failure.

Disclaimer

Alloy'd is an independent project with no affiliation with, or endorsement by, Anthropic or OpenAI. It invokes each provider's official CLI on your own accounts, each provider continues to meter and enforce its own usage limits, and it does not bypass quotas or grant capacity beyond what you purchased. You are responsible for your accounts and your compliance with the terms that apply to you; the project's terms-of-service assessment lives in the repo's COMPLIANCE.md.