h-uman

not quite human.

Bring AI to every device on Earth.
~2468 KB binary. < 6 MB RAM. Boots in <30 ms. Runs on anything with a CPU.

The smallest fully autonomous AI assistant infrastructure — a static C binary that fits on any $5 board, boots in milliseconds, and requires nothing but libc.

~2468 KB binary · <30 ms startup · 14,317+ tests · 97 providers · 31 channels · 87 tools · Pluggable everything

Features

• Impossibly Small: ~2468 KB static binary — no runtime, no VM, no framework overhead.
• Near-Zero Memory: < 6 MB peak RSS. Runs comfortably on the cheapest ARM SBCs and microcontrollers.
• Instant Startup: 6–27 ms on Apple Silicon, sub-50 ms on edge cores.
• True Portability: Single self-contained binary across ARM, x86, and RISC-V. Drop it anywhere, it just runs.
• Feature-Complete: 97 providers (9 core + 88 compatible), 31 channels, 87 tools, hybrid vector+FTS5 memory, multi-layer sandbox, tunnels, hardware peripherals, MCP, subagents, streaming, voice — the full stack.
• Interactive TUI: Full-screen terminal UI with split panes, markdown rendering, multi-session tabs (Ctrl+T), tool approval prompts, streaming output, and input history. Build with -DHU_ENABLE_TUI=ON and run with --tui.
• Performance-Optimized: Per-turn arena allocator, HTTP connection pooling, HTTP/2, system prompt caching — all benefiting from C-level control.
• HuLa programs: Optional JSON IR for structured multi-step tool plans (seq / par / branch / delegate / …) with policy checks and traceable runs — docs site · repo guide.

Why human

• Lean by default: C11 compiles to a tiny static binary. No runtime overhead, no garbage collector, no framework.
• Secure by design: pairing, strict sandboxing (landlock, firejail, bubblewrap, docker), explicit allowlists, workspace scoping, encrypted secrets.
• Fully swappable: core systems are vtable interfaces (providers, channels, tools, memory, tunnels, peripherals, observers, runtimes).
• No lock-in: OpenAI-compatible provider support + pluggable custom endpoints.

Install (macOS)

The fastest way to get running on macOS:

1. Download the installer: human-latest.pkg (Apple Silicon or Intel)
2. Install to /Applications/Human.app (double-click the .pkg)
3. Verify: /Applications/Human.app/Contents/MacOS/human --version

See Installation Guide for:

• Step-by-step walkthrough with screenshots
• Gatekeeper and permission dialogs explained
• Homebrew and source-build alternatives
• Troubleshooting (human doctor, Full Disk Access, etc.)

Landscape

