{"id":50615762,"url":"https://github.com/mithraeums/hako-code","last_synced_at":"2026-06-06T08:03:28.704Z","repository":{"id":356986022,"uuid":"1231499119","full_name":"mithraeums/hako-code","owner":"mithraeums","description":"A local first agent. Written in C. Works with most providers. Uses local Hako models or BYO AI.","archived":false,"fork":false,"pushed_at":"2026-05-29T07:19:52.000Z","size":765,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T08:29:52.476Z","etag":null,"topics":["ai-agents","anthropic","chatgpt","claude","claude-code","claw","clawdbot","codex","hako","hakoclaw","llm","mithraeum","moltbot","openclaw","skills","tui"],"latest_commit_sha":null,"homepage":"https://mithraeums.github.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mithraeums.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2026-05-07T02:44:54.000Z","updated_at":"2026-05-29T07:53:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mithraeums/hako-code","commit_stats":null,"previous_names":["mithraeums/hakoclaw","mithraeums/hako-code"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/mithraeums/hako-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mithraeums%2Fhako-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mithraeums%2Fhako-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mithraeums%2Fhako-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mithraeums%2Fhako-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mithraeums","download_url":"https://codeload.github.com/mithraeums/hako-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mithraeums%2Fhako-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33973868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","anthropic","chatgpt","claude","claude-code","claw","clawdbot","codex","hako","hakoclaw","llm","mithraeum","moltbot","openclaw","skills","tui"],"created_at":"2026-06-06T08:03:27.964Z","updated_at":"2026-06-06T08:03:28.675Z","avatar_url":"https://github.com/mithraeums.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://mithraeums.github.io\"\u003e\n    \u003cimg src=\"https://mithraeums.github.io/assets/banner-hako-code-dark.svg\" alt=\"hako-code — a standalone agent for the inner chamber\" width=\"100%\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eA standalone terminal AI agent in a single C file. Quiet, model-agnostic, skill-driven.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/mithraeums/hako-code/releases\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-v0.1.8-b89656?style=flat-square\u0026labelColor=14130f\" alt=\"v0.1.8\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-GPL--3.0-c8c2b2?style=flat-square\u0026labelColor=14130f\" alt=\"GPL-3.0\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/C99-single%20file-c8c2b2?style=flat-square\u0026labelColor=14130f\" alt=\"C99 single file\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/providers-13-c8c2b2?style=flat-square\u0026labelColor=14130f\" alt=\"13 providers\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platforms-5-c8c2b2?style=flat-square\u0026labelColor=14130f\" alt=\"5 platforms\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\u003ca href=\"https://mithraeums.github.io\"\u003esite\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"https://github.com/mithraeums/hako-code/releases\"\u003ereleases\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"CHANGELOG.md\"\u003echangelog\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"https://github.com/mithraeums/hako\"\u003ehako (models)\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"https://github.com/mithraeums/hako-edit\"\u003ehako-edit\u003c/a\u003e \u0026nbsp;·\u0026nbsp; \u003ca href=\"https://github.com/mithraeums\"\u003eorg\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003c!-- HERO: screenrecord-hako.gif — animated agent demo. 11s @ 12fps, 960px wide, ~1.2MB. Auto-loops on GitHub. --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/mithraeums/mithraeums.github.io/blob/main/assets/readme-screenshots/hako-code/screenrecord-hako.gif?raw=true\" alt=\"hako agent live demo\" width=\"82%\"/\u003e\n\u003c/p\u003e\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003c!-- SCREENSHOT: hako-code/screenshot-splash.png — hako agent banner box at startup, koi auto-detected, mithraeum provider. --\u003e\n      \u003cimg src=\"https://github.com/mithraeums/mithraeums.github.io/blob/main/assets/readme-screenshots/hako-code/screenshot-splash.png?raw=true\" alt=\"hako banner with koi defaulted\" width=\"100%\"/\u003e\u003cbr/\u003e\n      \u003csub\u003eauto-defaults to a local \u003cb\u003ehako\u003c/b\u003e model via mithraeum\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003c!-- SCREENSHOT: hako-code/screenshot-models.png — `:models` output showing the catalog (mithraeum koi + cloud providers). --\u003e\n      \u003cimg src=\"https://github.com/mithraeums/mithraeums.github.io/blob/main/assets/readme-screenshots/hako-code/screenshot-models.png?raw=true\" alt=\":models output\" width=\"100%\"/\u003e\u003cbr/\u003e\n      \u003csub\u003e\u003ccode\u003e:models\u003c/code\u003e · local hako + 13 cloud providers\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003c!-- REUSED from hako-edit — Rei pane shows the agent embedded in the editor, talking to koi. Same binary, different host. --\u003e\n      \u003cimg src=\"https://github.com/mithraeums/mithraeums.github.io/blob/main/assets/readme-screenshots/hako-edit/screenshot-rei.png?raw=true\" alt=\"hako inside hake editor\" width=\"100%\"/\u003e\u003cbr/\u003e\n      \u003csub\u003ealso runs embedded inside \u003ca href=\"https://github.com/mithraeums/hako-edit\"\u003e\u003cb\u003ehake\u003c/b\u003e\u003c/a\u003e (the editor)\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003c!-- REUSED from hako-edit themes capture — same palette tokens drive both editor + agent. --\u003e\n      \u003cimg src=\"https://github.com/mithraeums/mithraeums.github.io/blob/main/assets/readme-screenshots/hako-edit/screenshot-themes.png?raw=true\" alt=\"theme palette\" width=\"100%\"/\u003e\u003cbr/\u003e\n      \u003csub\u003ethemes · mithraeum · claude · nord · mono\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr\u003e\n\n\u003c!-- KEEP: ASCII mockup of the in-terminal banner. Renders fine in monospace; do not replace with a screenshot. Mirrors the cleaned 13-row logo (no TABs, no mixed ASCII spaces) — keep this and `CL_LOGO_MEDIUM` in lockstep when either changes. --\u003e\n\n```\n╭───────────────────────────────────────────╮\n│        ⠀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀         │\n│        ⠀⠀⠀⢀⣠⣶⣾⣿⣿⣿⣦⡀⠀⠀⢀⣴⣿⣿⣿⣷⣶⣄⡀⠀⠀⠀         │\n│        ⣠⣴⣾⣿⣿⣿⣿⣿⣿⠿⠛⠉⢠⡄⠉⠛⠿⣿⣿⣿⣿⣿⣿⣷⣦⣄         │\n│        ⠀⠻⣿⣿⣿⡿⠟⠋⠁⠀⠀⠀⢸⡇⠀⠀⠀⠈⠙⠻⢿⣿⣿⣿⠟⠁         │\n│        ⠀⠀⠈⠋⠁⠀⠀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⠀⠀⠈⠙⠁⠀⠀         │\n│        ⠀⠀⣰⣷⣦⣄⡀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⢀⣠⣴⣾⣆⠀⠀         │\n│        ⢠⣾⣿⣿⣿⣿⣿⣷⣦⣄⠀⠀⢸⡇⠀⠀⣠⣴⣾⣿⣿⣿⣿⣿⣷⡄         │\n│        ⠙⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠖⠀⠀⠲⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠋         │\n│        ⠀⠀⠀⠉⠛⠿⣿⣿⣿⠟⢁⣴⡇⢸⣦⡈⠻⣿⣿⣿⠿⠛⠉⠀⠀⠀         │\n│        ⠀⠀⠀⢸⣷⣦⣄⡉⢁⣴⣿⣿⡇⢸⣿⣿⣦⡈⢉⣠⣴⣾⡇⠀⠀⠀         │\n│        ⠀⠀⠀⠈⠙⠻⢿⣿⣿⣿⣿⣿⡇⢸⣿⣿⣿⣿⣿⡿⠟⠋⠁⠀⠀⠀         │\n│        ⠀⠀⠀⠀⠀⠀⠀⠈⠙⠻⢿⣿⡇⢸⣿⡿⠟⠋⠁⠀⠀⠀⠀⠀⠀⠀         │\n│        ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠁⠈⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀         │\n│                                           │\n│ hako 0.1.8 · mithraeum · hako-sho         │\n│ trust on · session resumed                │\n│ :help :providers :models :login :theme    │\n╰───────────────────────────────────────────╯\n```\n\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"33%\" valign=\"top\"\u003e\u003cb\u003eLocal first.\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eAuto-defaults to any installed \u003ca href=\"https://github.com/mithraeums/hako\"\u003ehako\u003c/a\u003e model — \u003ccode\u003ehako-sho\u003c/code\u003e (3B) or \u003ccode\u003ehako-koi\u003c/code\u003e (7B), runs on your device, no key, no cloud. The agent detects it and just works.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"33%\" valign=\"top\"\u003e\u003cb\u003eSingle binary.\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eOne C file. Builds with \u003ccode\u003egcc -lpthread\u003c/code\u003e. Curl on PATH for HTTP. Nothing else linked.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"33%\" valign=\"top\"\u003e\u003cb\u003e13 cloud providers when you want them.\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eAnthropic OAuth (Claude Pro/Max sub), GitHub Copilot, GH Models (free), OpenRouter, plus 9 more over OpenAI-compat. Set a key or run a one-line \u003ccode\u003e:login\u003c/code\u003e — your call.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— I ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Overview\n\n- **Local models run on the native engine — no ollama, no server.** Plain `make`\n  is all the agent needs; it runs Qwen-class models by spawning the\n  [hako engine](https://github.com/mithraeums/hako) as a one-shot `hakm`\n  subprocess per turn (`hakm \u003cmodel.mlf2\u003e --chat-stdin`) over mmap'd MLF2 weights.\n  No in-process link, no compile flag, no daemon, no socket. Install the engine\n  CLI once with `make hakm` (→ `~/.hako/bin/hakm`). Drop a `.mlf2` in\n  `~/.hako/models/` and `hako` auto-defaults to the **mithraeum** provider on\n  first launch — no key, no `:login`, no config (preference: koi \u003e sho,\n  fine-tunes over stock-wraps). Force prose tool mode is on so\n  `\u003ctool name=\"...\"\u003e{...}\u003c/tool\u003e` calls parse on small models. Convert a GGUF\n  with the engine's `tools/gguf2mlf.py`, or `:pull \u003ctier\u003e` it from HuggingFace.\n  (ollama is also supported as a *separate* optional provider — `:login ollama` —\n  for non-hako models.)\n- **13 cloud providers when you want them.** Anthropic native (SSE + OAuth via Claude Pro/Max), OpenAI function-calling, GitHub Copilot, GitHub Models (free), OpenRouter (PKCE), and OpenAI-compat aliases for Gemini, Groq, Cerebras, DeepSeek, Mistral, Together, Fireworks, xAI/Grok, custom. `:login \u003cname\u003e` walks you through OAuth or hands you to the provider's console for an API key.\n- **Terminal-class line editor.** Termios raw mode, cursor keys, history (↑ ↓), `^R` reverse-search, Home/End, kill-word, kill-line, bracketed paste. Multi-row aware redraw, no flicker.\n- **Theme presets.** `:theme mithraeum|claude|nord|mono` swaps the full palette live (persisted in `~/.hakorc`). Truecolor where supported, 16-color fallback for error chip in tmux without `RGB` passthrough.\n- **HAKO.md project context.** Per-project `\u003ccwd\u003e/.hako/HAKO.md` is auto-loaded into the system prompt — the CLAUDE.md equivalent for hako-code. Binary-safe + size-capped (200KB).\n- **Trust-gated tools.** `read_file`, `list_dir`, `write_file` (with staging), `run_shell` (10s timeout). Untrusted dir = all tools refused. `:trust` once per project.\n- **Persistent sessions + skills.** Per-cwd session id, 7-day resume, append-only JSONL history. Skills are markdown — flat or directory dispatchers ([corp](https://github.com/mithraeums/skills/tree/main/corp)-style) — pulled on demand via the `read_skill` tool. Notes you keep on disk for the agent to find.\n- **Self-update.** `hako --update` pulls the latest GitHub release, verifies sha256, atomically replaces the binary. No reinstall, no rebuild.\n- **Streaming + spinners.** Anthropic SSE streams live tokens. 8 spinner styles × 12 thinking labels rotate per turn (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`).\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— II ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Build \u0026 Run\n\n### Build\n\n```sh\ngcc hako.c -o hako -lpthread        # one-liner\n\nmake                                      # cross-OS Makefile\nmake UNIVERSAL=1                          # macOS arm64 + x86_64 fat binary\nmake asan                                 # ASan + UBSan build\n```\n\n\u003e Deps: libc + pthread + `curl(1)` on PATH. No third-party libraries linked.\n\n### Install\n\n```sh\ncurl -fsSL https://mithraeums.github.io/install.sh | sh\n```\n\nDetects OS and arch, downloads the latest signed release, verifies the sha256 sidecar, drops `hako` into `/usr/local/bin` (or `~/.local/bin`). No package manager. No daemon. No telemetry.\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003emacOS\u003c/b\u003e\u003cbr/\u003e\u003csub\u003euniversal2 · arm64 + x86_64\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003eLinux\u003c/b\u003e\u003cbr/\u003e\u003csub\u003ex86_64 · arm64\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003eFreeBSD\u003c/b\u003e\u003cbr/\u003e\u003csub\u003ex86_64\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003eWindows\u003c/b\u003e\u003cbr/\u003e\u003csub\u003ex86_64 · MinGW\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cb\u003eiSh\u003c/b\u003e\u003cbr/\u003e\u003csub\u003elinux-x86_64 binary\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### First turn\n\n**Local, zero config (recommended)** — build with the engine, drop in a weight, launch:\n\n```sh\nmake                                                   # plain build — the agent\nmake hakm                                              # installs the engine CLI → ~/.hako/bin/hakm\n# convert a Qwen2.5-Coder GGUF once → ~/.hako/models/hako-sho.mlf2\n#   (python3 ../hako/tools/gguf2mlf.py model.gguf ~/.hako/models/hako-sho.mlf2)\nhako                                                   # auto-detects the .mlf2, runs it via the hakm subprocess (mithraeum)\n\u003e :trust                                                # grant tool access in this project\n\u003e list files in this directory\n\u003e :trust                                                # grant tool access in this project\n\u003e list files in this directory\n```\n\n**Or wire a cloud provider:**\n\n```sh\nhako\n\u003e :login anthropic       # OAuth — uses your Claude Pro / Max subscription\n\u003e :login github-models   # free for any GitHub account\n\u003e :login gemini          # paste a free-tier API key\n\u003e :model gemini-2.5-flash\n```\n\nOr one-shot:\n\n```sh\nhako -p \"summarize README.md\"\n```\n\nSelf-update:\n\n```sh\nhako --update           # check + atomic-replace if newer\n```\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— III ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Key Bindings \u0026 Commands\n\n### Normal Mode\n\n| Key | Action |\n|---|---|\n| ← → | move cursor |\n| ↑ ↓ | history prev / next |\n| Home / End · `^A` / `^E` | line start / end |\n| `^U` / `^K` / `^W` | kill to start / end / word |\n| `^R` | reverse-incremental history search |\n| `^L` | clear screen |\n| Backspace · Delete | delete back / forward at cursor |\n| `^C` | cancel current line |\n| `^D` (empty) | EOF / exit |\n\n*Bracketed paste enabled in raw mode — multi-line pastes batch-insert.*\n\n### Commands (inside prompt):\n\n`:` is the primary prefix (vim / hako style). `/` works as a legacy alias.\n\n```\n:help     :clear     :retry     :edit     :undo     :usage     :q\n:providers          :models      :provider \u003cname\u003e      :model \u003cid\u003e\n:login [\u003cprov\u003e]     :logout [\u003cprov\u003e]     :accounts\n:history [local|global]\n:skills [reload]    :skill install \u003curl\u003e     :skill uninstall \u003cname\u003e\n:tools on|off       :toolgate on|off     :toolmode native|react     :trust [revoke]\n:sessions           :resume \u003cid\u003e     :session [new]\n```\n\n**TAB** completes commands and provider names after `:login` / `:provider` / `:logout`.\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— IV ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Configuration\n\n### Auth · Trust · State\n\n```\n~/.hako/state                              provider, model, settings (mode 0600, no secrets)\n~/.hako/credentials                        per-provider api_key / oauth tokens (obfuscated, 0600)\n~/.hako/skills/                            markdown behaviors (flat or dir-dispatcher)\n~/.hako/input_history                      line editor history (last 500)\n~/.hako/projects/\u003cencoded-cwd\u003e/state       per-project session id, turn count\n~/.hako/projects/\u003cencoded-cwd\u003e/trust       sentinel: tools allowed in this cwd\n~/.hako/projects/\u003cencoded-cwd\u003e/sessions/   append-only JSONL session history\n~/.hakorc                                  user config\n\u003ccwd\u003e/.hako/HAKO.md                        per-project context (auto-loaded into system prompt)\n```\n\n**Three auth paths:**\n\n- **OAuth (subscription / account-bound)** — `:login anthropic` (Claude Pro/Max), `:login copilot` (GitHub Copilot Pro/Business), `:login github-models` (free for any GitHub user), `:login openrouter` (PKCE, auto-issue an OR API key). Inference bills against your subscription where applicable; no per-token API key needed.\n- **API-key paste** — `:login openai`, `:login gemini`, `:login groq`, `:login cerebras`, `:login deepseek`, `:login mistral`, `:login together`, `:login fireworks`, `:login xai`, `:login anthropic-api`, `:login openrouter-api`, `:login custom`. Opens provider console in your browser, prompts with input hidden, persists into the cred store.\n- **Local** — `:login ollama` / `:login ollamacloud`. Local: ensure `ollama serve` is running. Cloud: paste an Ollama key.\n\nRun `:providers` for the full grouped list with `◎` (active) and `*` (saved login) markers. `:models` lists installed local models on Ollama or curated suggestions per provider. `:accounts` lists saved logins; `:logout [\u003cprovider\u003e]` wipes one. Mid-chat `:provider X` swaps secrets and flattens wire-format-specific message bodies so the conversation survives.\n\nResolution order: `HAKO_API_KEY` env → `\u003cPROVIDER\u003e_API_KEY` env → `~/.hako/credentials` (per provider). Legacy `CLAW_*` / `HAKOC_*` env names are read as fallback with a one-shot deprecation warning.\n\nFirst run in any directory asks for trust. Untrusted = no tool access at all.\n\n### Connection Matrix\n\n| Provider          | id (`:provider \u003cid\u003e`)            | Auth          | Cost     | Wire format       | Notes                                        |\n|---                |---                               |---            |---       |---                |---                                           |\n| Anthropic         | `anthropic` · `claude`           | OAuth         | sub      | native + SSE      | Claude Pro/Max subscription; live-tested     |\n| Anthropic API     | `anthropic-api` · `claude-api`   | paste         | $/tok    | native + SSE      | regular API key, separate from sub           |\n| GitHub Copilot    | `copilot` · `github-copilot`    | OAuth         | sub      | OpenAI-compat     | Copilot Pro/Business; device flow            |\n| GitHub Models     | `github-models` · `ghmodels`    | OAuth         | free     | OpenAI-compat     | rate-limited; any GH account                 |\n| OpenRouter        | `openrouter`                     | OAuth (PKCE)  | $/tok    | OpenAI-compat     | auto-issues user-scoped key; `:free` tier    |\n| OpenRouter API    | `openrouter-api`                 | paste         | $/tok    | OpenAI-compat     | paste existing key                           |\n| OpenAI            | `openai` · `gpt`                 | paste         | $/tok    | function-calling  |                                              |\n| Gemini            | `gemini` · `google`              | paste         | free/$   | OpenAI-compat     | generous free tier on AI Studio              |\n| Groq              | `groq`                           | paste         | free     | OpenAI-compat     | fastest hosting for Llama family             |\n| Cerebras          | `cerebras`                       | paste         | free     | OpenAI-compat     | ultra-fast inference                         |\n| DeepSeek          | `deepseek`                       | paste         | $/tok    |  OpenAI-compat    | DeepSeek-Chat / Reasoner                     |\n| Mistral           | `mistral`                        | paste         | $/tok    | OpenAI-compat     | Mistral Large / Small / Codestral            |\n| Together          | `together`                       | paste         | $/tok    | OpenAI-compat     | aggregator                                   |\n| Fireworks         | `fireworks`                      | paste         | $/tok    | OpenAI-compat     | aggregator                                   |\n| xAI               | `xai` · `grok`                   | paste         | $/tok    | OpenAI-compat     | Grok API at api.x.ai                         |\n| Ollama (local)    | `ollama` · `local`               | none          | local    | native            | needs `ollama serve` running                 |\n| Ollama Cloud      | `ollamacloud` · `ocloud`         | paste         | $/tok    | native            | ollama.com hosted                            |\n| custom            | `custom`                         | paste         | depends  | OpenAI-compat     | set `ai_endpoint` in `.hakorc`              |\n\n*Three wire formats (native Anthropic, native Ollama, OpenAI-compat).  Quickest paths: (a) **Claude Pro/Max** → `:login anthropic`. (b) **Copilot Pro** → `:login copilot`. (c) **Free, no card** → `:login github-models`, `:login gemini`, `:login groq`, or `:login ollama`. (d) **Pay-as-you-go** → any paste row. ChatGPT Plus piggyback deferred — no public OAuth surface yet.*\n\n### Tool modes\n\nSome smaller / non-tool-tuned models (Mistral 7B, Phi-4, DeepSeek-R1 distills, smaller Gemma / Llama variants) don't reliably emit OpenAI/Anthropic function-calling JSON. Toggle ReAct mode:\n\n```sh\n:toolmode react        # model emits \u003ctool name=\"X\"\u003e{...}\u003c/tool\u003e blocks in prose\n:toolmode native       # back to native function-calling (default)\n```\n\nReAct mode injects a tool schema in the system prompt and parses `\u003ctool\u003e...\u003c/tool\u003e` blocks from the model's response. Each tool call is executed and the result is appended as `\u003cobservation tool=\"X\"\u003e...\u003c/observation\u003e` for the next turn. Works with any instruct-tuned model.\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— V ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Skills\n\n```\n~/.hako/skills/\n├── style.md                  flat skill — whole file injected\n└── corp/                     directory skill — SKILL.md is the dispatcher\n    ├── SKILL.md\n    └── agents/\n        ├── CEO.md\n        ├── DEV.md\n        └── QA.md\n```\n\nDirectory skills inject only `SKILL.md` plus a `\u003cfiles\u003e` manifest. The agent reads inner files on demand via `read_skill(skill, path)` — no trust gate (skills are user-installed), path-traversal blocked.\n\n```sh\ngit clone https://github.com/mithraeums/skills ~/.hako/skills/_tmp\ncp -r ~/.hako/skills/_tmp/corp ~/.hako/skills/\nrm -rf ~/.hako/skills/_tmp\nhako        # \"loaded 1 skill(s)\"\n```\n\nBrowse the catalog: [mithraeums/skills](https://github.com/mithraeums/skills).\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— VI ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Change Log\n\n### v0.1.8 (Latest)\u003cbr\u003e\n- **Local models now run via the `hakm` SUBPROCESS — in-process engine link REVERSED.** `hkMithraeumChat` spawns `hakm \u003cmodel.mlf2\u003e --chat-stdin` one-shot per turn and reads the reply off stdout. No ollama, no server, no daemon. **Why the reversal:** v0.1.7's in-process link was gated behind `-DHAKO_HAVE_HAKM`, so a plain `make`/`make install` shipped an engine-less `hako` → MITHRAEUM fell through to the ollama curl path → \"empty response\" (recurred twice). Subprocess = plain `make` always ships the path, can't be compiled out. `make hakm` now builds+installs the standalone engine CLI to `~/.hako/bin/hakm`; the agent finds it via `hkFindHakm()` (`~/.hako/bin` → PATH).\n- **Provision** — relocate misplaced weights into `~/.hako/models/`, `:pull \u003ctier\u003e` from HuggingFace (`mithraeum` acct), prompt-then-pull on a `:model` switch to an uninstalled tier.\n\n### v0.1.7\u003cbr\u003e\n- **`mithraeum` provider ran the native hako engine IN-PROCESS.** Linked `libhakm.a` and called `hkMithraeumChat` → `hakm_chat` in this process; build was `make hakm` (`-DHAKO_HAVE_HAKM`). *(Reversed in v0.1.8 — the gated link kept shipping engine-less binaries.)*\n- **Model resolution off the filesystem** — `~/.hako/models/\u003cid\u003e.mlf2`. `clDetectKoiDefault` + `:models` scan `~/.hako/models/*.mlf2` (no more `ollama list` / `/api/tags`). koi \u003e koi-mini \u003e sho; `-v*` over `-stock`.\n- **Graceful weight fallback** — missing configured weight → `hkMithraeumFirstAvailable` picks the first installed `.mlf2` (prefers sho), warns, self-heals per-project state. Fixes the stale `ai_model=hako-koi-*` \"no such file\" crash.\n- **`AI_PROVIDER_OLLAMA` kept as a separate optional provider** — only the hako-models path is ollama-free.\n- Engine: int8 dot path → ~2.25 tok/s on the 3B (Intel i3). See `mithraeums/hako`.\n\n### v0.1.6\u003cbr\u003e\n- **Anthropic OAuth tool calls work.** System-as-array, CC fingerprint headers, prose-mode tool calls (Claude Code XML parser), JSON-unescape on `write_file` content. Verified live against Claude Pro/Max.\n- **Storage rewrite — CC-style.** Per-project state at `~/.hako/projects/\u003cencoded-cwd\u003e/{trust,state,sessions/\u003csid\u003e.jsonl}`. `\u003ccwd\u003e/.hako/` only holds `HAKO.md` (project context, system-prompt-loaded). Old per-project files trigger startup warn.\n- **Theme system** — `:theme mithraeum|claude|nord|mono` swap + persist.\n- **Visual overhaul** — sigils (`›` user, `◆` AI, `!` err, `·` sys), box banner, first-run wizard, ghost-text autocomplete for slash/colon cmds.\n- **Tool resolution hardened** — 20+ tool-name aliases case-insensitive (`bash`, `create_file`, `str_replace_based_edit_tool`, etc), param-name aliases (`command`→cmd, `file_path`→path, `file_text`→content) so CC-trained Claude works first try.\n- **`run_shell` rewrite** — tmp-script execution + JSON-unescape. Heredocs and embedded quotes now work.\n- **OPENAI + OLLAMA wires now carry `system_prompt`** — was silently dropped; BASE_PROMPT / skills / HAKO.md now reach Copilot / GH Models / OpenRouter / Gemini / Ollama / koi.\n- **Pre-tool prose suppression** — matches Claude Code chip-first ordering; no more \"Done!\" before the tool runs.\n- **Cached env probe** in system prompt — model knows `python3` vs `python` etc on first try.\n- **Ollama perf knobs** — `keep_alive: 30m` + `num_predict` cap. Big win on local koi turns.\n- **Error chip** — bold 16-color bright red + `✗` glyph (was rendering as invisible reverse-video bar in tmux).\n- **Banner box auto-sizes** correctly (was undercounting multibyte `·`). Rows truncate with `…`.\n\n### v0.1.5\u003cbr\u003e\n- **4 OAuth providers** — `:login anthropic` (Claude Pro/Max), `:login copilot` (Copilot Pro), `:login github-models` (free for any GH user), `:login openrouter` (PKCE auto-issue).\n- **Discovery** — `:providers` grouped catalog, `:models` live (Ollama) or curated suggestions (other providers), TAB completion.\n- **Workflow parity** — `:retry`, `:edit`, `:undo`, up-arrow recall.\n- **ReAct tool fallback** — `:toolmode react` for smaller / non-tool-tuned models (Mistral 7B, Phi-4, DeepSeek-R1 distills).\n- **Cost tracking** — per-provider USD/M-token price table, session `$` in status line, `:usage reset`.\n- **Rendering** — tool category glyphs, fenced code blocks with bronze gutter, last-turn latency in status line.\n- **Per-provider cred store** — `~/.hako/credentials` (XOR + base64, 0600). `:accounts`, `:logout`.\n- **Mid-chat provider swap** — `:provider X` flattens wire-format-specific bodies so conversation survives Anthropic↔OpenAI↔Ollama jumps.\n\n### v0.1.4\u003cbr\u003e\n- **`--pipe` mode** for hako integration — JSONL I/O over stdin/stdout.\n- **Mithraeum palette by default** — gold / paper / rust / dim chalk truecolor.\n\nSee [CHANGELOG.md](CHANGELOG.md) for full history.\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— VII ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Roadmap\n\n- [x] Termios line editor\n- [x] `--update`\n- [x] directory skills + `read_skill`\n- [x] universal2, Linux arm64, FreeBSD x86_64\n- [x] 4 OAuth providers (Anthropic, Copilot, GH Models, OpenRouter)\n- [x] Anthropic OAuth tool calls (CC-fingerprint prose mode)\n- [x] local hako auto-default (`hako-sho` 3B / `hako-koi` 7B) via the hakm subprocess\n- [x] [hako](https://github.com/mithraeums/hako) native engine wired as a **`hakm` subprocess** (`--chat-stdin`, one-shot per turn) — no ollama, no in-process link\n- [ ] MCP client mode with Dynamic Client Registration\n- [ ] Inline SHA-256 to drop openssl runtime dep\n- [ ] Vim-style error codes + Buddy BLE companion approval gateway — v0.2\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e—— VIII ——\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n\n## Contributing\nIf you share the belief that simplicity empowers creativity, feel free to contribute.\n\n### Contribution is welcome in the form of:\n- Forking this repo\n- Submitting a Pull Request\n- Bug reports and feature requests\n\nPlease ensure your code follows the existing style.\n\n### Thank you for your attention.\nThis project started out of curiosity and as a branch of [hako-edit](https://github.com/mithraeums/hako-edit), a C-based modal text editor. If you hit any issues, feel free to open an issue on GitHub.\nPull requests, suggestions, or even thoughtful discussions are welcome.\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003ca href=\"LICENSE\"\u003e— SEE LICENSE —\u003c/a\u003e \u0026nbsp;·\u0026nbsp; GPL-3.0\u003c/sub\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cem\u003e— deus sol invictus mithras —\u003c/em\u003e\u003c/sub\u003e\u003c/p\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmithraeums%2Fhako-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmithraeums%2Fhako-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmithraeums%2Fhako-code/lists"}