huagent

Huagent

The AI Coding Agent That Learns Your Codebase

A production-grade AI coding agent in your terminal — powered by a wiki knowledge engine, OpenCode-inspired TUI, and 22 LLM providers.

Install · Features · Providers · Usage · Contributing · Docs

🖥️ Preview

  ╔════════════════════════════════════════════════════════════════════╗
  ║  huagent v6.0.0                                                     ║
  ║  AI coding agent CLI — 22 providers, 101 models                     ║
  ╚════════════════════════════════════════════════════════════════════╝

  │  Ask, search, or run /help for commands
  │  huagent · claude-sonnet-4   anthropic
  ╰
     ready · ↵ send · alt+↵ newline · ↑↓ history · tab complete · ctrl+c exit
  ~/projects/myapp • 2 LSP  /status
  tokens: 1247  cost: $0.0089  perm: workspace-write  ? help  Ctrl+P/T/E/R pickers

⚡ Install

Option 1: npm (recommended)

npm install -g huagent

Option 2: One-liner (from source)

curl -fsSL https://raw.githubusercontent.com/ahmdd4vd/Huagent/main/install.sh | sh

Option 3: From source (manual)

git clone https://github.com/ahmdd4vd/Huagent.git
cd Huagent
npm install
npm run build
node bin/huagent.js

Quick Start

# Set any provider's API key
export ANTHROPIC_API_KEY=sk-ant-***   # or OPENAI_API_KEY, GEMINI_API_KEY, etc.

# Launch the TUI
huagent

Node.js >= 18 required. Huagent auto-detects your provider from environment variables — set one and you're ready.

✨ Features

🧠 Wiki Knowledge Engine	🎨 OpenCode-Inspired TUI	🔌 22 LLM Providers
5-memory system that learns from your codebase	Left-border prompt, minimal aesthetic, braille spinners	Anthropic, OpenAI, Gemini, DeepSeek, Groq, +17 more
🔄 Auto-Ingest	⌨️ Full Keyboard Control	🛡️ Security-First
Watches files & auto-creates wiki pages	Emacs keys, multi-line, history, autocomplete	SSRF protection, path-traversal guards, default-deny
📊 Cost Tracking	🔍 Smart Search	🧪 239 Tests
Real-time token count + cost per request	Fuzzy matching with intent-based routing	Comprehensive test suite covering all subsystems

🧠 WllmConcept — Knowledge That Grows

Huagent ships with a wiki knowledge engine that makes your agent smarter over time.

┌─────────────────────────────────────────────────────────┐
│                  5-Memory System                         │
│                                                         │
│   Semantic ──── Facts, concepts, entities               │
│   Episodic ──── Events, debugging sessions              │
│   Structural ── Architecture, dependencies              │
│   Causal ────── Decisions, tradeoffs, migrations        │
│   Meta ──────── Self-reflection, heuristics             │
│                                                         │
│   Confidence: ASSUMED → INFERRED → VERIFIED             │
│   Freshness:  LOW → MEDIUM → HIGH → STALE               │
└─────────────────────────────────────────────────────────┘

• Auto-Ingest — File watcher extracts functions, classes, patterns, and relationships automatically
• Scheduled Lint — 7 quality checks with A–F grading and auto-fix
• Evolve — Detects contradictions, suggests new pages, refreshes stale knowledge at session end
• Intent-Based Routing — "what is", "how to", "why", "when", "compare", "pattern", "history"

🎨 Modern TUI (OpenCode-Inspired)

• Left-border prompt — signature OpenCode look, no boxy borders
• Braille spinners (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) for thinking/writing states
• Multi-line input — Alt+Enter inserts newline, ↑↓ navigate between lines
• Emacs editing — Ctrl+A/E (line start/end), Ctrl+U/K (delete to start/end), Ctrl+W (delete word)
• History navigation — ↑↓ through previous prompts
• Slash command autocomplete — type /mod → get /model, /models, /modes
• Global shortcuts — Ctrl+P (provider), Ctrl+T (model), Ctrl+E (scope), Ctrl+R (resume), Ctrl+L (clear), ? (help)
• Tool call badges — inline status (✓ success, ✗ error, ⠋ running)
• Footer status bar — directory, LSP/MCP counts, /status hint
• Responsive layout — adapts to terminal width and height

⌨️ Full Keyboard Control

Key	Action
Enter	Submit prompt
Alt+Enter / Shift+Enter	Insert newline (multi-line)
↑ / ↓	Navigate history (single-line) or cursor (multi-line)
← / →	Move cursor horizontally
Ctrl+A / Home	Move to line start
Ctrl+E / End	Move to line end
Ctrl+U	Delete to line start
Ctrl+K	Delete to line end
Ctrl+W	Delete previous word
Tab	Accept autocomplete suggestion
Esc	Close autocomplete / dialog
Ctrl+C	Exit huagent
Ctrl+P	Open provider picker
Ctrl+T	Open model picker
Ctrl+E	Open scope picker
Ctrl+R	Resume previous session
Ctrl+K	Command palette
Ctrl+L	Clear messages
?	Show help dialog