Similar projects in the autonomous AI assistant space (data sourced from each project's own documentation):

	OpenClaw	NanoBot	PicoClaw	ZeroClaw	Human
Language	TypeScript	Python	Go	Rust	C
RAM ¹	—	—	< 10 MB	< 5 MB	< 6 MB
Binary Size ¹	~28 MB (npm dist)	N/A (Python)	~8 MB	~8.8 MB	~2468 KB
Runtime Deps	Node.js ≥22	Python ≥3.11	None (static)	None (static)	None (static)

¹ RAM and binary size figures for other projects are self-reported from their respective READMEs. Human's numbers are measured locally with /usr/bin/time -l on a MinSizeRel + LTO build.

Human's verified numbers (measured on macOS arm64, March 2026):

Binary size:   ~2468 KB (MinSizeRel + LTO, all channels)
Peak RSS:      ~5.7 MB (--version), ~5.9 MB (test suite)
Startup:       6–27 ms avg (Apple Silicon M4 Max)
Tests:         14,317 passing, 0 ASan errors

Why Switch from OpenClaw?

• Security: Encrypted secrets (ChaCha20-Poly1305) vs plain-text API keys; curated skill registry with no malicious packages.
• Cost: $5 hardware vs $599+ setup; no $300/mo API overhead from bloated runtime.
• Supply chain: 0 dependencies vs 1,200+ npm packages.
• Privacy: Single binary, no telemetry, full data ownership.

Reproduce locally:

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=MinSizeRel -DHU_ENABLE_LTO=ON
cmake --build .
ls -lh human

/usr/bin/time -l ./human --help
/usr/bin/time -l ./human status

Installation

Homebrew (macOS / Linux)

# Head-only (from source)
brew install --HEAD ./Formula/human.rb

# With curl support
brew install --HEAD ./Formula/human.rb --with-curl

Docker

docker pull ghcr.io/sethdford/h-uman:latest
docker run --rm ghcr.io/sethdford/h-uman:latest --version

Nix

nix run github:sethdford/h-uman
# Or add to flake inputs
nix build github:sethdford/h-uman

Debian / Ubuntu

Download the .deb from Releases:

sudo dpkg -i human_*.deb

Install Script

# macOS / Linux
curl -fsSL https://h-uman.ai/install.sh | sh

# Windows (PowerShell) — installs via WSL
irm https://h-uman.ai/install.ps1 | iex

Windows

Human runs inside WSL (Windows Subsystem for Linux). If WSL isn't installed:

wsl --install          # then restart
irm https://h-uman.ai/install.ps1 | iex

Or use Docker: docker run -it ghcr.io/sethdford/h-uman:latest agent

From Source

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=MinSizeRel -DHU_ENABLE_LTO=ON
cmake --build . -j$(nproc)
sudo cp human /usr/local/bin/

Quick Start

Prerequisites: C compiler (gcc or clang), CMake 3.20+. For full features: SQLite3 and libcurl. macOS: brew install cmake sqlite3 curl Linux: sudo apt-get install cmake libsqlite3-dev libcurl4-openssl-dev

The dev preset (cmake --preset dev) enables all features and requires SQLite and libcurl.

git clone https://github.com/sethdford/h-uman.git
cd h-uman
# Optional first-time: git config user.name "You" && git config user.email "you@example.com"
# After hooks pass: git push -u origin <your-branch>
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=MinSizeRel -DHU_ENABLE_LTO=ON -DHU_ENABLE_ALL_CHANNELS=ON
cmake --build .
cd ..

# Mac users: zero-config with Apple Intelligence (on-device, free)
human onboard --apple

# Or pick any provider
human onboard --provider openrouter --api-key sk-...

# Or interactive wizard
human onboard

# Chat
human agent -m "Hello, human!"

# Interactive mode
human agent

# Start gateway runtime (gateway + all configured channels/accounts + heartbeat + scheduler)
human gateway                # default: 127.0.0.1:3000
human gateway --port 4000    # custom port

# Check status
human status

# Run system diagnostics
human doctor

# Check channel health
human channel status

# Start specific channels
human channel start telegram
human channel start discord
human channel start signal

# Manage background service
human service install
human service status

# Migrate memory from SQLite or Markdown
human migrate sqlite /path/to/brain.db
human migrate markdown /path/to/memories/

Dev fallback (no global install): prefix commands with build/ (example: build/human status).

Edge MVP (Hybrid Host + WASM Logic)

If you want edge deployment (Cloudflare Worker) with Telegram + OpenAI while keeping agent policy in WASM, see:

examples/edge/cloudflare-worker/

This pattern keeps networking/secrets in the edge host and lets you swap/update logic by replacing a WASM module.

Architecture

Every subsystem is a vtable interface — swap implementations with a config change, zero code changes.

Subsystem	Interface	Ships with	Extend
AI Models	Provider	97 providers — 9 core + 88 compatible (OpenRouter, Anthropic, OpenAI, Gemini, Ollama, llama.cpp, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, etc.)	custom:https://your-api.com — any OpenAI-compatible API
Channels	Channel	CLI, Telegram, Signal, Discord, Slack, iMessage, Matrix, WhatsApp, Webhook, IRC, Lark/Feishu, OneBot, Line, DingTalk, Email, Nostr, QQ, MaixCam, Mattermost, and more	Any messaging API
Memory	Memory	SQLite with hybrid search (FTS5 + vector cosine similarity), Markdown	Any persistence backend
Tools	Tool	85 built-in: shell, file ops, git, memory, browser, screenshot, composio, http, cron, hardware, web search, delegate, computer use, LSP, and more	Any capability
Observability	Observer	Noop, Log, File, Multi	Prometheus, OTel
Runtime	RuntimeAdapter	Native, Docker (sandboxed); WASM and Cloudflare adapters are stubs behind HU_ENABLE_RUNTIME_EXOTIC (OFF)	Any runtime
Security	Sandbox	Landlock, Firejail, Bubblewrap, Docker, auto-detect	Any sandbox backend
Identity	IdentityConfig	OpenClaw (markdown), AIEOS v1.1 (JSON)	Any identity format
Tunnel	Tunnel	None, Cloudflare, Tailscale, ngrok, Custom	Any tunnel binary
Heartbeat	Engine	src/observability/heartbeat.c periodic tasks	—
Skills	Loader	TOML manifests + SKILL.md instructions	Community skill packs
Peripherals	Peripheral	Serial, Arduino, Raspberry Pi GPIO, STM32/Nucleo	Any hardware interface
Cron	Scheduler	Cron expressions + one-shot timers with JSON persistence	—

Memory System

All custom, zero external dependencies:

Layer	Implementation
Vector DB	Embeddings stored as BLOB in SQLite, cosine similarity search
Keyword Search	FTS5 virtual tables with BM25 scoring
Hybrid Merge	Weighted merge (configurable vector/keyword weights)
Embeddings	EmbeddingProvider vtable — OpenAI, custom URL, or noop
Hygiene	Automatic archival + purge of stale memories
Snapshots	Export/import full memory state for migration
Connections	LLM-powered insight discovery across memory entries
Consolidation	Periodic dedup, decay scoring, automatic insight generation
Multimodal	File ingestion (text, PDF, images) with LLM extraction
Source Tracking	Source attribution persisted across all storage backends

{
  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3,
    "hygiene_enabled": true,
    "snapshot_enabled": false
  }
}

