Hakimi Agent

Production-grade AI Agent — rewritten in Rust for speed, safety, and multi-surface control
_{Inspired by Nous Research Hermes Agent · built to match and surpass it}

Install · Why Hakimi · Features · Unique Design · Commands · Studio · Architecture · 中文

One-Click Install

Linux / macOS

curl -sSL https://raw.githubusercontent.com/Mouseww/hakimi-agent/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/Mouseww/hakimi-agent/main/install.ps1 | iex

From source (any platform with Rust)

cargo install --git https://github.com/Mouseww/hakimi-agent --locked
# or after clone:
cargo build --release -p hakimi-agent

First run

hakimi setup      # guided config wizard (providers, keys, gateway)
hakimi doctor     # diagnose install, systemd, gateway processes, port 3005, config/session DB, connectivity
hakimi            # local TUI (same as `hakimi tui`)
hakimi "prompt"   # one-shot CLI print mode
hakimi chat       # interactive CLI entrypoint (compatibility placeholder until REPL wiring lands)
hakimi gateway start  # multi-platform gateway (Telegram, Discord, …)
hakimi --gateway start # legacy gateway alias
# WebUI runtime has been removed; use Gateway/CLI/TUI/Studio surfaces instead

Release binaries (CLI + bundled hakimi-tui launcher): GitHub Releases on tags v*. Use hakimi tui --smoke to verify the packaged TUI through the main hakimi launcher, or hakimi-tui --smoke to probe the bundled TUI binary directly without entering raw terminal mode. Desktop Studio packs (deb / AppImage / MSI / DMG): Actions Desktop workflow artifacts, or attached on the same tag release when packaging succeeds.

Why Hakimi?

	Typical Python agent	Hakimi (Rust)
Startup	~2s	~50ms
Idle memory	~150MB	~15MB
Async	asyncio + GIL	tokio native
Tool safety	runtime crashes	compile-time traits
Error recovery	basic retry	20+ classifiers + recovery
Context	manual / fragile	3-tier smart compression
Surfaces	CLI or chat	CLI · TUI · WebUI · Gateway · Studio desktop

Not a thin wrapper. Hakimi is a production agent runtime: credential pools with circuit breakers, secret redaction, SSRF guards, path jails, multi-device Studio protocol, and release pipelines for both CLI and desktop.

Features

Agent core

Full agent loop in Rust only (not TypeScript) with SSE / chunk streaming
63+ tools: files, shell, web, browser/CDP, computer-use readiness, code exec, vision/TTS/STT, todo, cron, memory, knowledge graph, MCP, delegation
Sub-agents & teams: delegate_task, named personas, multi-level delegation with depth limits
Smart context: drop stale tool noise → LLM summary → sliding window; model-aware context length
Intent + roles: classify intent, adapt Coder / Researcher / Writer modes
Memory: short/long/working tiers, FTS5, session search (discovery / scroll / browse)
Checkpoints: shared shadow-git store under ~/.hakimi/checkpoints (not your project .git)

Control surfaces

Surface	What it is
CLI	REPL, setup, doctor, skills, plugins, profiles
TUI	ratatui UI, slash commands, voice PTT, skins
WebUI	Removed runtime; use TUI, Gateway, Studio desktop, or the optional Studio backend surfaces instead
Gateway	Telegram · Discord · Slack · Signal · WhatsApp · Feishu · WeCom · Matrix · Email · …
Studio	Local-first workbench: workspace IDE, multi-device handoff, Hub relay, desktop shell

Gateway highlights

Streaming with progressive edits, flood control, UTF-8-safe chunking
Busy input: queue or interrupt (gateways.busy_input_mode)
Slash commands: /cron, /usage, /stop, /undo, /voice, /update, …
Optional hide_tool_details — keep ⚙️ progress indicators, hide raw STDOUT/JSON dumps
Cron: intervals + five-field expressions, deliver to origin / home / all channels

Safety

Secret redaction (API keys, JWTs) before model/output surfaces
Prompt-injection heuristics on skills / cron / context files
SSRF blocklist, dangerous shell patterns, tool-loop guardrails
Write safe-root sandbox + Studio path deny policy (.env, .git, keys, …)
Controller / Viewer roles for multi-device Studio sessions

Extensibility

MCP client (stdio / HTTP / SSE) + catalog snippets
HTTP plugins (YAML) and WASM plugin path (evolving)
Skills Hub: install community skills
OpenAI-compatible discovery: /v1/models, /v1/chat/completions, /v1/runs, …
Isolated profiles (--profile) for config / memory / sessions / cron

Unique Design

Ideas that define Hakimi vs “just another agent wrapper”:

