macaz

Use your favorite models and providers with your favorite coding agents.

macaz connects locally installed coding agents with a model provider chosen by
the user. It starts Claude Code or Codex CLI and routes model interactions while
the selected agent continues to own its local tools, permissions, sessions,
skills, and user interface.

macaz is free and open-source software licensed under Apache-2.0. Every build
contains the complete feature set.

[!IMPORTANT]
macaz is an independent interoperability project. It is not affiliated with,
authorized by, endorsed by, or sponsored by Anthropic, OpenAI, or any other
client or model provider. Claude Code and Codex CLI are separate products that
must be obtained from their authorized sources. Each product and provider
remains subject to its own current terms.

Read LEGAL.md and PRIVACY.md before use.

What it does

macaz claude   # Claude Code through the selected provider
macaz codex    # Codex CLI through the selected provider

The two clients have independent provider/model configuration and isolated
macaz profiles. For example, macaz claude can use an OpenAI model while
macaz codex uses the official Anthropic API. macaz reset codex changes
neither the Claude configuration nor shared provider credentials.

The local routing layer translates both directions:

• Anthropic Messages requests and streams used by Claude Code;
• OpenAI Responses requests and streams used by Codex CLI;
• text, images, supported document inputs, reasoning effort, usage, errors,
  function tools, Codex custom/free-form tools, and tool namespaces; and
• live provider model catalogs into each client's native /model interface.

Client-executed tools stay in the client. Shell commands, file edits,
apply_patch, skills, hooks, MCP tools, namespaced tools, and subagents are not
executed by macaz or by an upstream CLI adapter. Normal client permission and
sandbox behavior is preserved unless the user explicitly passes that client's
own bypass option.

Server-executed tools are different: a tool such as provider-hosted web
search is available only when the selected provider exposes a compatible
server implementation. macaz disables Codex's OpenAI-hosted web-search request
for provider-neutral sessions rather than silently pretending another provider
can execute it. Local function, custom, namespace, and MCP tools remain
available.

No translation can make different proprietary models semantically identical.
The compatibility target is correct protocol and local-tool behavior without a
hidden provider fallback.

Install

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/macaz-dev/macaz-cli/main/scripts/install.sh | sh

The installer selects the platform release, requires its entry in
SHA256SUMS, verifies SHA-256, and installs to $HOME/.local/bin by default.
Pin a release with --version:

curl -fsSL https://raw.githubusercontent.com/macaz-dev/macaz-cli/main/scripts/install.sh |
  sh -s -- --version 0.2.0

Windows binaries and other release files are published on
GitHub Releases.

Install the latest release in place later with:

macaz update

The updater downloads only the exact asset for the current platform, verifies
the release checksums and embedded version, and replaces the executable with
rollback protection. It does not send prompts, source code, configuration, or
provider credentials.

Release builds perform a short best-effort update check on startup. The check
never installs automatically and does not block offline use. Disable it with:

export MACAZ_NO_UPDATE_CHECK=1

Requirements

• Go is needed only when building from source.
• claude must be on PATH to use macaz claude.
• codex must be on PATH to use macaz codex.
• opencode is required only when OpenCode CLI is the selected provider. Local
  agent auth reads existing Codex, OpenCode, or Pi credentials directly and
  does not start those CLIs.
• A browser is used by the OpenAI Subscription authorization flow.

Claude Code, Codex CLI, and OpenCode are not bundled or redistributed.

Setup and providers

The first invocation of each client opens its own setup:

macaz claude
macaz codex

Available upstreams:

API keys and OAuth credentials configured by macaz are stored in the
operating-system credential store, not in config.json. Local agent auth
instead uses a selected credential from Codex's, OpenCode's, or Pi's
auth.json. Supported discoveries are appended directly to the provider menu
and identify both the source agent and whether the credential is an API key or
a subscription. The initial direct adapter supports OpenAI OAuth and API-key
entries. OAuth refreshes are written back to that same file under the source's
compatible lock where one exists, with stale-token conflict detection so the
source agent and macaz keep one credential source. The Anthropic option uses an Anthropic API key and
the public Messages API; it does not use or convert a Claude consumer
subscription. Anthropic model IDs, token limits, input capabilities, and effort
levels are read from the account's live Models API during setup and startup.

