@hera-al/atn-proxy

Part of Hera Artificial Life — an opinionated AI assistant platform that runs locally on your machine. This package provides the tool name translation proxy used by Hera agents to communicate with OpenAI-compatible endpoints. It can also be used independently in any Node.js project.

Anthropic Tool Name Proxy — sits between the Claude Agent SDK and OpenAI-compatible endpoints (e.g. OpenRouter), resolving the 64-character tool name limit.

Agent SDK  -->  ATN-Proxy (:4181)  -->  OpenRouter  -->  Model

What it does

| Direction | Action | |-----------|--------| | Request | Truncates tools[].name to 64 chars using a deterministic hash suffix | | Request | Rewrites ?beta=true query param into the anthropic-beta header | | Request | Truncates tool_use.name in conversation history to match | | Response | Remaps truncated tool names back to originals (stream + non-stream) | | Response | Normalizes usage{} to Anthropic format (missing fields default to 0) | | Response | Wraps non-JSON responses (HTML 404) into Anthropic-compatible errors | | Response | Handles /count_tokens locally with a token estimate |

Install

npm install -g @hera-al/atn-proxy

Or run from source:

git clone https://github.com/hera-artificial-life/hera-al.git
cd hera-al/atn-proxy
npm install
npm run build

Usage

# Start with defaults (port 4181, target openrouter.ai)
atn-proxy

# Custom port and verbose logging
atn-proxy --port 8080 --verbose

# Show all options
atn-proxy --help

Options

| Flag | Default | Description | |------|---------|-------------| | --port <n> | 4181 (env: PORT) | Listen port | | --target <url> | https://openrouter.ai | Upstream endpoint | | --prefix <path> | /api | Target path prefix | | --max-name <n> | 64 | Max tool name length | | --logs <dir> | ./logs | Log directory | | --verbose | off (env: VERBOSE=1) | Debug logging |

Connect the Agent SDK

ANTHROPIC_BASE_URL=http://localhost:4181 \
ANTHROPIC_AUTH_TOKEN=sk-or-v1-xxx \
ANTHROPIC_API_KEY="" \
node your-agent.mjs

Logging

Logs are written to ./logs/atn-proxy.log with automatic rotation:

• Max file size: 10 MB
• Rotated files: up to 9 (atn-proxy.1.log ... atn-proxy.9.log)

How tool name truncation works

When a tool name exceeds the max length, ATN-Proxy generates a deterministic short name by keeping a readable prefix and appending an 8-char SHA-256 hash:

mcp__very-long-server-name__very_long_tool_name
  --> mcp__very-long-server-name__very_long_t_a1b2c3d4

The mapping is maintained in memory for the proxy session. Response tool names are automatically restored to the originals before reaching the SDK.

License

MIT