Coding agents¶

Point a coding agent at the LLM proxy so it uses your Hawk model access, attributed to you, instead of a personal API key. Setup writes the tool's own configuration — no wrapper, no shell alias — so the tool keeps working when an editor launches it.

hawk login                             # once per deployment on this machine
hawk proxy setup-client claude-code    # writes Claude Code's own config
claude                                 # no wrapper, no flags

What it writes¶

To ~/.claude/settings.json — or $CLAUDE_CONFIG_DIR/settings.json, which is where Claude Code keeps its user configuration when that variable is set (--scope selects a project file instead): apiKeyHelper, and the env keys ANTHROPIC_BASE_URL, HAWK_API_URL, CLAUDE_CODE_API_KEY_HELPER_TTL_MS, HAWK_VERSION_CHECK and — where they apply — ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL, CLAUDE_CODE_MAX_CONTEXT_TOKENS. Nothing else in the file is touched, except an ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in the same env block, which would beat the apiKeyHelper and 401 every request: setup removes it, and remove puts it back. If you have exactly one usable model it is pinned for you; otherwise pass --model (hawk models -i claude lists yours). ANTHROPIC_SMALL_FAST_MODEL is written only when you pass --small-fast-model, or when that one usable model is the only thing you could run background work on — otherwise Claude Code picks its own background model rather than billing that work at --model rates.

The pinned API and Anthropic URLs keep the helper on the selected deployment and Claude Code on the selected proxy when run from another directory. To move Claude Code to a different deployment or proxy, log in there and re-run setup.

hawk auth access-token exports a token for the selected deployment. Hawk checks destinations for its own authenticated requests; the consuming tool controls where it sends an exported token. The helper does not inspect provider endpoint variables or the tool's configuration.

To see what your agent actually sent and received, see Your own Middleman traffic.

Checking and undoing¶

hawk proxy setup-client claude-code --dry-run   # print the diff, write nothing
hawk proxy setup-client doctor                  # check without configuring
hawk proxy setup-client status                  # what is configured, and where
hawk proxy setup-client remove claude-code      # put back what was there before

doctor stops at the first check that fails and names the remedy:

$ hawk proxy setup-client doctor
[OK  ] hawk command  /home/you/.local/bin/hawk
[FAIL] environment  no deployment to configure against
         Run `hawk login` against the deployment you want, or pass --api-url.
Error: environment: no deployment to configure against

Both commands finish by running an apiKeyHelper and sending its token to the proxy — the two steps Claude Code itself takes — so a helper that cannot run is caught here rather than at first use. doctor runs the configuration that is already there, naming the file it checked, and falls back to what setup would write only when nothing is configured.

Setup backs up any file it is about to change, under ~/.config/hawk-cli/backups/, and tells you where. remove puts your original back and deletes the backup.

Common problems¶

Message	Do this
`<host> could not be reached`	The proxy may be on a private network. Connect to it and retry.
`ANTHROPIC_AUTH_TOKEN is exported …` (or `ANTHROPIC_API_KEY`)	Unset it. It takes precedence over the `apiKeyHelper`, so Claude Code sends it instead of your Hawk token and requests 401. Setup removes one it finds in the settings file, but cannot touch an exported value.
A `.env` changes the deployment or proxy URL	Each deployment uses its own saved login, and tokens can only go to approved recipients. Remove an unintended override, or run `hawk login` to approve the new recipient. `--yes` cannot bypass this check; unrelated service settings do not invalidate the login.
`The apiKeyHelper … does not run` (`hawk wrote`, `hawk would write`, or `in <file>`)	Usually `--hawk-command` named a path that is not there, or `hawk` has moved since setup ran. Re-run setup, passing `--hawk-command` with the full path to `hawk`.
`Setup is incomplete: Claude Code has no model it can call`	The config was written, but this account has no model for this tool on this deployment. Access granted moments ago may still be propagating — otherwise ask for a model group.

Only Claude Code is supported so far — PRs adding other tools are welcome.