Manual provider accepts either an OpenAI-compatible base URL (including its
port) plus a model ID, or an explicit path to a nonstandard Codex, OpenCode, or
Pi auth.json. A base URL without a path is normalized to /v1. Manual local
endpoints do not require or send an API key.

Each start refreshes the active provider catalog. The resulting public model
IDs and supported reasoning levels are written to the isolated client profile,
so model selection works through Claude Code's or Codex CLI's native /model
interface. The configured provider default is selected at launch; interactive
changes follow the selected client's normal session behavior.

Commands

macaz claude [args...]    Start Claude Code
macaz codex [args...]     Start Codex CLI
macaz status [client]     Check the configured provider and model catalog
macaz doctor [client]     Check the client executable and provider
macaz reset [client]      Reset one client, or all macaz state when omitted
macaz legal               Show the compatibility notice
macaz update              Install the latest verified release
macaz version             Show the installed version

Arguments after macaz claude or macaz codex are forwarded to that client,
except model/provider/profile overrides that would bypass macaz's authenticated
local routing layer.

Examples:

macaz claude --dangerously-skip-permissions
macaz codex --sandbox workspace-write
macaz status codex
macaz doctor claude
macaz reset codex

macaz reset claude or macaz reset codex removes only that client's macaz
configuration and isolated profile. It preserves the other client and shared
provider credentials. macaz reset with no client removes both macaz profiles,
all macaz-managed credentials, configuration, and isolated session history. It
does not remove normal vendor-client profiles or credentials managed directly
by vendor CLIs.

Claude MCP servers

On each macaz claude start, macaz imports user- and local-scoped MCP server
definitions from the normal Claude Code state into the isolated macaz Claude
profile. This lets the same locally configured MCP servers load in normal
Claude Code and through macaz without copying the rest of Claude's identity,
session, trust, or onboarding state. Project-scoped .mcp.json files remain
project files and are discovered normally by both profiles; Claude Code may ask
for approval once per profile.

[!NOTE]
Claude.ai account connectors are not local MCP definitions and cannot be
imported this way. Claude Code fetches those connectors only while its active
authentication method is a Claude.ai subscription; it does not load them when
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or a third-party provider is
active. Macaz must set a local authentication token to route model requests,
so entries such as claude.ai Google Drive, claude.ai Google Calendar, and
claude.ai Gmail shown by normal claude mcp list are unavailable through
macaz. See the official
Claude Code MCP documentation.

The normal Claude profile is authoritative for an imported server name:

• additions and updates are refreshed into the macaz profile at startup;
• a removal deletes the prior imported copy when that copy was not changed in
  the macaz profile; and
• MCP servers with names that exist only in the macaz profile are preserved.

Change or remove an imported server with the normal claude mcp command; the
next macaz start will refresh that change. Use macaz claude mcp add or
remove for servers intended to exist only in the isolated macaz profile.

Only local MCP definitions are imported. Definitions can themselves contain
command arguments, URLs, headers, or environment variables, so the isolated
copy is written with private file permissions. Claude Code authentication,
Claude.ai connectors, and generic profile state are not copied. A standard
OAuth-backed MCP server may require a separate login for the isolated profile:

macaz claude mcp login SERVER_NAME

Inspect or manage the resulting profile with Claude Code's normal MCP commands:

macaz claude mcp list
macaz claude mcp get SERVER_NAME
macaz claude mcp add --scope user SERVER_NAME -- COMMAND ARGUMENTS...
macaz claude mcp remove --scope user SERVER_NAME

Isolation and security

• The local routing layer listens on a random 127.0.0.1 port.
• A new random authentication token is generated for every launch.
• The token exists only in the child process environment.
• Config and profile files use private permissions where supported.
• Normal Claude and Codex profiles are not modified. Claude MCP definitions are
  read and copied into the isolated macaz profile as described above.
• The local routing process stops when the launched client exits.
• There is no fallback to a different provider or official model.
• macaz contains no project-operated analytics or telemetry client.

The isolated profiles may contain client-owned session history. See
PRIVACY.md for exact data flow and deletion behavior.

Provider notes

• OpenAI API and OpenRouter use Responses-compatible HTTP adapters. They reject
  truncated streams and invalid tool arguments instead of returning partial
  success. OpenRouter also receives a per-session/per-agent sticky routing key
  without changing the selected model.
• OpenAI Subscription uses device authorization, refreshes credentials, and
  applies bounded account retry/backoff. It is experimental and remains
  subject to OpenAI's current account terms.
• Anthropic API uses native /v1/models, /v1/messages, and
  /v1/messages/count_tokens. Responses custom tools are converted to normal
  Anthropic tools with a typed raw-input wrapper and converted back before
  Codex executes them.
• Codex CLI as a provider uses codex app-server only as the authenticated
  transport and is offered only to the Claude client; using Codex as both
  client and upstream would recurse. Macaz derives a private temporary model
  catalog from Codex's local model caches, including the default profile,
  CODEX_HOME, sibling profiles, and profiles reported by wrapper executables.
  Malformed cache revisions are skipped when another valid profile is
  available; MACAZ_CODEX_MODEL_CATALOG can explicitly select a fully custom
  catalog path. Macaz normalizes supported Codex catalog schema revisions,
  selects direct tool calling, disables Codex execution environments, and
  leaves every source cache unchanged. Claude
  executes client tools and macaz returns each structured result to the same
  app-server thread. Pending turns are isolated by Claude session and agent and
  expire after five minutes. Macaz reserves one CLI slot for new traffic;
  excess pending turns use the safe interrupted-turn fallback instead of
  starving the pool. If the Codex model cache is missing, run Codex once before
  using this experimental bridge.
• OpenCode CLI uses an isolated request-scoped provider configuration. Its
  project tools and context are not exposed as a second agent layer.
• Local agent auth bypasses the source agent runtime and uses a selected Codex,
  OpenCode, or Pi credential. The OpenAI adapter follows the same direct API and
  subscription paths as macaz's native OpenAI providers.
• Claude Code controls skill and subagent fan-out. Parallel subagents and Auto
  mode classifier checks can consume substantially more provider usage than a
  single-agent Codex session. Macaz keeps the user's selected model for main,
  background, and subagent work, while OpenAI Subscription fan-out is bounded
  to four concurrent upstream requests by default. Advanced users can change
  max_concurrent_subscription_requests in config.json.
• Macaz keeps the exact selected model for main, background, classifier, and
  subagent paths. It sets Claude's automatic compact window only when the active
  provider reports a context limit, and caps reasoning effort only for Claude's
  dedicated conversation-compaction request. The default reasoning effort is
  medium and can be changed with default_effort in config.json.

Local development

Go 1.26.5 or newer is required.

Run from source:

go run ./cmd/macaz version
go run ./cmd/macaz claude
go run ./cmd/macaz codex

Build and run a local binary:

go build -o ./macaz ./cmd/macaz
./macaz version
./macaz codex

Run verification:

go mod verify
go test ./...
go vet ./...
go test -race ./...

Build a complete local release package into ignored dist/:

./scripts/build-release.sh v1.0.0

The release script requires an empty output directory and creates static
macOS, Linux, and Windows binaries for amd64 and arm64, plus SHA256SUMS for
installer and updater verification. To choose another empty directory:

OUTPUT_DIR=/tmp/macaz-release ./scripts/build-release.sh v1.0.0

Opt-in live-provider tests never run in normal CI:

MACAZ_OPENAI_API_INTEGRATION_MODEL=<model> go test ./internal/provider/openai -run LiveOpenAIAPI
MACAZ_OPENAI_SUBSCRIPTION_INTEGRATION_MODEL=<model> go test ./internal/provider/openai -run LiveOpenAISubscription
MACAZ_OPENROUTER_INTEGRATION_MODEL=<provider/model> go test ./internal/provider/openrouter -run LiveOpenRouter
MACAZ_CODEX_INTEGRATION_EXECUTABLE=<codex-or-compatible> go test ./internal/provider/codexcli -run LiveCodex
MACAZ_OPENCODE_INTEGRATION_MODEL=<provider/model> go test ./internal/provider/opencodecli -run LiveOpenCode
MACAZ_CLAUDE_INTEGRATION=1 go test ./internal/app -run LiveClaudeLifecycle

Every merged pull request on main is verified, assigned the next SemVer tag,
built for all supported platforms, and published as a GitHub Release with
checksums, generated release notes, and provenance when the repository is
public. The default bump is patch; the release:minor and release:major
labels select larger bumps.

License

Apache License 2.0. See LICENSE, NOTICE, and
THIRD_PARTY_NOTICES.md.