Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ go build -o test-output ./cmd/server && rm test-output # Verify compile (REQUIRE
- Wrap defer errors: `defer func() { if err := f.Close(); err != nil { log.Errorf(...) } }()`
- Use logrus structured logging; avoid leaking secrets/tokens in logs
- Avoid panics in HTTP handlers; prefer logged errors and meaningful HTTP status codes
- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, and the `cmd/fetch_antigravity_models` utility timeouts
- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, the quota-history per-account sample timeout in `internal/quotahistory/recorder.go` (a background usage read, not client traffic), and the `cmd/fetch_antigravity_models` utility timeouts
- Avoid wall-clock `time.Sleep` in TTL, expiration, ordering, or cache-eviction unit tests due to platform timer granularity (e.g. Windows default timer resolution of ~15.6ms) and CI jitter under load; prefer controllable clocks (`nowFunc` / mock clock), explicit timestamp manipulation, or deterministic synchronization primitives.
- Note: `internal/home/` integrates with the separate CLIProxyAPIHome control plane. If you change features that involve it, check whether the CLIProxyAPIHome repository needs a matching update.
- Endpoints under the `/v0/management` base URL are a supported compatibility contract: T3 Code reads the hub through `GET /v0/management/auth-files`, `POST /v0/management/api-call` and `POST /v0/management/reset-quota`, pinned by `test/t3code_contract_test.go`. Do not remove them or change their request or response shapes. Add new management features under `/v8/management`.
61 changes: 61 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,67 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Mistral monthly API and Vibe Code budget history for API-key upstreams on `api.mistral.ai`,
with cached subscription plans and optional `budget` and `currency` window fields. These
usage-only windows use account weight 1.
- Plan-aware routing and pooling. Each account's plan is resolved (Claude Pro, Max 5x, Max 20x;
Codex Plus, Pro, and so on) and given a capacity weight, overridable under
`routing.plan-weights` and readable at `GET /v8/management/routing/plan-weights`.
`soonest-reset-first` spreads new conversations by plan weight where accounts are otherwise
equal, and `routing.plan-headroom-reserve` keeps new conversations off accounts whose 5-hour
window is nearly used while another account has room.
- Quota history and `soonest-reset-first` ranking for xAI, Antigravity, Kimi, Meta, Devin and
quota plugins, next to Claude and Codex. With `quota-history.enabled: true`, an upgraded hub now
polls the usage endpoints of all of these providers by default; `quota-history.providers`
limits which ones.
- Web panel: the same pool card for every provider that reports renewing limits (from recorded
history, or from the latest live read when the recorder does not sample that provider), with
pooled figures in percent of the heaviest plan in the pool ("38% of 120%" for Max 5x + Pro),
plan weights saved on the hub, a group picker for providers with many windows such as
Antigravity, and Connect snippets for OpenAI-compatible tools, OpenCode, Gemini clients and
Muse Code.
- Web panel Overview: a **Pools** / **Resets** switch. Resets is a calendar of every account
window across providers (current, upcoming and elapsed windows with what was left unspent at
each reset, banked Codex reset expiries with **Use reset**, monthly windows on the calendar
month), with a **Next resets** list of the soonest resets and their unspent allowance, a window
filter, and the Pools view's span controls. It replaces the old "Quota windows" timeline.
- Web panel: Mistral, read by the hub with an API key and present only in the quota history, gets
a tab, a pool and calendar lanes; windows with a budget read in money beside percent.
- `scripts/migrate-windows.ps1`, which replaces a running CLIProxyAPI Scheduled Task with
t3code-proxy: verified backup, detached switch, authenticated checks, automatic rollback, and a
named-backup rollback. `t3code-proxy doctor -check-config` validates a config without starting
a server.
- Guides for every provider, for T3 Code environments over Tailscale (including Windows with
WSL 2), and an agent-readable box-setup checklist.

### Changed

- Web panel Overview: account cards are gone. Each row of an accounts table opens that account's
full read in place (windows and resets, plan details, Claude extra usage, Codex banked resets
and credit overage, xAI usage breakdown and pay-as-you-go, Antigravity groups, errors, and the
per-account actions); accounts without a renewing window list in the same table form. The plan
shares caption under the pool headline is removed (the weight editor stays behind the card's
sliders button), and account emails are shown by default with a **Hide emails** toggle.

- A conversation bound by session affinity moves to another account before sending when the hub
already knows a window governing that model is spent on the bound account.
- `soonest-reset-first` skips an account when any window governing the model is spent, and
response headers newer than a recorded reading overrule it.
- Behavior change for hubs already on `soonest-reset-first`: the 5-hour headroom guard is on by
default (`routing.plan-headroom-reserve: 10`; `0` turns it off), and tied accounts are spread
by plan weight instead of evenly.
- New logo: a fox head in profile, white and silver on the black tile.