Persona System

Data-driven personality cloning — human can adopt a user's real communication style by analyzing their message history.

Component	Description
Profile	JSON persona file (~/.human/personas/<name>.json) with traits, vocabulary, communication rules, values
Channel Overlays	Per-channel style overrides (formality, message length, emoji usage, style notes)
Example Banks	Curated message examples per channel for few-shot style matching
Prompt Builder	Generates system prompt injection from persona + overlay + examples
Sampler	Extracts messages from iMessage (chat.db), Gmail, or Facebook exports
Analyzer	Sends message batches to AI provider for personality extraction
Creator	Orchestrates the full pipeline: sample → analyze → synthesize → write

# Create a persona from your iMessage history
human persona create myname --from-imessage

# Show persona profile
human persona show myname

# Use in config
# ~/.human/config.json: { "agent": { "persona": "myname" } }

The persona tool is also available in-conversation for agents to manage personas dynamically.

Security

human enforces security at every layer.

#	Item	Status	How
1	Gateway not publicly exposed	Done	Binds 127.0.0.1 by default. Refuses 0.0.0.0 without tunnel or explicit allow_public_bind.
2	Pairing required	Done	6-digit one-time code on startup. Exchange via POST /pair for bearer token.
3	Filesystem scoped	Done	workspace_only = true by default. Null byte injection blocked. Symlink escape detection.
4	Access via tunnel only	Done	Gateway refuses public bind without active tunnel. Supports Tailscale, Cloudflare, ngrok, or custom.
5	Sandbox isolation	Done	Auto-detects best backend: Landlock, Firejail, Bubblewrap, or Docker.
6	Encrypted secrets	Done	API keys encrypted with ChaCha20-Poly1305 using local key file.
7	Resource limits	Done	Configurable memory, CPU, disk, and subprocess limits.
8	Audit logging	Done	Signed event trail with configurable retention.

Channel Allowlists

• Empty allowlist = deny all inbound messages
• "*" = allow all (explicit opt-in)
• Otherwise = exact-match allowlist

