{"id":47727535,"url":"https://github.com/fajarhide/heimsense","last_synced_at":"2026-04-02T20:54:48.678Z","repository":{"id":348255842,"uuid":"1191627761","full_name":"fajarhide/heimsense","owner":"fajarhide","description":"Run Claude Code with any LLM. Single binary API adapter.","archived":false,"fork":false,"pushed_at":"2026-03-31T11:37:26.000Z","size":70,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T13:29:06.252Z","etag":null,"topics":["antrophic","api-adapter","claude-code","cli","deepseek","golang","groq","llm","openai","proxy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fajarhide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"fajarhide","ko_fi":"fajarhide"}},"created_at":"2026-03-25T12:38:25.000Z","updated_at":"2026-03-31T11:37:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fajarhide/heimsense","commit_stats":null,"previous_names":["fajarhide/heimsense"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fajarhide/heimsense","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fajarhide%2Fheimsense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fajarhide%2Fheimsense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fajarhide%2Fheimsense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fajarhide%2Fheimsense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fajarhide","download_url":"https://codeload.github.com/fajarhide/heimsense/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fajarhide%2Fheimsense/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antrophic","api-adapter","claude-code","cli","deepseek","golang","groq","llm","openai","proxy"],"created_at":"2026-04-02T20:54:48.032Z","updated_at":"2026-04-02T20:54:48.670Z","avatar_url":"https://github.com/fajarhide.png","language":"Go","funding_links":["https://github.com/sponsors/fajarhide","https://ko-fi.com/fajarhide"],"categories":[],"sub_categories":[],"readme":"# Heimsense\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/fajarhide/heimsense?style=for-the-badge\" alt=\"Stars\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/releases\"\u003e\u003cimg src=\"https://img.shields.io/badge/Updated-Mar_31,_2026-brightgreen?style=for-the-badge\" alt=\"Last Update\"/\u003e\u003c/a\u003e\n  \u003ca href=\"./go.mod\"\u003e\u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white\" alt=\"Go Version\"/\u003e\u003c/a\u003e\n  \u003ca href=\"#supported-providers\"\u003e\u003cimg src=\"https://img.shields.io/badge/Providers-20+-orange?style=for-the-badge\" alt=\"Supported Providers\"/\u003e\u003c/a\u003e\n  \u003ca href=\"./Containerfile\"\u003e\u003cimg src=\"https://img.shields.io/badge/Container-ready-blueviolet?style=for-the-badge\u0026logo=podman\u0026logoColor=white\" alt=\"Container Ready\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/fajarhide/heimsense/ci.yml?style=for-the-badge\u0026label=CI\" alt=\"CI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/release/fajarhide/heimsense?style=for-the-badge\" alt=\"Release Version\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/fajarhide/heimsense.svg\" alt=\"Issues\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fajarhide/heimsense/pulls\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/fajarhide/heimsense.svg\" alt=\"Last Commit\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nHeimsense 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. \n\nDelivered as a single compiled Go binary, Heimsense eliminates the need for Python or Node.js runtime environments.\n\n```text\n  Claude Code CLI ────► [ Heimsense ] ────► Any LLM Provider\n (Anthropic format)     [ :8080     ]       (OpenAI format)\n```\n\n## Features\n\n* **Provider Flexibility:** Compatible with various models including DeepSeek, ChatGPT, Groq, or local options like Ollama.\n* **Cost Efficiency:** Allows utilization of more cost-effective models as alternatives to Anthropic's pricing.\n* **Zero Dependencies:** Distributed as a single Go binary. No external runtime environments required.\n* **Production Ready:** Includes automatic retries on 5xx errors, graceful shutdown, and health check endpoints.\n* **Automated Setup:** Features an interactive CLI to automatically configure Claude Code.\n\n---\n\n## Quick Start\n\n### 1. Installation\n\nExecute the installation script to download the appropriate binary for your operating system to `~/.local/bin/`:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/fajarhide/heimsense/main/scripts/install.sh | bash\n```\n\nAlternatively, 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`.\n\n### 2. Configuration \u0026 Execution\n\nRun the interactive setup. This process prompts for your target API key and configures the Claude Code CLI:\n\n```bash\nheimsense setup\n```\n\nStart the Heimsense server:\n\n```bash\nheimsense run\n```\n\n### 3. Usage with Claude Code\n\nOpen a new terminal session and launch Claude Code:\n\n```bash\nclaude\n# Use the /model command and select \"Heimsense Custom Model\"\n```\n\n---\n\n## Configuration\n\nConfiguration is managed via the `~/.heimsense/.env` file. Modify these variables to adjust your provider or model settings.\n\n| Variable | Example | Description |\n|----------|---------|-------------|\n| `ANTHROPIC_BASE_URL` | `https://api.openai.com/v1` | Target LLM provider API URL |\n| `ANTHROPIC_API_KEY` | `sk-...` | Authentication token for the upstream API |\n| `ANTHROPIC_CUSTOM_MODEL_OPTION` | `gpt-4o` | Default model when none is specified or mapped |\n| `MODEL_MAP_HAIKU` | `gemini-2.5-flash` | (Optional) Redirection for Claude Haiku requests |\n| `MODEL_MAP_SONNET` | `gemini-2.5-pro` | (Optional) Redirection for Claude Sonnet requests |\n| `MODEL_MAP_OPUS` | `gemini-2.5-pro` | (Optional) Redirection for Claude Opus requests |\n| `LISTEN_ADDR` | `:8080` | Local server listening address and port |\n\n*Note: After making manual changes to the `.env` file, execute `heimsense sync` to propagate the updates to Claude Code's configuration.*\n\n---\n\n## Container Deployment\n\nHeimsense is distributed as a compact container image (~15MB) for environments utilizing Docker or Podman.\n\n```bash\n# 1. Prepare configuration\ncp env.example .env\n# Edit .env to set your target API key and Base URL\n\n# 2. Start the container\ndocker run -d \\\n  --name heimsense \\\n  -p 8080:8080 \\\n  -v $(pwd)/.env:/.env \\\n  ghcr.io/fajarhide/heimsense:latest\n\n# 3. Configure local Claude Code instance\nheimsense setup\n```\n\n---\n\n## Supported Providers\n\nHeimsense is compatible with endpoints adhering to the OpenAI API specification, including:\n\n* **Cloud Services:** OpenAI, DeepSeek, Groq, Together AI, Mistral, xAI (Grok), OpenRouter, Fireworks AI.\n* **Local Implementations:** Ollama, LM Studio, vLLM, LocalAI.\n\n---\n\n## Architecture Overview\n\nHeimsense operates as a translation proxy layer between the Claude Code client and the target LLM API.\n\n1. The Claude Code client sends queries in the **Anthropic format** (`/v1/messages`).\n2. Heimsense transforms the request payload into the **OpenAI format** (`/v1/chat/completions`).\n3. The query is forwarded to the designated LLM provider.\n4. The provider's response, including SSE streams and tool/function calls, is translated back to the Anthropic format for consumption by the client.\n\n---\n\n## Comparison: Why Heimsense\n\nIn contrast to similar tools built with Python or Node.js, Heimsense prioritizes simplicity and minimal footprint through its Go implementation:\n\n* **No package managers:** Bypasses `pip`, `npm`, or virtual environments in favor of a standalone binary.\n* **Minimal resource usage:** Typical RAM consumption is under 20MB.\n* **Integrated CLI:** Dedicated commands (`setup`, `sync`, `run`) streamline the configuration process for Claude Code.\n* **Reliability features:** Incorporates exponential backoff retries, graceful shutdown, structured logging, and health monitoring.\n\n---\n\n## Development \u0026 API Reference\n\nStandard development commands:\n\n```bash\nmake run        # Build binary and start server\nmake test       # Execute test suite\nmake build      # Compile executable to ./bin/\nmake lint       # Run code formatters and linters\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAPI Endpoints\u003c/strong\u003e\u003c/summary\u003e\n\n### `POST /v1/messages` \n\nThis endpoint handles requests formatted according to the Anthropic API specification:\n\n**Streaming Example:**\n```bash\ncurl -X POST http://localhost:8080/v1/messages \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer your-key\" \\\n  -d '{\n    \"model\": \"gpt-4o\",\n    \"max_tokens\": 1024,\n    \"stream\": true,\n    \"messages\": [{\"role\": \"user\", \"content\": \"Explain the concept of an API.\"}]\n  }'\n```\n\n*(Tool and function calling features are supported)*\n\n### `GET /health`\n```bash\ncurl http://localhost:8080/health\n# → {\"status\":\"ok\"}\n```\n\n\u003c/details\u003e\n\n\n## Star History\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#fajarhide/heimsense\u0026Date\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=fajarhide/heimsense\u0026type=Date\u0026theme=dark\" /\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=fajarhide/heimsense\u0026type=Date\" /\u003e\n      \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=fajarhide/heimsense\u0026type=Date\" width=\"600\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n*Heimsense: Inspired by Heimdall, the guardian of the Bifröst bridge.*  \n**License:** [MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffajarhide%2Fheimsense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffajarhide%2Fheimsense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffajarhide%2Fheimsense/lists"}