### Fixed

- `soonest-reset-first` no longer sends new work to an account it knows is spent while the
account with allowance left is only on a short hold. Seen on a live hub: one "overloaded"
answer put the usable Codex account on a five-minute hold and the next conversations were
refused by the spent account with "usage limit reached", valid for two days. The hub now
answers with a cooldown error and the short wait.

## [0.1.0]

First release as t3code-proxy. The code base starts from CLIProxyAPI v8.0.72; see
Expand Down
32 changes: 22 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,23 @@
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

t3code-proxy is a hub for your own Claude and Codex subscriptions. You run it on one machine at
home that stays on. It holds every account login, keeps the tokens fresh, and exposes one
OpenAI- and Claude-compatible API on port 8317. Your other machines reach it over Tailscale, and
Claude Code, Codex and the T3 Code app use it through their normal config files. Nothing on the
client side is patched. The setup follows the one Theo Browne describes in his
t3code-proxy is a hub for your own AI subscriptions and API-key providers. You run it on one
machine at home that stays on. It holds account logins, keeps OAuth tokens fresh, and exposes
OpenAI-, Claude-, Gemini- and Codex-compatible APIs on port 8317. It serves Claude, Codex,
Antigravity, Kimi, xAI, Devin and Meta accounts, Google API keys and OpenAI-compatible upstreams.
Your other machines reach it over Tailscale. Claude Code, Codex and T3 Code use their normal
client configuration. The panel pools supported limits with plan-aware weights. See
[providers](docs/providers.md) for current coverage. The setup follows Theo Browne's
[token maxing video](https://www.youtube.com/watch?v=D8PikZ1KhUo) and
[gist](https://gist.github.com/t3dotgg/59a521d2ee8d70aaf90e280c175072af); his own hub is private,
and this project is an open-source implementation of it.
[gist](https://gist.github.com/t3dotgg/59a521d2ee8d70aaf90e280c175072af). His own hub is private.
This project is an open-source implementation of it.

This project is not affiliated with or endorsed by T3, Anthropic or OpenAI.

**Using subscriptions this way may violate provider terms and can get accounts suspended or
banned. Never serve other people's traffic with your subscriptions. Use Claude subscriptions
only through Claude Code.** Read the [risks and rules](#risks-and-rules) before signing in.

## How it works

```mermaid
Expand All @@ -43,11 +49,12 @@ flowchart LR
hub --- auth
hub --> anthropic["Anthropic"]
hub --> openai["OpenAI"]
hub --> others["Google, Kimi, xAI, Devin, Meta<br/>and compatible upstreams"]
```

The hub listens on loopback only. `tailscale serve` publishes it to your tailnet over HTTPS, so
only devices on your tailnet can reach it. Every request to Anthropic and OpenAI leaves from the
hub's home connection.
only devices on your tailnet can reach it. Provider requests leave from the hub's home connection.
T3 Code can run agents on any connected home or cloud [environment](docs/environments.md).

## Features

Expand All @@ -60,7 +67,9 @@ hub's home connection.
- **Codex over WebSockets.** Codex clients that set `supports_websockets = true` use the
WebSocket transport through the hub.
- **Quota history.** The hub records each Claude and Codex account's quota windows over time.
See [quota history](docs/quota-history.md).
The panel's pooled charts support editable plan weights, so accounts on different plans can
contribute different capacity. See [quota history](docs/quota-history.md) and the
[provider capability table](docs/providers.md#capability-table).
- **Web panel.** A management panel is compiled into the binary and served at
`/management.html`: pooled limits and banked Codex reset credits, accounts, sign-in, routing,
activity, providers, logs and settings, plus a Connect page with ready-to-paste client config
Expand Down Expand Up @@ -115,6 +124,9 @@ second config directory that leaves your normal client setup untouched.
## Documentation

- [Setup guide](docs/setup.md): pick a hub, install, sign in, connect clients.
- [Providers](docs/providers.md) covers every login, API-key upstream and current quota capability.
- [Environments](docs/environments.md) covers T3 Code on other machines, including Windows and WSL 2.
- [Set up a box](docs/box-setup.md) gives an ordered agent checklist for a new execution machine.
- [Guide for coding agents](docs/agents.md): for an agent doing the setup on someone's behalf.
- [T3 Code](docs/t3code.md): providers, usage provider and limits.
- [Routing](docs/routing.md): strategies, soonest-reset-first, session affinity, retries.
Expand Down
20 changes: 11 additions & 9 deletions assets/brand/banner-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 11 additions & 9 deletions assets/brand/banner-light.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading