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 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.

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 is sent as an `Authorization` header, which the proxy's Anthropic route does not read, so requests 401. Setup removes one it finds in the settings file, but cannot touch an exported value.
`./.env sets HAWK_MIDDLEMAN_URL=<host>`	A `.env` in the working directory outranks your own config, and that host would be sent your access token — so setup asks first, and refuses rather than guess when nothing can answer (`--yes` does not waive this). Delete the entry, or export the variable yourself if you meant it.
`./.env sets HAWK_API_URL=<host>`	The same, for the deployment — that host would be sent your refresh token.
`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.