HUQAN

HUQAN

An agent proposes something. HUQAN decides whether it lands.

HUQAN is a local gate between an AI agent's output and the state it would change — a memory entry, a repository, a tool call. Every decision leaves a Trust Receipt: the evidence, the policy, the approver. No model, no cloud, no API key.

Try it in 30 seconds

$ npx -y huqan quickstart
HUQAN quickstart — learn -> review -> approve -> verify -> Trust Receipt
  1. OK   propose: huqan.learn -> review (mutating_requires_review), approval approval-…
  2. OK   approve: huqan.approve -> approved (actor cli-quickstart)
  3. OK   verify: verified (confidence 0.90)
  4. OK   receipt: receiptId … (status canonical)

The write in line 1 did not happen. It was held until line 2 approved it, and line 4 is the durable record of why. The quickstart uses a throwaway store and never touches your own memory.

No install: the same flow runs in the browser at huqan.com (a static simulation). What to run when: product surfaces.

Install

npm install -g huqan     # Node.js 22.13.0 or newer

Seven binaries: huqan (CLI), huqan-mcp (MCP server over stdio), huqan-gate (pre-execution guard for other agents), huqan-authority (which approval authority this runtime answers to, see ADR-016), and three bounded experiment CLIs, huqan-cognitive-lab, huqan-causal-lab and huqan-neural-lab. huqan doctor reports what is configured.

How it works

evidence + provenance + workspace scope
        → verification, contradiction, risk
                → policy and approval boundary
                        → outcome + Trust Receipt

The outcome is one of:

ALLOW / REVIEW / QUARANTINE / DRY-RUN ONLY / BLOCK / REJECT

A tool call returns allow, review, dry_run_only or block. A memory write can also be set aside (quarantine) or refused (reject).

Escalation is a decision a person makes, not one the gate returns. A reviewer can move a pending case to escalated, and nothing executes until the authority it was raised to answers. That needs a second approver, so it is absent in a single-user install. The decision types are approve, reject, expire, cancel, escalate and override — see lib/human-oversight-approval-runtime.js.

A passing verification is a result inside one configured boundary, not a certificate of truth. The receipt names the boundary.

What's new in 1.0.0

Since v0.13.2 — full list in CHANGELOG:

• huqan coder creates files, and --authorize lands real source changes. The create_file and sequence transforms apply test-file additions and multi-step fixes as one derivation. --authorize lifts only the SOURCE_CHANGE_REQUIRES_REVIEW hold with authorization explicitly supplied for that run; critical blocks, package/CI changes, and dirty-repo holds keep their own decision. Details: lib/cli-coder.js.
• MCP fails closed harder. A non-JSON arguments string no longer runs as an empty call; it returns ARGUMENTS_PARSE_ERROR with a block decision.
• AURA bridge (optional, external). A content-hashed signal pack from the AURA repository plants canary markers on the core egress path. No pack means no signal, never a wrong signal. Details: lib/aura-signal-pack.js.
• Self-healer. Autonomous read-only repository scan (audit_only) plus concrete fix generation from a verified failure record. Scope: docs/adr/ADR-007-self-healer-loop.md.
• Quiet fixes. quickstart no longer leaves a memory.db in the working directory; upload: learns a file's content, not its path; HUQAN_DB_PATH now co-locates all three stores.

Connect your agent

MCP (Claude, Cursor, any MCP client):

{
  "mcpServers": {
    "huqan": {
      "command": "npx",
      "args": ["-y", "--package=huqan", "huqan-mcp"]
    }
  }
}

--package=huqan is required because the binary name differs from the package name. The operator tools (huqan.approve, huqan.approvals, huqan.approval_detail, huqan.agent_resume, huqan.emergency_stop) are hidden from the model and need HUQAN_MCP_OPERATOR_TOKEN: an agent cannot approve its own proposal.

Other agents: huqan-gate ships with Claude Code, Codex, OpenHands, OpenCode, Pi and Hermes projections. It enforces only when the client calls it before executing. Details.

Use it directly

const Kernel = require('huqan');   // KernelV2
const kernel = new Kernel();

As a server: HUQAN_API_KEY=… npm run server on port 3000 — read-only /api, guarded /verify and /upload, the UI at /, the receipt viewer at /viewer.

Limits

• HUQAN does not eliminate hallucinations. It makes one inspectable and blockable before it becomes state.
• Only what is wired is governed. An agent that never calls HUQAN is not covered.
• Some shipped modules have no production caller yet; each is listed with its reason in lib/module-reachability.js. A green unit test is not deployment evidence.
• The conformance suites are self-run in this repository. They are not third-party verification. See the interoperability and attestation boundary.
• The unexpected-egress gate is fail-open by default until the expected destinations are declared, either with HUQAN_EXTERNAL_GUARD_EXPECTED_EGRESS or by the caller passing an expectedEgress policy. huqan doctor shows its state.
• Scale is measured up to 10k graph nodes on one machine: scale truth pack.
• It complements IAM, infrastructure security and human governance. It replaces none of them.

Compared with

Reach for	When the problem is	HUQAN's job instead
NeMo Guardrails	Filtering an LLM's inputs and outputs	Deciding whether an output earned the write, and recording why
LangChain guardrails / HITL	Framework checks and pause-and-resume around tool calls	A durable receipt binding evidence, scope, policy and approval to one decision
Docker MCP Gateway	MCP server lifecycle, credentials, isolation	The decision inside the call, not the isolation around it
DeepEval	Scoring model quality offline, in CI	The single live action, judged before it lands

Details, and when HUQAN is the wrong choice: competitive positioning.

More

npm ci && npm test                    # full suite
npm run conformance:external          # consumer conformance

When this page and the repository disagree, the repository wins.

License

AGPL-3.0-only. A commercial license is being prepared; those terms are not yet operative and this repository grants no commercial rights. CLA.md is a review draft, not an operative agreement.

---

Confidence is not truth. Verify before you trust.