Nostr additionally: the owner_pubkey is always allowed regardless of dm_allowed_pubkeys. Private keys are encrypted at rest via SecretStore (enc2: prefix) and only decrypted into memory while the channel is running; zeroed on channel stop.

Nostr Channel Setup

human speaks Nostr natively via NIP-17 (gift-wrapped private DMs) and NIP-04 (legacy DMs), using nak.

Prerequisites: Install nak and ensure it's in your $PATH.

Setup via onboarding wizard:

human onboard   # configures Nostr when selected

The wizard will:

1. Generate a new keypair for your bot or import a key & encrypt it with ChaCha20-Poly1305
2. Ask for your (owner) pubkey (npub or hex) — always allowed through DM policy
3. Configure relays and DM relays (kind:10050 inbox)
4. Display the bot's pubkey

Or configure manually in the config.

How it works: On startup, human announces its DM inbox relays (kind:10050), then listens for incoming NIP-17 gift wraps and NIP-04 encrypted DMs. Outbound messages mirror the sender's protocol. Multi-relay rumor deduplication prevents duplicate responses when the same message is delivered via multiple relays.

Configuration

Config: ~/.human/config.json (created by onboard)

Config structure: human uses top-level providers (array), default_provider, and default_model. Channels use accounts wrappers under channels.<name>.accounts.

Metacognition (optional): Tune bounded re-entry, hysteresis, and calibrated risk via agent.metacognition in config.json. Example: docs/examples/config.agent.metacognition.json. Merge into your config with jq: ./scripts/merge-agent-metacog-config.sh (install jq; backs up ~/.human/config.json). Environment overrides: HUMAN_METACOGNITION, HUMAN_METACOG_MAX_REGEN; agent turn also reads HUMAN_METACOG_LOGPROBS for OpenAI-style logprobs. Details: docs/api/config.md, docs/man/human.1. Inspect SQLite history: ./scripts/metacog-analytics.sh → docs/operations/metacog-analytics.md.

{
  "default_temperature": 0.7,

  "providers": [
    { "name": "openrouter", "api_key": "sk-or-..." },
    { "name": "groq", "api_key": "gsk_..." },
    {
      "name": "anthropic",
      "api_key": "sk-ant-...",
      "base_url": "https://api.anthropic.com"
    }
  ],
  "default_provider": "openrouter",
  "default_model": "anthropic/claude-sonnet-4",

  "agents": {
    "defaults": {
      "heartbeat": { "every": "30m" }
    },
    "list": [
      {
        "id": "researcher",
        "model": { "primary": "openrouter/anthropic/claude-opus-4" },
        "system_prompt": "..."
      }
    ]
  },

  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123:ABC",
          "allow_from": ["user1"],
          "reply_in_private": true,
          "proxy": "socks5://..."
        }
      }
    },
    "discord": {
      "accounts": {
        "main": {
          "token": "dihu-token",
          "guild_id": "12345",
          "allow_from": ["user1"],
          "allow_bots": false
        }
      }
    },
    "irc": {
      "accounts": {
        "main": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "human",
          "channel": "#human",
          "tls": true,
          "allow_from": ["user1"]
        }
      }
    },
    "slack": {
      "accounts": {
        "main": {
          "bot_token": "xoxb-...",
          "app_token": "xapp-...",
          "allow_from": ["user1"]
        }
      }
    },
    "nostr": {
      "private_key": "enc2:...",
      "owner_pubkey": "hex-pubkey-of-owner",
      "relays": [
        "wss://relay.damus.io",
        "wss://nos.lol",
        "wss://relay.nostr.band"
      ],
      "dm_allowed_pubkeys": ["*"],
      "display_name": "Human",
      "about": "AI assistant on Nostr",
      "nip05": "human@yourdomain.com",
      "lnurl": "lnurl1..."
    }
  },

  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "language": "ru",
        "models": [{ "provider": "groq", "model": "whisper-large-v3" }]
      }
    }
  },

  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  },

  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3
  },

  "gateway": {
    "port": 3000,
    "require_pairing": true,
    "allow_public_bind": false
  },

  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },

  "runtime": {
    "kind": "native",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "memory_limit_mb": 512,
      "read_only_rootfs": true
    }
  },

  "agent": {
    "persona": "myname"
  },

  "tunnel": { "provider": "none" },
  "secrets": { "encrypt": true },
  "identity": { "format": "openclaw" },

  "security": {
    "sandbox": { "backend": "auto" },
    "resources": { "max_memory_mb": 512, "max_cpu_percent": 80 },
    "audit": { "enabled": true, "retention_days": 90 }
  }
}