Office View — personas as desks in a shared office: live state, tool progress on monitors, team handoff animation, SSE-driven without polling.
Studio Protocol — seq-numbered events, gap detection + session reset, single active runner, Controller/Viewer roles, pure Hub relay (no provider keys on the hub).
Local-first execution — default run on your machine; switch location via Hub worker dispatch when you need remote runners.
Queue + preempt — dual input model: queue follow-ups or preempt the current run.
Workspace jail + checkpoints — path-jailed FS, auto pre-write snapshots, worktree isolation for agent sessions.
Desktop = shell — hakimi-desktop embeds backend + WebUI; optional Tauri window is UI only, agent loop stays in Rust.
Hermes alignment — gateway slash commands, skin engine, voice, session/search shapes — then go further on multi-device and Studio packaging.

Design docs: docs/hakimi-studio/ · docs/ARCHITECTURE.md

Commands

Everyday

hakimi                 # local TUI (default local experience)
hakimi tui             # local TUI explicitly
hakimi "…prompt…"      # one-shot CLI print mode
hakimi chat            # interactive CLI entrypoint (REPL wiring pending; use TUI today)
hakimi setup           # wizard
hakimi doctor          # install/systemd/gateway/config diagnostics
hakimi gateway start   # messaging platforms
hakimi --gateway start # legacy gateway alias
hakimi tui --smoke  # verify packaged TUI via the main launcher
hakimi-tui --smoke  # verify the TUI binary directly without raw terminal mode
# TUI keys: F1 or /help opens command help,
#           Tab completes slash commands or toggles the tools panel,
#           Shift+Tab always toggles the tools panel, Esc clears the current input/completion hint,
#           ↑↓/Ctrl+P/Ctrl+N/PageUp/PageDown scroll; Ctrl+L jumps back to latest,
#           Home/End or Ctrl+A/Ctrl+E jump input start/end,
#           Ctrl+Left/Alt+Left or Alt+B jumps to previous word,
#           Ctrl+Right/Alt+Right or Alt+F jumps to next word,
#           Ctrl+U/Ctrl+K clear before/after cursor,
#           Ctrl+W or Alt+Backspace deletes the previous word; Alt+D or Ctrl+Delete deletes the next word,
#           Ctrl+D deletes under cursor or exits when empty,
#           Ctrl+C quits.
# Type /shortcuts inside the TUI to show the same key reference without the full command help.
# Type /about inside the TUI to show version and local-surface summary without calling the model.
# Type /status inside the TUI to show local session/model/state counters without calling the model.
# Type /usage inside the TUI to show local token/API counters without calling the model.
# Type /doctor inside the TUI to show local TUI readiness diagnostics; use `hakimi doctor` for install/systemd checks.
# Type /logs inside the TUI to show recent local TUI log lines without calling the model.
# Type /model inside the TUI to show the current model; /model NAME explains safe restart-based switching.
# Type /providers inside the TUI to show the current provider/model transport snapshot and supported API modes.
# Type /memory inside the TUI to show read-only persistent memory status and paths.
# Type /skin inside the TUI to show the active skin; /skin NAME explains restart-based theme switching.
# Type /tips inside the TUI to show practical TUI usage tips.
# Type /commands (or /help local) inside the TUI to show the local slash-command catalog without calling the model.
# Type /tools status inside the TUI to inspect recent tool activity; /tools on|off controls the side panel without calling the model.
# hakimi serve / --serve are retained only to report that the old WebUI runtime was removed

Studio / desktop

# Headless Studio backend (WebUI static + /v1/studio WS)
cargo run -p hakimi-desktop -- --bind 127.0.0.1:3015

# Smoke (listen, print URL, exit)
cargo run -p hakimi-desktop -- --once

# Native window (Tauri 2; needs webkit2gtk-4.1 on Linux)
cargo run -p hakimi-desktop --features gui

Docs: docs/hakimi-studio/DESKTOP.md

Ops / products

hakimi plugin list|install|info …
hakimi skills …
hakimi knowledge …
hakimi skin list|set …
hakimi cron …          # or manage via WebUI / gateway /cron

Gateway (in-chat)

Command	Purpose
`/stop`	Cancel run + clear queue
`/undo [N]`	Rewind turns / prefill edit
`/usage`	Tokens, cost, rate limits
`/cron …`	Schedule jobs
`/voice …`	TTS / STT mode
`/update`	Self-update path (release-aware)

Dev

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
RUST_LOG=debug cargo run -p hakimi-cli

CI packaging (cloud, not local EL9 GUI):

CI — fmt / clippy / tests
Desktop — headless + GUI packs on Ubuntu 22.04 / Windows / macOS
Release — tag v* → multi-target CLI binaries (+ desktop assets when Desktop attaches)

Hakimi Studio

Local-first AI development workbench:

Piece	Role
`hakimi-studio-api`	Protocol, EventBus, runtime, agent host
`hakimi-workspace`	Path jail, worktrees, checkpoints
`hakimi-hub`	Pure relay or embedded runtime
`hakimi-server`	Runner + Studio WS + Hub worker client
`hakimi-desktop`	Local binary / optional Tauri GUI
WebUI Studio panels	Files, chat, devices, ecosystem, cron, checkpoints