🛡️ Security-First Design

• SSRF protection — web tool blocks private IPs, loopback, cloud metadata (169.254.169.254), link-local
• Path traversal guards — session ids, /export filenames validated against ^[A-Za-z0-9_-]+$
• Shell injection prevention — grep and hooks use execFile with arg arrays (no shell interpolation)
• Default-deny permissions — unknown tools are denied by default in workspace-write mode
• OAuth secret hardening — Google OAuth secrets support env override (HUAGENT_GOOGLE_*_CLIENT_SECRET)
• ZIP-bomb protection — bundle reader tracks actual decompressed bytes, not just reported size

🌐 Providers

22 providers, 101 models. Each with a default model, full registry, and capability metadata.

Category	Models
Flagship	Claude Opus 4.7, Claude Sonnet 4.6, GPT-5.5, Gemini 3 Pro, Grok 4
Reasoning	DeepSeek R1, o3, QwQ 32B, Sonar Reasoning, Magistral Medium
Fast	Claude Haiku 4.5, GPT-5 mini, Llama 3.1 8B, Gemini 3 Flash
Code	Qwen 3 Coder 480B, Codestral 25, DeepSeek Coder V2, GPT-5.5 Codex
Local (free)	Ollama (Llama 3.2, Qwen 2.5 Coder 32B, DeepSeek R1 32B)
Search	Perplexity Sonar Pro
Cloud	AWS Bedrock, Google Vertex AI

Browse in the TUI:

/providers              # all 22 providers
/models                 # models for current provider
/models anthropic       # models for a specific provider

Auto-Detect

Set any of these env vars and huagent picks the provider automatically:

Click to expand all 22 environment variables

Env var	Provider
ANTHROPIC_API_KEY	Anthropic Claude
OPENAI_API_KEY	OpenAI
GEMINI_API_KEY	Google Gemini
MINIMAX_API_KEY	MiniMax
TOKENROUTER_API_KEY	Custom (TokenRouter)
GROQ_API_KEY	Groq
DEEPSEEK_API_KEY	DeepSeek
OPENROUTER_API_KEY	OpenRouter
GITHUB_TOKEN	GitHub Copilot
HF_TOKEN	HuggingFace
PERPLEXITY_API_KEY	Perplexity
TOGETHER_API_KEY	Together AI
FIREWORKS_API_KEY	Fireworks AI
CEREBRAS_API_KEY	Cerebras
XAI_API_KEY	xAI Grok
MISTRAL_API_KEY	Mistral
NVIDIA_API_KEY	NVIDIA NIM
OPENCODE_API_KEY	OpenCode Zen
CODEX_API_KEY	OpenAI Codex
MIMO_API_KEY	Xiaomi MiMo
AWS_BEARER_TOKEN_BEDROCK	AWS Bedrock
GOOGLE_APPLICATION_CREDENTIALS	Google Vertex AI

🛠️ Usage

Slash Commands

Command	What it does
/model <name>	Switch LLM model
/provider <name>	Switch provider
/models	Browse all 101 models
/providers	List all 22 providers
/autonomous	Toggle autonomous mode
/scope <file>	Limit edits to one file
/permissions <mode>	Switch permission mode
/memory	Inspect knowledge base
/skills	List installed skills
/status	Session status + stats
/cost	Token usage + cost breakdown
/sessions	List saved sessions
/resume <id>	Resume a session
/diff	Show git diff
/doctor	Run diagnostics
/clear	Fresh session
/help	Show all commands
/exit	Exit huagent

CLI Flags

huagent                                              # interactive TUI
huagent "fix the auth bug"                           # one-shot mode
huagent --provider anthropic --model claude-sonnet-4 # pick provider + model
huagent --autonomous                                 # no confirmations
huagent --scope src/auth.ts                          # limit to one file
huagent --permission-mode sandboxed                  # sandboxed edits
huagent --no-tui                                     # simple REPL mode
huagent version                                      # show version
huagent --help                                       # show help

Permission Modes

Mode	What you can do
read-only	Read files, no edits
workspace-write	Edit project files (default)
sandboxed	Edits go to a temp directory
danger-full-access	No confirmations at all
allow	Auto-approve everything (autonomous)

📊 By the Numbers

Metric	Value
LLM Providers	22
Models	101
Tests	239 passing
Source Files	130+ TS/TSX
Slash Commands	26
Permission Modes	5
Memory Systems	5
TUI Components	20+
Documentation	6,000+ lines
Lines of Code	25,000+
Security Fixes	72 bugs fixed
Keyboard Shortcuts	20+

🧪 Testing

