HiraxCode

An AI coding agent that lives in your terminal, built for vibe coding. Multi-provider, local models & GGUF, with settings right inside the TUI.

Built with TypeScript + Bun + Ink (React for the terminal).

██╗  ██╗██╗██████╗  █████╗ ██╗  ██╗ ██████╗ ██████╗ ██████╗ ███████╗
██║  ██║██║██╔══██╗██╔══██╗╚██╗██╔╝██╔════╝██╔═══██╗██╔══██╗██╔════╝
███████║██║██████╔╝███████║ ╚███╔╝ ██║     ██║   ██║██║  ██║█████╗
██╔══██║██║██╔══██╗██╔══██║ ██╔██╗ ██║     ██║   ██║██║  ██║██╔══╝
██║  ██║██║██║  ██║██║  ██║██╔╝ ██╗╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

Features

• 18 providers — OpenRouter, OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Mistral, xAI, Together, Fireworks, Cerebras, River AI, FreeLLMAPI, Ollama, LM Studio, llama.cpp, local GGUF, and Custom (OpenAI-compatible).
• Multiple API keys + auto-rotation — store several keys per provider (comma-separated). When one is rejected (401/402/403) or hits its rate limit (429), HiraxCode automatically rotates to the next key mid-conversation.
• Local GGUF, zero setup — just point at a .gguf file. If llama-server is missing, HiraxCode downloads the official llama.cpp binary into ~/.cache/hiraxcode/bin (Windows/macOS/Linux, x64 & arm64), then spawns it and waits until it is ready.
• Image input (screenshots) — attach a clipboard screenshot with /paste, Alt+V, or Ctrl+V, then send it to a vision model (GPT-4.1/4o, Claude, Gemini, LLaVA, Qwen2-VL, …). If the model can't read images, HiraxCode tells you and suggests the right ones (no cryptic errors).
• Local vision — GGUF models can accept images through a multimodal projector (--mmproj); set the mmproj (vision) field in /settings.
• Cross-platform — runs on Windows, macOS, and Linux. run_bash uses PowerShell on Windows and bash/zsh on macOS/Linux.
• In-TUI settings (/settings) — provider, API key, model, base URL, reasoning, temperature, max tokens, auto-approve, working dir, accent colour. Auto-saved.

Temperature

Temperature controls how random the model's output is: 0 = deterministic and focused, higher = more varied and creative. Past ~1.0 most models stop producing coherent text (you get word salad), so HiraxCode clamps it to 0.00–1.00 — the range that is safe across OpenAI, Anthropic and Gemini. The default is 0.20 (good for coding). Change it with /temp 0.3 or in /settings → Temperature, which also shows a label (precise / focused / balanced / creative).

