Heimsense

Heimsense runs Claude Code, and agents built on the Anthropic Messages API, on any OpenAI-compatible model: DeepSeek, Groq, OpenAI, OpenRouter, or a model you host yourself. It translates Anthropic requests to the OpenAI format and translates the responses back, including streaming and tool calls.

It ships as one Go binary. No Python, no Node.js, no database.

  Claude Code / your agent ────► [ Heimsense ] ────► Any LLM Provider
     (Anthropic format)          [ :8080     ]       (OpenAI format)

• Developers who want Claude Code's workflow on a cheaper or local model.
• Builders shipping agents to clients. If your agent is built on Claude Code or the Anthropic API and per-token cost decides whether the deal makes money, point it at Heimsense and swap the model without rewriting the agent.
• Teams whose data must stay in-house. Route requests to vLLM or Ollama on your own servers.

Heimsense is an adapter, not an organization-wide AI gateway. If you need virtual keys, per-team budgets, SSO and an admin dashboard, use LiteLLM.

• Provider Flexibility: Compatible with various models including DeepSeek, ChatGPT, Groq, or local options like Ollama.
• Cost Efficiency: Allows utilization of more cost-effective models as alternatives to Anthropic's pricing.
• Zero Dependencies: Distributed as a single Go binary. No external runtime environments required.
• Production Ready: Includes automatic retries on 5xx errors, graceful shutdown, and health check endpoints.
• Automated Setup: Features an interactive CLI to automatically configure Claude Code.

Execute the installation script to download the appropriate binary for your operating system to ~/.local/bin/:

curl -fsSL https://raw.githubusercontent.com/fajarhide/heimsense/main/scripts/install.sh | bash

Alternatively, pre-compiled binaries are available on the Releases page, or it can be built from source using make build.

Run the interactive setup. This process prompts for your target API key and configures the Claude Code CLI:

heimsense setup

Start the Heimsense server:

heimsense run

Open a new terminal session and launch Claude Code:

claude
# Use the /model command and select "Heimsense Custom Model"

Configuration is managed via the ~/.heimsense/.env file. Modify these variables to adjust your provider or model settings.

Note: After making manual changes to the .env file, execute heimsense sync to propagate the updates to Claude Code's configuration.

Heimsense is distributed as a compact container image (~15MB) for environments utilizing Docker or Podman.

# 1. Prepare configuration
cp env.example .env
# Edit .env to set your target API key and Base URL

# 2. Start the container
docker run -d \
  --name heimsense \
  -p 8080:8080 \
  -v $(pwd)/.env:/.env \
  ghcr.io/fajarhide/heimsense:latest

# 3. Configure local Claude Code instance
heimsense setup

Heimsense is compatible with endpoints adhering to the OpenAI API specification, including:

• Cloud Services: OpenAI, DeepSeek, Groq, Together AI, Mistral, xAI (Grok), OpenRouter, Fireworks AI.
• Local Implementations: Ollama, LM Studio, vLLM, LocalAI.

Heimsense operates as a translation proxy layer between the Claude Code client and the target LLM API.

1. The Claude Code client sends queries in the Anthropic format (/v1/messages).
2. Heimsense transforms the request payload into the OpenAI format (/v1/chat/completions).
3. The query is forwarded to the designated LLM provider.
4. The provider's response, including SSE streams and tool/function calls, is translated back to the Anthropic format for consumption by the client.

Most proxies in this space are Python or Node.js apps. Heimsense is one Go binary, so it fits on a laptop, a small VPS, or next to your agent in the same container.

• Nothing to install besides the binary: no pip, npm or virtualenv.
• Typical memory use is under 20MB.
• heimsense setup writes the Claude Code config for you, and heimsense sync updates it after you edit .env.
• Retries 5xx errors with exponential backoff, shuts down gracefully, logs in structured form, and exposes /health.

Standard development commands:

make run        # Build binary and start server
make test       # Execute test suite
make build      # Compile executable to ./bin/
make lint       # Run code formatters and linters

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-key" \
  -d '{
    "model": "gpt-4o",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Explain the concept of an API."}]
  }'

curl http://localhost:8080/health
# → {"status":"ok"}

Heimsense: Inspired by Heimdall, the guardian of the Bifröst bridge.
License: MIT