npm test              # run all 239 tests
npm run verify        # lint + test + build

Suite	Tests	What it covers
Provider integrity	350	22 providers, 101 models, pricing, auto-detect
TUI stress	153	Visual regression, 40–240 cols, unicode, edge cases
Discipline	181	Plan → Ground → Observe → Diagnose → Verify
TUI v4	119	Theme, activity store, status bar, slash commands
CLI commands	68	All 26 slash commands, option parsing
WllmConcept	26	WikiMemory, 5-memory routing, lint, evolve
Auto-Ingest	25	Content analyzer, file watcher, page creation
OpenCode TUI	52	Theme, borders, MessageList, Prompt, Picker, Dialog
Keyboard	16	Enter, Esc, Tab, Ctrl+C/U/W, Alt+Enter, arrows
App shortcuts	8	Ctrl+P/T/E/L, ?, stats, footer
Security	25	SSRF, path traversal, LRU, dialog reset, limit:0
Render	23	MessageList, Footer, Dialog, Picker rendering

🏗️ Architecture

src/
├── cli.tsx                   # entry point, bootstrap, arg parsing
│
├── providers/                # 22-provider abstraction layer
│   ├── registry.ts           # provider registry + auto-detect
│   ├── models.ts             # 101-model catalog with pricing
│   ├── client.ts             # unified streaming client
│   ├── capabilities.ts       # model capability metadata
│   ├── pricing.ts            # cost calculation engine
│   └── executors/            # provider-specific executors
│
├── engine/                   # AI engine core
│   ├── core.ts               # main engine loop + WikiStore integration
│   ├── wiki-memory.ts        # backward-compatible wiki memory wrapper
│   └── v4/                   # stream-native actor model
│       ├── discipline/       # Plan → Ground → Observe → Diagnose → Verify
│       ├── stream/           # SSE pipeline + cognitive events
│       ├── actor/            # actor model + supervisor
│       ├── htn/              # hierarchical task network planner
│       └── graph/            # SQLite-backed graph store
│
├── tui/                      # terminal user interface
│   ├── OpenCodeApp.tsx       # production TUI (OpenCode-inspired)
│   └── oc/                   # OpenCode-style components
│       ├── theme.ts          # 12-step grayscale + semantic palette
│       ├── border.ts         # SplitBorder, LeftBorder, TopBorder
│       ├── MessageList.tsx   # chat history with tool call badges
│       ├── Prompt.tsx        # left-border textarea + autocomplete
│       ├── Footer.tsx        # status bar (directory, LSP, MCP)
│       ├── Dialog.tsx        # modal dialogs (confirm, alert, help)
│       └── Picker.tsx        # fuzzy-searchable list dialog
│
├── wllm/                     # wiki knowledge engine
│   ├── graph/                # WikiStore (bi-temporal property graph)
│   ├── ingest/               # content analyzer + auto-ingest
│   ├── lint/                 # quality audit (7 checks, A–F grade)
│   ├── evolve/               # self-reflection engine
│   └── query/                # intent-based search + 5-memory routing
│
├── tools/                    # built-in tools (bash, file ops, search, git)
├── memory/                   # SQLite-backed session memory
├── sessions.ts               # session save/load/resume
└── slash-commands.ts         # 26 runtime commands

📚 Documentation

Guide	Description
User Guide	Getting started, configuration, daily usage
Architecture	System design, engine internals, TUI layout
API Reference	Full API documentation for all modules
WllmConcept	Wiki knowledge engine deep-dive
Auto-Ingest	File watcher + content analysis
Contributing	How to contribute to Huagent
Security	Vulnerability reporting + threat model
Changelog	Release history

🤝 Contributing

Bug reports and feature requests welcome via issues.

See CONTRIBUTING.md for development setup and guidelines.

Quick Start for Contributors

git clone https://github.com/ahmdd4vd/Huagent.git
cd Huagent
npm install
npm run dev           # watch mode (auto-rebuild on save)
npm test              # run all 239 tests
npm run verify        # lint + test + build (must pass before PR)

Commit Message Format

type(scope): short summary

Body explaining the why. Reference issues with #123.

Types: feat, fix, chore, docs, test, refactor, style, perf.

🔒 Security

See SECURITY.md for the vulnerability reporting policy and threat model.

Don't open a public issue for security bugs. Use GitHub's private vulnerability reporting: https://github.com/ahmdd4vd/Huagent/security/advisories/new

📦 Publishing (Maintainers)

# 1. Update version in package.json
# 2. Update CHANGELOG.md
# 3. Run verify
npm run verify

# 4. Publish to npm
npm publish

# 5. Tag and push
git tag v6.0.0
git push origin v6.0.0

MIT © 2026 Huanime

Built with Ink · Inspired by OpenCode, claw-code, and OpenClaude

_{The AI coding agent that learns from your codebase.}