Full Web Search + Shell Access

Use this when you want full web-search provider control plus unrestricted shell command allowlist behavior:

{
  "http_request": {
    "enabled": true,
    "search_base_url": "https://searx.example.com",
    "search_provider": "auto",
    "search_fallback_providers": ["jina", "duckduckgo"]
  },
  "autonomy": {
    "level": "full",
    "allowed_commands": ["*"],
    "allowed_paths": ["*"],
    "require_approval_for_medium_risk": false,
    "block_high_risk_commands": false
  }
}

• http_request.search_base_url accepts either instance root (https://host) or explicit endpoint (https://host/search).
• Invalid http_request.search_base_url now fails config validation at startup (no automatic fallback for malformed URL).
• http_request.search_provider supports: auto, searxng, duckduckgo (ddg), brave, firecrawl, tavily, perplexity, exa, jina.
• http_request.search_fallback_providers is optional and is tried in order when the primary provider fails.
• Provider env vars: BRAVE_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY, PERPLEXITY_API_KEY, EXA_API_KEY, JINA_API_KEY (or shared WEB_SEARCH_API_KEY where supported). DuckDuckGo and SearXNG do not require API keys.
• allowed_commands: ["*"] enables wildcard command allowlist matching.
• allowed_paths: ["*"] allows access outside workspace, except system-protected paths.

Web UI / Browser Relay

Use channels.web for browser UI events (WebChannel v1):

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "local",
          "listen": "127.0.0.1",
          "port": 32123,
          "path": "/ws",
          "auth_token": "replace-with-long-random-token",
          "allowed_origins": [
            "http://localhost:5173",
            "chrome-extension://your-extension-id"
          ]
        }
      }
    }
  }
}

• Local: keep "listen": "127.0.0.1".
• Local and relay use the same pairing flow: send pairing_request, receive pairing_result, then include UI access_token in every user_message.
• auth_token is optional hardening for WebSocket upgrade and required when binding non-loopback addresses.
• Remote host: set "listen": "0.0.0.0" and terminate TLS at proxy/CDN (wss://...).
• UI/extension should live in a separate repository and connect via this WebSocket endpoint.
• Relay transport (outbound agent socket) is configured via:

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "relay",
          "relay_url": "wss://relay.human.io/ws/agent",
          "relay_agent_id": "default",
          "relay_token": "replace-with-relay-token",
          "relay_token_ttl_secs": 2592000,
          "relay_pairing_code_ttl_secs": 300,
          "relay_ui_token_ttl_secs": 86400,
          "relay_e2e_required": false
        }
      }
    }
  }
}

• Relay token lifecycle (dedicated): relay_token (config) -> HUMAN_RELAY_TOKEN (env) -> persisted web-relay-<account_id> credential -> generated token.
• Relay UI handshake: send pairing_request with one-time pairing_code, receive pairing_result with UI access_token JWT (and optional set_cookie string for relay HTTP layer).
• Relay user_message must include valid UI JWT in access_token (top-level or payload.access_token).
• If E2E is enabled (relay_e2e_required=true), UI and agent exchange X25519 keys during pairing and send encrypted payloads in payload.e2e.
• WebChannel event envelope is defined in spec/webchannel_v1.json.

Gateway API

Endpoint	Method	Auth	Description
/health	GET	None	Health check (always public)
/pair	POST	X-Pairing-Code header	Exchange one-time code for bearer token
/webhook	POST	Authorization: Bearer <token>	Send message: {"message": "your prompt"}
/whatsapp	GET	Query params	Meta webhook verification
/whatsapp	POST	None (Meta signature)	WhatsApp incoming message webhook

