Small contracts. Composable agents.

Use the hosted API directly, compose the Node packages, or stay inside the CLI. Every surface shares the same routing and permission contract.

Packages#

PackageUse it for
@tokensize/agent-clientShared local discovery, allowance, auth, routing, receipts and feedback.
@tokensize/cliTerminal commands and JSON/human-readable output.
@tokensize/mcpCodex-compatible stdio tools backed by the shared client.
@tokensize/opencodeTyped OpenCode tools with inspect-only execution in beta.
@tokensize/routerRuntime-neutral model selection with no infrastructure lock-in.

Hosted endpoints#

GET/v1/agent-catalog

Check service protocol compatibility and advertised harness support.

POST/v1/agent-routes

Submit task features and candidate metadata for an explainable route.

POST/v1/agent-feedback

Submit receipt-bound, content-free execution feedback.

GET/.well-known/tokensize-agent.json

Discover the registration protocol, credential prefix and privacy boundary.

Configuration#

shell
TOKENSIZE_API_URL=https://api.tokensize.dev
TOKENSIZE_API_KEY=ts_…                 # headless only
TOKENSIZE_HOME=~/.tokensize             # optional local store
TOKENSIZE_ROOT_HARNESS=codex            # embedding surface
TOKENSIZE_ROOT_ACTIVE=1                 # plugin root
TOKENSIZE_ALLOW_SUBSCRIPTION_HARNESSES=codex,claude

Never commit .dev.vars, provider keys or API keys. The browser callback is the recommended interactive setup.

Route request shape#

Contract v2 carries the client surface and active-root state explicitly. The hosted service is not a hidden quality signal or a permission authority.

shell
{
  "schemaVersion": 2,
  "client": { "surface": "codex-plugin", "version": "0.3.0-beta.1" },
  "root": { "harness": "codex", "active": true },
  "routerMode": "metadata-only",
  "policy": { "objective": "balanced", "permissionCeiling": "inspect" }
}