https://github.com/fajarhide/heimsense
Run Claude Code with any LLM. Single binary API adapter.
https://github.com/fajarhide/heimsense
antrophic api-adapter claude-code cli deepseek golang groq llm openai proxy
Last synced: 3 months ago
JSON representation
Run Claude Code with any LLM. Single binary API adapter.
- Host: GitHub
- URL: https://github.com/fajarhide/heimsense
- Owner: fajarhide
- License: mit
- Created: 2026-03-25T12:38:25.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T11:37:26.000Z (3 months ago)
- Last Synced: 2026-03-31T13:29:06.252Z (3 months ago)
- Topics: antrophic, api-adapter, claude-code, cli, deepseek, golang, groq, llm, openai, proxy
- Language: Go
- Homepage:
- Size: 68.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Heimsense
Heimsense is a lightweight, production-ready API adapter that enables the use of the Claude Code CLI with any LLM provider, such as OpenAI, DeepSeek, Groq, or local models. It functions by translating Anthropic's API protocol to the OpenAI format and vice-versa.
Delivered as a single compiled Go binary, Heimsense eliminates the need for Python or Node.js runtime environments.
```text
Claude Code CLI ────► [ Heimsense ] ────► Any LLM Provider
(Anthropic format) [ :8080 ] (OpenAI format)
```
## Features
* **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.
---
## Quick Start
### 1. Installation
Execute the installation script to download the appropriate binary for your operating system to `~/.local/bin/`:
```bash
curl -fsSL https://raw.githubusercontent.com/fajarhide/heimsense/main/scripts/install.sh | bash
```
Alternatively, pre-compiled binaries are available on the [Releases](https://github.com/fajarhide/heimsense/releases) page, or it can be built from source using `make build`.
### 2. Configuration & Execution
Run the interactive setup. This process prompts for your target API key and configures the Claude Code CLI:
```bash
heimsense setup
```
Start the Heimsense server:
```bash
heimsense run
```
### 3. Usage with Claude Code
Open a new terminal session and launch Claude Code:
```bash
claude
# Use the /model command and select "Heimsense Custom Model"
```
---
## Configuration
Configuration is managed via the `~/.heimsense/.env` file. Modify these variables to adjust your provider or model settings.
| Variable | Example | Description |
|----------|---------|-------------|
| `ANTHROPIC_BASE_URL` | `https://api.openai.com/v1` | Target LLM provider API URL |
| `ANTHROPIC_API_KEY` | `sk-...` | Authentication token for the upstream API |
| `ANTHROPIC_CUSTOM_MODEL_OPTION` | `gpt-4o` | Default model when none is specified or mapped |
| `MODEL_MAP_HAIKU` | `gemini-2.5-flash` | (Optional) Redirection for Claude Haiku requests |
| `MODEL_MAP_SONNET` | `gemini-2.5-pro` | (Optional) Redirection for Claude Sonnet requests |
| `MODEL_MAP_OPUS` | `gemini-2.5-pro` | (Optional) Redirection for Claude Opus requests |
| `LISTEN_ADDR` | `:8080` | Local server listening address and port |
*Note: After making manual changes to the `.env` file, execute `heimsense sync` to propagate the updates to Claude Code's configuration.*
---
## Container Deployment
Heimsense is distributed as a compact container image (~15MB) for environments utilizing Docker or Podman.
```bash
# 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
```
---
## Supported Providers
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.
---
## Architecture Overview
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.
---
## Comparison: Why Heimsense
In contrast to similar tools built with Python or Node.js, Heimsense prioritizes simplicity and minimal footprint through its Go implementation:
* **No package managers:** Bypasses `pip`, `npm`, or virtual environments in favor of a standalone binary.
* **Minimal resource usage:** Typical RAM consumption is under 20MB.
* **Integrated CLI:** Dedicated commands (`setup`, `sync`, `run`) streamline the configuration process for Claude Code.
* **Reliability features:** Incorporates exponential backoff retries, graceful shutdown, structured logging, and health monitoring.
---
## Development & API Reference
Standard development commands:
```bash
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
```
API Endpoints
### `POST /v1/messages`
This endpoint handles requests formatted according to the Anthropic API specification:
**Streaming Example:**
```bash
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."}]
}'
```
*(Tool and function calling features are supported)*
### `GET /health`
```bash
curl http://localhost:8080/health
# → {"status":"ok"}
```
## Star History
---
*Heimsense: Inspired by Heimdall, the guardian of the Bifröst bridge.*
**License:** [MIT](./LICENSE)