Commands

Command	Description
onboard --apple	Mac: zero-config Apple Intelligence setup
onboard --provider openrouter --api-key sk-...	Quick setup with API key and provider
onboard	Interactive setup wizard
onboard --channels-only	Reconfigure channels/allowlists only
agent -m "..."	Single message mode
agent	Interactive chat mode (CLI)
agent --tui	Full-screen terminal UI with tabs, approval, streaming
gateway	Start long-running runtime (default: 127.0.0.1:3000)
service install|start|stop|status|uninstall	Manage background service
doctor	Diagnose system health
status	Show full system status
channel status	Show channel health/status
cron list|add|remove|pause|resume|run	Manage scheduled tasks
skills list|install|remove|info|search	Manage skill packs
skills info <name>	Show skill details
skills publish	Publish skill to registry
hardware scan|flash|monitor	Hardware device management
models list|info|benchmark	Model catalog
persona create <name> [--from-imessage|--from-gmail|--from-facebook]	Create persona from message history
persona show <name>	Display persona profile
persona list	List all persona profiles
persona delete <name>	Remove persona profile
migrate sqlite / migrate markdown [path]	Import memories from SQLite or Markdown source

Development

Build and tests require a C11 compiler and CMake 3.20+. One-time setup:

./scripts/setup-dev.sh   # activates git hooks, installs token pipeline

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DHU_ENABLE_ALL_CHANNELS=ON
cmake --build .                            # Dev build
./human_tests                             # 14,317+ tests
cd ..

ASan (AddressSanitizer) for leak/overflow detection during development:

cmake -B build -DHU_ENABLE_ASAN=ON
cmake --build build
./build/human_tests

Integration tests (optional): real libcurl HTTP and SQLite file I/O (human_core without HU_IS_TEST):

cmake --preset integration && cmake --build --preset integration
./build-integration/human_integration_tests

Release build (~2468 KB):

mkdir -p build-release && cd build-release
cmake .. -DCMAKE_BUILD_TYPE=MinSizeRel -DHU_ENABLE_LTO=ON
cmake --build .

Channel Flow Coverage

Channel CJM coverage (ingress parsing/filtering, session key routing, account propagation, bus handoff) is validated by tests in:

• src/channels/channel_manager.c (runtime channel registration/start semantics + listener mode wiring)
• src/config/config.c (OpenClaw-compatible channels.*.accounts parsing, multi-account selection/ordering, aliases)
• src/gateway/gateway.c (Telegram/WhatsApp/LINE/Lark routed session keys from webhook payloads)
• src/daemon.c (gateway-loop inbound route resolution for Discord/QQ/OneBot/Mattermost/MaixCam)
• src/channels/discord.c, src/channels/mattermost.c, src/channels/qq.c, src/channels/onebot.c, src/channels/signal.c, src/channels/line.c, src/channels/whatsapp.c (per-channel inbound/outbound contracts)

Project Stats

Language: C11 + ASM (aarch64, x86_64)
Source files: 2,084
Lines of code: ~445K
Test files: 882
Tests: 14,317
Binary: ~2468 KB (MinSizeRel + LTO, all channels)
Peak RSS: ~5.7 MB
Startup: 6–27 ms avg (Apple Silicon)
Dependencies: libc + optional SQLite, libcurl

Source Layout

src/
main.c CLI entry point + command routing
agent/ Agent loop, context, planner, compaction, dispatcher
channels/ 31 channel implementations (cli, telegram, discord, ...)
providers/ 50+ AI provider implementations
memory/ SQLite + markdown + LRU backends, embeddings, vector search
tools/ 87 tool implementations
security/ Policy, pairing, secrets, sandbox backends
runtime/ Runtime adapters (native, docker; wasm/cloudflare are gated stubs)
core/ Allocator, arena, error, json, http, string, slice
observability/ Log + metrics observers
gateway/ HTTP gateway server
persona/ Persona profiles, prompt builder, example banks
ml/          ML training subsystem (BPE, GPT, optimizer) — HU_ENABLE_ML
feeds/       Feed processor, research agent, social feeds
intelligence/ Skills, self-improvement, value learning, world model
pwa/         Progressive web app bridge, context, entities
voice/       Voice pipeline, WebRTC, realtime
config.c Config loading/merging (~/.human/config.json)
...

