A standalone terminal AI agent in a single C file. Quiet, model-agnostic, skill-driven.

_{site  ·  releases  ·  changelog  ·  hako  ·  org}

    █       █     hakoCLAW v0.1.5
   ███     ███    provider: gemini
 ███████████████  model: gemini-2.5-flash
 ███░████████░██  trust: granted
 ███████████████
 ███████████████

Local first. Your text, your keys, your weights. No telemetry. No silent network. The cursor is a private place.

Single binary. One C file. Builds with gcc -lpthread. Curl on PATH for HTTP. Nothing else linked.

Bring your own deity. Anthropic, OpenAI, Gemini, Groq, Cerebras, Ollama, plus 7 more. Set a key, set a model, that's the wire.

_{—— I ——}

Overview

• 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.
• 13 providers, 3 wire formats. Anthropic native (SSE), OpenAI function-calling, Ollama local. Aliases route Gemini, Groq, Cerebras, DeepSeek, Mistral, Together, Fireworks, OpenRouter, xAI/Grok, custom over OpenAI-compat. koi slot reserved for hakoAI.
• Trust-gated tools. read_file, list_dir, write_file (with staging), run_shell (10s timeout). Untrusted dir = all tools refused. :trust once per project.
• Persistent sessions + skills. Per-cwd session id, 7-day resume, append-only JSONL history. Skills are markdown — flat or directory dispatchers (corp-style) — pulled on demand via the read_skill tool. Notes you keep on disk for the agent to find.
• Self-update. hakoc --update pulls the latest GitHub release, verifies sha256, atomically replaces the binary. No reinstall, no rebuild.
• Streaming + spinners. Anthropic SSE streams live tokens. 8 spinner styles × 12 thinking labels rotate per turn (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏).

_{—— II ——}

Build & Run

Build

gcc hakoCLAW.c -o hakoc -lpthread        # one-liner

make                                      # cross-OS Makefile
make UNIVERSAL=1                          # macOS arm64 + x86_64 fat binary
make asan                                 # ASan + UBSan build

Deps: libc + pthread + curl(1) on PATH. No third-party libraries linked.

Install

curl -fsSL https://mithraeums.github.io/install.sh | sh

Detects OS and arch, downloads the latest signed release, verifies the sha256 sidecar, drops hakoc into /usr/local/bin (or ~/.local/bin). No package manager. No daemon. No telemetry.

macOS universal2 · arm64 + x86_64

Linux x86_64 · arm64

FreeBSD x86_64

Windows x86_64 · MinGW

iSh linux-x86_64 binary

First turn

hakoc                    # interactive REPL
> :login anthropic       # OAuth — uses your Claude Pro / Max subscription
> what's in this directory?

# or — free tier, no subscription:
> :login github-models   # device flow, free for any GitHub account
> :model gpt-4o-mini

# or — paste an API key:
> :login gemini          # opens browser, paste free-tier key
> :model gemini-2.5-flash

Or one-shot:

hakoc -p "summarize README.md"

Self-update:

hakoc --update           # check + atomic-replace if newer

_{—— III ——}

Key Bindings & Commands

Normal Mode

Key	Action
← →	move cursor
↑ ↓	history prev / next
Home / End · ^A / ^E	line start / end
^U / ^K / ^W	kill to start / end / word
^R	reverse-incremental history search
^L	clear screen
Backspace · Delete	delete back / forward at cursor
^C	cancel current line
^D (empty)	EOF / exit

Bracketed paste enabled in raw mode — multi-line pastes batch-insert.

Commands (inside prompt):

: is the primary prefix (vim / hako style). / works as a legacy alias.

:help     :clear     :retry     :edit     :undo     :usage     :q
:providers          :models      :provider <name>      :model <id>
:login [<prov>]     :logout [<prov>]     :accounts
:history [local|global]
:skills [reload]    :skill install <url>     :skill uninstall <name>
:tools on|off       :toolgate on|off     :toolmode native|react     :trust [revoke]
:sessions           :resume <id>     :session [new]

TAB completes commands and provider names after :login / :provider / :logout.

_{—— IV ——}

Configuration

Auth · Trust · State

~/.hakoc/state              provider, model, settings (mode 0600, no secrets)
~/.hakoc/credentials        per-provider api_key / oauth tokens (obfuscated, 0600)
~/.hakoc/history            append-only JSONL chat log
~/.hakoc/skills/            markdown behaviors (flat or dir-dispatcher)
~/.hakoc/input_history      line editor history (last 500)
~/.hakocrc                  user config
<cwd>/.hakoc/state          per-project session id, turn count (no secrets)
<cwd>/.hakoc/trust          sentinel: tools allowed in this cwd

Three auth paths:

• 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.
• 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.
• Local — :login ollama / :login ollamacloud. Local: ensure ollama serve is running. Cloud: paste an Ollama key.

Run :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 [<provider>] wipes one. Mid-chat :provider X swaps secrets and flattens wire-format-specific message bodies so the conversation survives.

Resolution order: CLAW_API_KEY env → <PROVIDER>_API_KEY env → ~/.hakoc/credentials (per provider).

