huagent

v6.2.0

Published

8 hours ago

AI coding agent CLI — 22 LLM providers, 101 models, wiki knowledge engine, OpenCode-inspired TUI, MIT-licensed

0High
0Medium
0Low

ai agent coding cli tui terminal anthropic claude openai gemini deepseek groq mistral openrouter ollama assistant chatbot developer-tools llm ink

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

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

| 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

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

The AI coding agent that learns from your codebase.