• Model picker (/model) — fetch models straight from the provider, filter, or type a custom one.
• Clean TUI — a two-tone gradient wordmark, an indented transcript (accent bar for the user, plain assistant text, per-tool icons for tool calls), a framed session header with token counters, a bordered composer with the active agent · model · provider underneath, rounded overlay panels, and markdown rendering (headings, lists, quotes, code blocks).
• Mouse-wheel scrollback — scroll the transcript with the wheel; ↑/↓ also work line by line.
• Command palette — type / for an interactive list: ↑/↓ move, Tab completes, Enter runs. Long lists scroll.
• Message queue — send another message while the agent is working; it is queued and sent automatically when the turn finishes (with an N queued indicator).
• Accent themes (/theme, default #fab283) plus compact mode (/compact) for small screens.
• Agent loop — thinking → tool call → approval → execution → repeat.
• 8 tools — read_file, list_dir, glob, edit_file, write_file, run_bash, http_request, port_scan.
• Pentest & Security modes — dedicated security-testing agents: recon (port scan + HTTP probing), enumeration, and read-only code review. See Security & Pentest.
• Approval system — dangerous actions ask for y/n confirmation.
• Multi-session — session sidebar, history persisted to disk.
• Single binary — bun run build.

Quick Start

npm install          # or: bun install

cp .env.example .env # optional — you can also set everything from /settings

bun run dev          # run it

On first launch, open /settings to pick a provider and paste an API key. That's it — start chatting.

Build a binary:

bun run build        # -> dist/hiraxcode (current platform)

# Cross-compile for other platforms (from any OS):
bun run build:win    # -> dist/hiraxcode-win-x64.exe
bun run build:mac    # -> dist/hiraxcode-macos-arm64
bun run build:linux  # -> dist/hiraxcode-linux-x64
bun run build:all    # all of the above

The binary is self-contained (the Bun runtime is embedded) — just copy it to the target machine, no Bun/Node install required.

Providers

Every provider is selectable from /settings → Provider. Those needing an API key are under Cloud; the rest are Local (FreeLLMAPI is local but still wants its unified key).

| Provider | Env var | Default base URL | |---|---|---| | OpenRouter | OPENROUTER_API_KEY | https://openrouter.ai/api/v1 | | OpenAI | OPENAI_API_KEY | https://api.openai.com/v1 | | Anthropic | ANTHROPIC_API_KEY | https://api.anthropic.com | | Google Gemini | GEMINI_API_KEY | https://generativelanguage.googleapis.com | | Groq | GROQ_API_KEY | https://api.groq.com/openai/v1 | | DeepSeek | DEEPSEEK_API_KEY | https://api.deepseek.com/v1 | | Mistral | MISTRAL_API_KEY | https://api.mistral.ai/v1 | | xAI (Grok) | XAI_API_KEY | https://api.x.ai/v1 | | Together | TOGETHER_API_KEY | https://api.together.xyz/v1 | | Fireworks | FIREWORKS_API_KEY | https://api.fireworks.ai/inference/v1 | | Cerebras | CEREBRAS_API_KEY | https://api.cerebras.ai/v1 | | FreeLLMAPI (local router) | FREELLMAPI_API_KEY | http://localhost:3001/v1 | | River AI | RIVER_API_KEY | https://api.river.ai/v1 | | Ollama (local) | — | http://localhost:11434/v1 | | LM Studio (local) | — | http://localhost:1234/v1 | | llama.cpp server (local) | — | http://localhost:8080/v1 | | GGUF file (local) | — | auto-spawns llama-server | | Custom | — | your own |

All three wire protocols are implemented: OpenAI-compatible, Anthropic Messages (/v1/messages + tool-use blocks), and Gemini (streamGenerateContent + function calling).

Running a local GGUF

1. Nothing to install. If llama-server isn't on your PATH, HiraxCode downloads an official llama.cpp build into ~/.cache/hiraxcode/bin/llama-server/ (Windows/macOS/Linux, x64 & arm64). If you already have one, it uses the one on PATH.
2. In the app: /settings → Provider → GGUF file (local, auto-spawn).
3. Set GGUF file to the model path, e.g. /models/qwen2.5-coder-7b-instruct-q4_k_m.gguf.
4. (Optional, for vision models) set mmproj (vision) to the model's .mmproj companion file.
5. Send a message. HiraxCode spawns llama-server (with --jinja so tool-calling works), picks a free port, and shuts it down when you exit.

If you already run your own server (llama-server, Ollama, LM Studio), just pick the matching local provider — no spawning needed.

FreeLLMAPI (one endpoint, many free providers)

FreeLLMAPI runs a local router on port 3001 that stacks ~34 free provider tiers behind a single OpenAI-compatible /v1 endpoint, with its own failover and key rotation.

1. Start it (desktop installer from its Releases page, or docker compose up). Open http://localhost:3001, add your upstream provider keys, and copy the unified freellmapi-… key.
2. In HiraxCode: /settings → Provider → FreeLLMAPI (local router), then set API key(s) to that unified key.
3. Pick a model: auto (router picks), auto:fast, auto:smart, or any model id it lists (run /model to refresh the list from /v1/models).

HiraxCode's own multi-key rotation stacks with it: put several unified keys (comma-separated) and they rotate on 401/402/403/429 too.

Sending images / screenshots

1. Copy a screenshot (Windows: Win+Shift+S; macOS: Cmd+Ctrl+Shift+4; Linux: use xclip/wl-paste).
2. In HiraxCode press Alt+V (or Ctrl+V when your terminal passes it through) or run /paste. A ▣ 1 image attached indicator appears.
3. Send the message. HiraxCode converts the image to the right format per provider:
   • OpenAI-compatible → image_url data-URI
   • Anthropic → base64 image block
   • Gemini → inlineData
4. /drop to cancel attachments.

You can also attach an image from a file:

• /paste <path> or /file <path> — e.g. /file C:\shots\bug.png.
• Copy a file in your file manager and press Alt+V — images are attached; other files have their path inserted into the prompt.
• Drag a file onto the terminal (which types its path) and press Enter — any image path in your message is attached automatically.

The model must be vision-capable. If it isn't, HiraxCode refuses to send and suggests models (e.g. /model gpt-4.1, /model llava). For local GGUF, set mmproj first to enable vision.

Usage

| Key | Action | |---|---| | Enter | Send message (queued while the agent is running) | | Tab | Open/focus the session sidebar | | Ctrl+V / Alt+V | Attach an image (or file) from the clipboard | | Ctrl+B | Toggle sidebar | | / | Open the command palette (↑/↓ to move, Tab to complete) | | Mouse wheel | Scroll the transcript | | ↑ / ↓ | Scroll the transcript line by line (or navigate menu/sidebar when active) | | Ctrl+P / Ctrl+N | Previous / next input history | | ← / → | Change a value in Settings | | y / n | Approve / deny a tool call | | Esc | Close overlay / go back | | Ctrl+C | Quit (from any screen) |

Slash commands

| Command | Action | |---|---| | /settings | Open settings (provider, key, model, …) | | /provider | Switch provider | | /model | Pick / type a model | | /agent [id] | Switch agent (build / plan / pentest / security / custom) | | /pentest | Jump straight to the Pentest agent | | /paste [path] | Attach a clipboard image, or a file by path | | /file <path> | Attach an image file | | /drop | Clear image attachments | | /new | New session | | /clear | Clear the conversation | | /sessions | Toggle the session sidebar | | /cd <path> | Change the working directory | | /reasoning | Toggle thinking | | /temp <0-1> | Set the temperature (creativity) | | /compact | Toggle compact mode (denser transcript) | | /yolo | Toggle auto-approve for all tools (no confirmation prompts) | | /theme | Cycle the accent colour | | /help | Help | | /exit | Quit |

Tools

| Tool | Action | Approval? | |---|---|---| | read_file | Read a file (supports offset/limit) | no | | list_dir | List a folder's contents | no | | glob | Find files by pattern | no | | edit_file | Replace an exact span of text | yes | | write_file | Create / overwrite a file | yes | | run_bash | Run a shell command (PowerShell on Windows, bash/zsh on macOS/Linux) | yes | | http_request | Send an HTTP/HTTPS request and inspect status, headers, body (web probing) | no | | port_scan | TCP-connect scan a host for open ports (recon) | yes |

Security & Pentest

HiraxCode ships two security-focused agents, selected via /agent, /pentest, or the /agent picker:

• Pentest (pentest) — for authorised engagements. Workflow: scope → recon (port_scan, http_request, run_bash) → enumeration → common-vulnerability testing (auth, injection, misconfiguration, exposed files) → exploit PoC → findings report (severity, request evidence, impact, remediation).
• Security (security) — a read-only code review: leaked secrets, injection, authz issues, insecure deserialization, path traversal, SSRF, XSS, and dependency risk. run_bash is still allowed for read-only audits (e.g. npm audit), but there are no write/edit tools.

Both agents answer directly — they assume an authorised engagement and won't bury you in caveats. Point them at targets you own or are permitted to test: port_scan and run_bash require approval (unless you turn on /yolo), http_request is read-only and runs immediately.

Example:

/pentest
Scan 10.0.0.5 for open ports, then probe the web server on whatever ports you find

Configuration

Two layers:

1. .env — default keys & environment (see .env.example).
2. ~/.config/hiraxcode/config.json — written automatically whenever you change anything via /settings. Takes precedence over .env.

Main .env variables:

| Variable | Default | Description | |---|---|---| | HIRAX_PROVIDER | openrouter | Active provider | | MODEL | per-provider | Default model | | <PROVIDER>_API_KEY | — | Per-provider API key (comma-separate several to rotate) | | BASE_URL | per-provider | Override the base URL | | GGUF_PATH | — | Path to a .gguf file | | MMPROJ_PATH | — | Path to a .mmproj file (vision for GGUF) | | LLAMA_SERVER_BIN | llama-server | llama.cpp binary | | TEMPERATURE | 0.2 | 0–2 | | MAX_TOKENS | 0 | 0 = auto | | ENABLE_REASONING | true | Thinking stream | | REASONING_EFFORT | medium | low/medium/high | | AUTO_APPROVE_SAFE_TOOLS | true | Run read-only tools without confirmation | | AUTO_APPROVE_ALL | false | Skip confirmation for every tool — writes, shell, scans | | WORKING_DIR | cwd | Agent working root | | SHOW_SIDEBAR | false | Show the sidebar on start | | HIRAX_COMPACT | false | Compact mode (denser transcript) | | HIRAX_MINIMAL | false | Hide thinking blocks & inter-message spacing | | ACCENT | #fab283 | UI accent colour (also gold, cyan, violet, emerald, …) | | DEBUG | false | Log to stderr |

Architecture

src/
├── index.tsx                  # entry point, llama-server cleanup
├── core/
│   ├── providers.ts           # 18-provider registry + metadata
│   ├── settings.ts            # load/save settings (env + config.json)
│   ├── vision.ts              # detect image-capable models
│   ├── detect.ts              # detect local runtimes (ollama/lmstudio/llama.cpp)
│   └── types.ts
├── providers/
│   ├── types.ts               # Provider + StreamEvent interfaces
│   ├── openai.ts              # OpenAI-compatible (most + local)
│   ├── anthropic.ts           # Anthropic Messages + tool use
│   ├── gemini.ts              # Gemini streamGenerateContent
│   ├── llama.ts               # spawn/health-check llama-server (GGUF)
│   ├── ollama.ts, lmstudio.ts # local runtime spawn helpers
│   ├── models.ts              # list models per provider
│   └── index.ts               # createProvider() factory
├── agent/
│   ├── prompt.ts, tools.ts, tool-registry.ts, tool-schema.ts, loop.ts
├── store/sessions.ts
├── ui/
│   ├── App.tsx                # state, screen routing, slash commands, keys
│   ├── theme.ts               # design system (hex palette)
│   ├── lib/
│   │   ├── text.ts            # width/truncate/wrap/wrapCode helpers
│   │   └── markdown.tsx       # inline markdown parse + render
│   └── components/            # Banner, Sidebar, MessageList, InputBox,
│                              # Header, Home, StatusBar, CommandMenu,
│                              # ListPicker, TextField, TextInput,
│                              # SettingsScreen, HelpScreen, CustomProviderForm
└── utils/                     # logger, helpers, color, binaries (auto-download),
                               # clipboard (cross-platform image/file reading)

Agent flow: user → streamed answer/thinking → tool call → approval → execution → result back to the model → repeat → final answer.

Testing

bun test           # test suite
bun run typecheck  # typecheck (0 errors)

Coverage includes: tools (including http_request & port_scan), the agent loop, built-in agents (build/plan/pentest/security), OpenAI/Anthropic/Gemini wire formats (against a mock SSE server), image sending for every wire format, vision-model detection, Gemini tool-schema sanitization, approvals, provider errors surfaced in the chat, settings persistence, and UI rendering. No API key required.

Troubleshooting

• Raw mode is not supported on the current process.stdin — Ink needs an interactive terminal. Run hiraxcode directly in a terminal (not through a pipe/CI/nohup). If you really must force it, set HIRAX_FORCE_TTY=1.
• Provider returns 400 INVALID_ARGUMENT (Gemini) about additionalProperties / type — already fixed: tool schemas are normalized to Gemini's functionDeclarations format. Update to the latest version.
• No response at all — providers return errors that now show up in the chat as ⚠️ API .... Read the message; it's usually a wrong/empty API key or a missing model.
• Cannot find package 'ink' / missing modules — in some sandboxes bun install fails to extract files. Use npm install, then still run via bun run dev.
• Provider says "no API key" — open /settings, pick the provider, paste the API key.
• API 500: tools param requires --jinja flag (GGUF) — handled automatically: HiraxCode runs llama-server with --jinja. If you set llama-server args yourself, don't add --no-jinja (or add --jinja). Update to the latest version.
• llama-server not found — HiraxCode downloads llama.cpp automatically; if that fails (e.g. no internet), install it manually and set llama-server in /settings to the binary path.
• Model can't read images — use a vision model (GPT-4.1/4o, Claude, Gemini, LLaVA, Qwen2-VL). For local GGUF, set mmproj in /settings.
• /paste says "no image in clipboard" — make sure you copied a screenshot, not text. On Linux you need xclip (X11) or wl-paste (Wayland).
• Ctrl+V does nothing — some terminals (e.g. VS Code) capture Ctrl+V for their own paste. Use Alt+V or /paste instead.
• Image not sent — if the model is text-only, HiraxCode withholds the send and suggests models; press /drop to send text only.
• Local model missing — make sure the local server is running (Ollama/LM Studio/llama.cpp), then /model.
• Logs — ~/.local/state/hiraxcode/hiraxcode.log.
• Sessions — ~/.local/share/hiraxcode/sessions/*.json.
• Settings — ~/.config/hiraxcode/config.json.

Roadmap

• [ ] Diff preview before applying edits
• [ ] Syntax highlighting
• [ ] Subagents / parallel tasks
• [ ] MCP support
• [ ] Full themes (not just an accent)
• [ ] Per-provider cost & token tracking

Development

Questions, ideas, or bug reports — reach the developer on Telegram: @hirakox.

License

MIT