include/human/ Public C headers
tests/ 580+ test files, 14,317+ tests
asm/ Platform-specific assembly (aarch64, x86_64, generic C)

ui/ Web UI (LitElement + Vite)
apps/ios/ Native iOS app (SwiftUI)
apps/android/ Native Android app (Kotlin + Jetpack Compose)
apps/shared/ Shared packages (HumanKit for iOS)
apps/macos/   Native macOS app (SwiftUI)

Native CI: ci.yml runs iOS XCUITest on one simulator (via .github/actions/ios-uitest). The native apps fleet workflow (.github/workflows/native-apps-fleet.yml) runs a multi-simulator iOS matrix, multi-API Android emulators (connectedDebugAndroidTest), and an all-green SOTA gate. Local: scripts/run-native-fleet-local.sh quick (no Simulator UI tests) or full on macOS (includes XCUITest).

Web UI

The gateway ships a modern web dashboard built with LitElement and Vite. It connects to the gateway WebSocket and provides real-time chat, agent monitoring, tool results, session history, voice input, and full configuration management.

cd ui
npm install
npm run dev          # http://localhost:5173
npm run build        # production build → ui/dist/
npm test             # vitest unit tests
npx playwright test  # E2E tests

Design system tokens live in ui/src/styles/_tokens.css. Components use the hu- prefix (e.g., hu-card, hu-button, hu-badge).

Web UI Dashboard

17 views, all connected to the gateway via WebSocket:

View	Data Source	Interactive?
Overview	health, capabilities, channels, sessions	Refresh
Chat	chat.send/history, events	Full: type, send, streaming, abort
Sessions	sessions.list/patch/delete, chat.history	Select, rename, delete, resume
Agents	config.get, sessions.list, capabilities	Navigate to config
Models	models.list, config.get	Display only
Voice	chat.send + browser STT	Mic button, speech-to-text
Tools	tools.catalog	Search, expand params
Channels	channels.status	Display only
Skills	skills.list/install/enable/disable	Install, toggle
Cron	cron.list/add/remove/run	Add, run, delete jobs
Config	config.get/set/schema	Edit fields, raw JSON, save
Nodes	nodes.list, health	Display only
Usage	usage.summary	Display only
Logs	WebSocket events	Filter, clear
Memory	memory.status/list/consolidate/forget	Browse, search, filter, consolidate, forget
Automations	automations config	Display only
Security	security status	Display only

Mobile Apps

Native companion apps connect to the gateway via WebSocket:

iOS (SwiftUI, requires Xcode 15+):

cd apps/ios
swift build
open Package.swift   # opens in Xcode

Android (Kotlin + Jetpack Compose, requires Android Studio + JDK 17):

cd apps/android
./gradlew assembleDebug

Both apps persist the gateway URL, show real-time connection status, and support chat with tool call visualization. Shared design tokens live in apps/shared/.

Versioning

human uses CalVer (YYYY.M.D) for releases — e.g. v2026.2.20.

• Tag format: vYYYY.M.D (one release per day max; patch suffix vYYYY.M.D.N if needed)
• No stability guarantees yet — the project is pre-1.0, config and CLI may change between releases
• human --version prints the current version

Contributing

Implement a vtable interface, submit a PR:

• New Provider -> src/providers/
• New Channel -> src/channels/
• New Tool -> src/tools/
• New Memory backend -> src/memory/
• New Tunnel -> src/tunnel/
• New Sandbox backend -> src/security/
• New Peripheral -> src/peripherals/
• New Skill -> skills/ directory or submit to the skill registry

Disclaimer

human is a pure open-source software project. It has no token, no cryptocurrency, no blockchain component, and no financial instrument of any kind. This project is not affiliated with any token or financial product.

License

MIT — see LICENSE

---

h-uman — not quite human.

Star History