# Linghun: Evidence-First AI Coding Terminal with Anti-Hallucination Constraints

> Linghun is an npm-installed AI coding terminal that connects any OpenAI-compatible LLM to real project files, tool execution, and verification, using a runtime constraint system to prevent the model from claiming completion without evidence. It targets developers who want tighter control over what an AI agent actually reads, modifies, and verifies.

**linghungegeg/Linghun** — AGI-oriented, hallucination-resistant AI coding runtime grounded in evidence, tools, memory, agents, and verification.

- Repository: https://github.com/linghungegeg/Linghun
- Stars: 465 · Forks: 22
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/linghungegeg-linghun

## The Problem Linghun Addresses: Unconstrained LLM Engineering

AI coding tools that operate as chat interfaces face a structural problem: the model can claim to have read a file, fixed a bug, or passed a test without any system-level evidence that these things happened. The README describes the pattern directly: a model that answers confidently without having read the relevant code, a change that runs but breaks the project structure, a test of one small command presented as proof the whole project passes.

Linghun's approach is to move those constraints from the prompt level to the system level. Instead of asking the model to be careful, Linghun enforces that file reads produce entries in an evidence store, that edits go through a permission and path boundary checker, that verification results are attached to the final answer, and that agent summaries or job completions cannot be treated as passing verdicts without real evidence.

The project targets individual developers and small teams who work on real projects over multiple sessions, where context drift and repeated failures in the same area are the primary cost drivers.

## Anti-Hallucination Architecture: Evidence Store, Final Gate, and Verification

The README describes the anti-hallucination system as a set of runtime constraints that apply to every tool execution. When the model reads a file, the content enters an evidence store. When it makes an engineering claim, the system checks whether that claim is anchored to an evidence entry. The final gate is a runtime check that runs before the model's response is shown to the user: it verifies that the claimed outcomes match the actual tool results.

Four layers work together. The evidence-first layer records what was actually read and what tools actually returned. The permission layer controls which files can be edited and which Bash commands can run. The verification layer distinguishes between local unit test verification, mock verification, real smoke testing, and unverified conclusions. The Git layer manages stable points so that tasks can be resumed or rolled back.

The README notes that agent summaries, job completed events, and remote events cannot be treated as PASS by the system. A claimed completion that lacks supporting tool evidence does not pass the final gate. This is the core distinction from tools where the model's self-report is the primary signal.

## Installing Linghun and Configuring a Language Model

Linghun installs as a global npm package. Node.js 22 or newer is required:

```bash
npm install -g @linghun/cli
```

Start it in a project directory:

```bash
linghun
```

On Windows, an uppercase entry point is also available:

```powershell
Linghun
```

Check the installed version:

```bash
linghun --version
```

Once inside the terminal, run the model setup wizard:

```
/model setup
```

The wizard asks for an API base URL, an API key, a model name, and an inference level. The API key is saved to a user-level private provider.env file, not to the project directory. Run the doctor command to verify the provider configuration:

```
/model doctor
```

The .env.example file in the repository shows the expected variable names: LINGHUN_OPENAI_BASE_URL, LINGHUN_OPENAI_API_KEY, LINGHUN_OPENAI_MODEL, LINGHUN_OPENAI_ENDPOINT_PROFILE, and LINGHUN_INFERENCE_LEVEL.

## What Linghun Does in a Real Development Task

The README describes a typical task cycle. When a developer asks Linghun to fix a build failure, the system is designed to follow a sequence: read the project structure and relevant files first, form a plan, request confirmation for high-risk file writes or commands, execute edits through the tool runtime, run targeted verification, check the Git status, and then report what was changed, what was verified, and what remains uncertain.

This sequence is enforced by the runtime, not by the model's willingness to follow instructions. The model still does the reasoning and code generation, but the system records what it actually read, applies permission checks before writes, attaches verification results to the final answer, and creates Git stable points when appropriate.

For long tasks, Linghun supports background jobs and multi-agent exploration. The README describes role-based model routing: a planner role, an executor role, a reviewer role, and a summariser role can each use different models. The code index reduces repeated file reads across a session by providing pre-computed summaries of project structure and relevant code sections.

## Benchmark Results and Performance Claims

The README includes a Terminal-Bench 2.1 submission with a reported score of 78.43%, which the README states would place Linghun approximately sixth on the official leaderboard. The README also notes that the submission PR is pending merge and that the formal ranking is determined only after the PR is merged.

The whitepaper section in the README gives cache hit rate targets for stable configurations: 92 to 96 percent for a stable project, model, tool list, and system prompt, with higher rates for specific high-stability scenarios. The README explicitly qualifies these as architectural estimates rather than fixed performance guarantees, noting that actual results depend on project, model, task, and usage patterns.

The performance improvement estimates for different task types, ranging from small gains on simple tasks to larger gains on complex engineering tasks, are also from the whitepaper and carry the same qualification: they represent architectural reasoning about where the evidence-first constraints help most, not measured benchmarks.

## Limitations and How Linghun Compares to aider

Linghun works with any OpenAI-compatible API endpoint, which means it does not include its own model. Users must supply a model and API key. The choice of model significantly affects output quality in ways the runtime constraints cannot compensate for: a weak model will still produce poor code even with evidence-first enforcement.

The anti-hallucination system constrains what the model can claim to have done, but it cannot prevent incorrect edits that pass automated tests. A patch that introduces a logic error but does not break the tests will still show as verified. The verification layer records what was tested, not whether the tests adequately cover the changed code.

For comparison, aider is a widely known open-source AI coding CLI that also works with multiple LLM providers and uses Git for tracking changes. aider focuses on a clean diff-based workflow where the model produces unified diffs applied via Git. Linghun's focus is different: it adds an evidence and verification layer designed to constrain what the model can assert about its own completions. aider does not include a final-gate verification step or an evidence store; Linghun does not have aider's editor mode or its auto-commit workflow.

Linghun is Apache-2.0 licensed. The last push to the repository was on 2026-08-19.

## Conclusion

Linghun is worth trying for developers who have experienced LLM coding tools that claim tasks are complete without actually running tests, or that modify files without reading the relevant code first. The evidence-first and final-gate architecture addresses those patterns at the runtime level rather than relying on prompts to remind the model. It is not a drop-in replacement for tools that are bundled with a proprietary model; Linghun works with any OpenAI-compatible API, so you supply the model and the API key. Start with npm install -g @linghun/cli, then run /model setup inside the terminal to configure your provider, and linghun --version to confirm the installation.

## FAQ

### What language models does Linghun support?

Linghun works with any OpenAI-compatible API endpoint. The .env.example file shows variables for a custom base URL, API key, and model name, so it supports OpenAI, Anthropic (via compatible wrappers), and other providers that implement the same API interface.

### How does Linghun's anti-hallucination system work?

The system records file reads and tool results in an evidence store and applies a final gate before showing the model's response. The gate checks that claimed completions are backed by actual tool evidence. Agent summaries and job-completed events cannot be treated as passing verdicts without supporting evidence.

### What operating systems does Linghun support?

The README states that Linghun works on Windows (including PowerShell, Chinese paths, and paths with spaces), Linux, and macOS. A Windows-specific uppercase entry point Linghun is registered alongside the lowercase linghun command.

## Sources

- [Issues](https://github.com/linghungegeg/Linghun/issues)
- [License: Apache-2.0](https://github.com/linghungegeg/Linghun/blob/main/LICENSE)
- [linghungegeg/Linghun on GitHub](https://github.com/linghungegeg/Linghun)
- [README](https://github.com/linghungegeg/Linghun/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linghungegeg-linghun