First run in any directory asks for trust. Untrusted = no tool access at all.

Connection Matrix

Provider	id (:provider <id>)	Auth	Cost	Wire format	Notes
Anthropic	anthropic · claude	OAuth	sub	native + SSE	Claude Pro/Max subscription; live-tested
Anthropic API	anthropic-api · claude-api	paste	$/tok	native + SSE	regular API key, separate from sub
GitHub Copilot	copilot · github-copilot	OAuth	sub	OpenAI-compat	Copilot Pro/Business; device flow
GitHub Models	github-models · ghmodels	OAuth	free	OpenAI-compat	rate-limited; any GH account
OpenRouter	openrouter	OAuth (PKCE)	$/tok	OpenAI-compat	auto-issues user-scoped key; :free tier
OpenRouter API	openrouter-api	paste	$/tok	OpenAI-compat	paste existing key
OpenAI	openai · gpt	paste	$/tok	function-calling
Gemini	gemini · google	paste	free/$	OpenAI-compat	generous free tier on AI Studio
Groq	groq	paste	free	OpenAI-compat	fastest hosting for Llama family
Cerebras	cerebras	paste	free	OpenAI-compat	ultra-fast inference
DeepSeek	deepseek	paste	$/tok	OpenAI-compat	DeepSeek-Chat / Reasoner
Mistral	mistral	paste	$/tok	OpenAI-compat	Mistral Large / Small / Codestral
Together	together	paste	$/tok	OpenAI-compat	aggregator
Fireworks	fireworks	paste	$/tok	OpenAI-compat	aggregator
xAI	xai · grok	paste	$/tok	OpenAI-compat	Grok API at api.x.ai
Ollama (local)	ollama · local	none	local	native	needs ollama serve running
Ollama Cloud	ollamacloud · ocloud	paste	$/tok	native	ollama.com hosted
custom	custom	paste	depends	OpenAI-compat	set ai_endpoint in .hakocrc

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 to v0.1.6.

Tool modes

Some 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:

:toolmode react        # model emits <tool name="X">{...}</tool> blocks in prose
:toolmode native       # back to native function-calling (default)

ReAct mode injects a tool schema in the system prompt and parses <tool>...</tool> blocks from the model's response. Each tool call is executed and the result is appended as <observation tool="X">...</observation> for the next turn. Works with any instruct-tuned model.

_{—— V ——}

Skills

~/.hakoc/skills/
├── style.md                  flat skill — whole file injected
└── corp/                     directory skill — SKILL.md is the dispatcher
    ├── SKILL.md
    └── .claude/agents/
        ├── CEO.md
        ├── DEV.md
        └── QA.md

Directory skills inject only SKILL.md plus a <files> manifest. The agent reads inner files on demand via read_skill(skill, path) — no trust gate (skills are user-installed), path-traversal blocked.

git clone https://github.com/mithraeums/skills ~/.hakoc/skills/_tmp
cp -r ~/.hakoc/skills/_tmp/corp ~/.hakoc/skills/
rm -rf ~/.hakoc/skills/_tmp
hakoc        # "loaded 1 skill(s)"

Browse the catalog: mithraeums/skills.

_{—— VI ——}

Change Log

v0.1.5 (Latest)

• 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).
• Discovery — :providers grouped catalog, :models live (Ollama) or curated suggestions (other providers), TAB completion.
• Workflow parity — :retry, :edit, :undo, up-arrow recall.
• ReAct tool fallback — :toolmode react for smaller / non-tool-tuned models (Mistral 7B, Phi-4, DeepSeek-R1 distills).
• Cost tracking — per-provider USD/M-token price table, session $ in status line, :usage reset.
• Rendering — tool category glyphs, fenced code blocks with bronze gutter, last-turn latency in status line.
• Per-provider cred store — ~/.hakoc/credentials (XOR + base64, 0600). :accounts, :logout.
• Mid-chat provider swap — :provider X flattens wire-format-specific bodies so conversation survives Anthropic↔OpenAI↔Ollama jumps.

v0.1.4

• --pipe mode for hako integration — JSONL I/O over stdin/stdout.
• Mithraeum palette by default — gold / paper / rust / dim chalk truecolor.

See CHANGELOG.md for full history.

_{—— VII ——}

Roadmap

• Termios line editor
• --update
• directory skills + read_skill
• universal2, Linux arm64, FreeBSD x86_64
• editor integration in hako (build-time make AI=0|1), pluggable local model backend.
• hakoAI/koi engine plugin, OAuth where providers add it

_{—— VIII ——}

Contributing

If you share the belief that simplicity empowers creativity, feel free to contribute.

Contribution is welcome in the form of:

• Forking this repo
• Submitting a Pull Request
• Bug reports and feature requests

Please ensure your code follows the existing style.

Thank you for your attention.

This project started out of curiosity and as a branch of hako, a C based modal text editor. If you hit any issues, feel free to open an issue on GitHub. Pull requests, suggestions, or even thoughtful discussions are welcome.

_{— SEE LICENSE —  ·  GPL-3.0}

_{— deus sol invictus mithras —}