Device A (Controller) ──WS──┐
Device B (Viewer)    ──WS──┼── Runtime ── Agent (Rust) ── Tools / Workspace
Hub (relay only)     ──WS──┘       ▲
                                   └── optional remote worker_dispatch

Permissions: docs/hakimi-studio/PERMISSIONS.md
Checkpoint: docs/hakimi-studio/CHECKPOINT.md
Protocol: docs/hakimi-studio/protocol.md

Architecture

hakimi-agent/
├── hakimi-core/           # Loop, errors, credentials, delegation
├── hakimi-transports/     # OpenAI / Anthropic / Gemini / Bedrock …
├── hakimi-tools/          # Built-in tools + registry
├── hakimi-session/        # SQLite WAL + FTS5
├── hakimi-context/        # Compression, request planning, intent, roles
├── hakimi-knowledge/      # Graph memory
├── hakimi-skills/         # Skills + meta extraction
├── hakimi-cron/           # Persistent scheduler
├── hakimi-gateway/        # Platform adapters
├── hakimi-mcp/            # MCP client
├── hakimi-cli/ · hakimi-tui/
├── hakimi-server/         # Unified serve + Studio + hub worker
├── hakimi-studio-api/ · hakimi-workspace/ · hakimi-hub/
└── hakimi-desktop/        # Studio desktop shell

Turn pipeline (simplified)

Message → Intent / Role → Context (compress → request-local plan)
        → Credential pool → LLM stream → Tool dispatch + guards
        → Session / memory

Compare

	Hermes (Python)	Hakimi
Language	Python 3.11+	Rust 2024
Startup / RAM	~2s / ~150MB	~50ms / ~15MB
Tool model	runtime	compile-time traits
Multi-device Studio	—	seq events, handoff, Hub relay
Office / persona desks	—	first-class WebUI
Desktop pack	—	Tauri 2 CI matrix
Gateway breadth	strong	parity + more adapters

Configuration (quick)

Item	Notes
Config dir	`~/.hakimi/` (or profile-scoped)
WebUI password	`HAKIMI_WEBUI_PASSWORD` → Bearer prompt
Language	`display.language` / `HAKIMI_LANGUAGE`
Hide tool dumps	`gateways.hide_tool_details` (keeps ⚙️ progress)
Busy input	`gateways.busy_input_mode`: `queue` \| `interrupt`

Run hakimi setup for the full wizard.

License

MIT License

中文说明 → README_CN.md · Studio 设计 → docs/hakimi-studio/DESIGN.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.hermes/plans		.hermes/plans
.spec-workflow		.spec-workflow
crates		crates
deploy		deploy
docs		docs
examples		examples
qq-bot-sdk		qq-bot-sdk
registry		registry
release_assets		release_assets
scripts		scripts
skills/software-development/hakimi-webui		skills/software-development/hakimi-webui
tasks		tasks
templates		templates
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
EVOLUTION_COMPLETE_REPORT.md		EVOLUTION_COMPLETE_REPORT.md
EVOLUTION_ENGINE_LAUNCH.md		EVOLUTION_ENGINE_LAUNCH.md
EVOLUTION_ROADMAP.md		EVOLUTION_ROADMAP.md
GAP_ANALYSIS.md		GAP_ANALYSIS.md
HERMES_TELEGRAM_FORMAT.md		HERMES_TELEGRAM_FORMAT.md
INTEGRATIONS.md		INTEGRATIONS.md
LICENSE		LICENSE
MEMORY_ENHANCEMENT_v0.5.56.md		MEMORY_ENHANCEMENT_v0.5.56.md
README.md		README.md
README_CN.md		README_CN.md
RELEASE_NOTES_v0.5.10.md		RELEASE_NOTES_v0.5.10.md
RELEASE_NOTES_v0.5.56.md		RELEASE_NOTES_v0.5.56.md
WEBUI_OPTIMIZATION_v0.5.9.md		WEBUI_OPTIMIZATION_v0.5.9.md
install.ps1		install.ps1
install.sh		install.sh
test_output.txt		test_output.txt

Navigation Menu

Repository files navigation

Hakimi Agent

One-Click Install

Why Hakimi?

Features

Agent core

Control surfaces

Gateway highlights

Safety

Extensibility

Unique Design

Commands

Everyday

Studio / desktop

Ops / products

Gateway (in-chat)

Dev

Hakimi Studio

Architecture

Compare

Configuration (quick)

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Hakimi Agent

One-Click Install

Why Hakimi?

Features

Agent core

Control surfaces

Gateway highlights

Safety

Extensibility

Unique Design

Commands

Everyday

Studio / desktop

Ops / products

Gateway (in-chat)

Dev

Hakimi Studio

Architecture

Compare

Configuration (quick)

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages