Model or dataset
linghungegeg/Linghun avatar
linghungegeg/Linghun

Linghun: an evidence-first AI coding runtime for the terminal

AGI-oriented, hallucination-resistant AI coding runtime grounded in evidence, tools, memory, agents, and verification.

475 stars20 forksTypeScriptApache-2.0

At a glance

What is it?
Linghun is a local-first TypeScript CLI that puts model output behind evidence, permissions and verification. It is aimed at developers who want an agent to read code, edit files and run checks rather than just describe what to do.
Who is it for?
Adopt Linghun if you want a terminal agent whose claims are tied to file reads, tool results and verification records, and if you work on Windows or in mixed-language projects where pre-check indexing matters. Skip it if you need a documented rollback story, a stable published release line, or evidence of maintenance you can verify from the repository itself.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • linghungegeg/Linghun475 ★ · +16
Star history
Repository2026-09-212026-11-15
linghungegeg/Linghun459475

16 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What problem Linghun is trying to solve

Linghun's README frames the problem in terms of the gap between an answer and a delivered change. A chat tool can tell you how a file should be modified. Linghun's stated concern is whether the model actually read the relevant code, actually edited the right file, actually ran the verification, and said plainly where it is uncertain. The README describes this as an anti-hallucination runtime rather than a prompting technique: the constraints live in the execution path, not in an instruction asking the model to be careful.

The target user is a developer working in a terminal on a real repository. The README lists Windows first among its badges and calls out Windows, PowerShell, Chinese paths and paths containing spaces as environments it is built to handle. That is a narrower and more specific claim than the usual cross-platform line, and it suggests the project's early testing was concentrated there. It also lists multi-agent exploration, role-based model switching (planning, execution, review, summarization), and MCP, Skills, Plugins, Hooks and Capability Connectors as extension points. The breadth is large; the README does not rank which of these are mature.

The runtime chain: evidence, permissions, verification, final gate

The mechanism described in the README is a single chain rather than a set of features. Reading a file produces evidence. Editing passes through permission and path checks. Verification feeds into the final answer. Git state informs whether a stable point exists for rollback or handoff. Failure records influence the next scheduling round. Agent and job results enter as context only and, per the README, cannot be presented as a PASS on their own.

That last rule is the most concrete design decision in the README. A sub-agent reporting "completed" or a remote event arriving is treated as an input, not as proof. The README states that final answers should distinguish local verification, mock verification, real smoke tests and unverified conclusions. This is a distinction that most agent frameworks leave to the prompt; here it is described as a runtime constraint on the output.

A second layer sits underneath: a pre-check engine. The updates list says that as of 2026-07-12 the engine exposes only five mature chains (TypeScript/TSX, Python, Rust, Go, Java), and that Windows, Linux and macOS platform packages carry pinned compatible versions of TypeScript and Pyright. The same entry describes the engine as giving the model an index, an impact scope and language-level pre-check results before work starts, with the goal of cutting redundant file reads and re-exploration. The scope is deliberately limited: five languages, not every language the runtime can edit.

Installing @linghun/cli and getting a first answer

The README's quick start requires Node.js 22 or newer plus npm, pnpm or another Node package manager. Installation is a global npm install, and the binary is named linghun. The README shows the two commands together as the entire entry point.

bash
npm install -g @linghun/cli
linghun

After the install, running linghun with no arguments starts the terminal interface. The repository's package.json exposes both a lower-case linghun binary and a capitalized Linghun binary, so either spelling resolves on a case-sensitive filesystem; on Windows the distinction rarely matters.

Provider credentials are not passed as flags. The .env.example file is a template, and its comment states that copying it is optional because the /model setup command creates ~/.linghun/provider.env for you. The same comment notes that shell environment variables override provider.env, which is the useful part when you want a temporary key without editing the file.

bash
LINGHUN_OPENAI_BASE_URL=
LINGHUN_OPENAI_API_KEY=
LINGHUN_OPENAI_MODEL=
LINGHUN_OPENAI_ENDPOINT_PROFILE=chat_completions
LINGHUN_OPENAI_INCLUDE_USAGE=false
LINGHUN_INFERENCE_LEVEL=Medium
LINGHUN_AUX_MODEL=

LINGHUN_AUX_MODEL is documented as optional, and the comment says leaving it empty makes helper roles follow the main model. LINGHUN_OPENAI_ENDPOINT_PROFILE defaults to chat_completions. There is no documented model name in the example, so the first real step after starting the TUI is running /model setup and filling in the base URL, key and model for whichever provider you use. If you are working from the repository rather than the npm package, package.json defines the build as corepack pnpm -r build and the test command as vitest run, with a typecheck script at tsc -b tsconfig.json.

Where the design shows strain

The README does not document rollback. It mentions Git stable points, handoff and rollback as goals, and the capability list includes checking Git status and creating stable points, but no command, flag or procedure for undoing an applied change appears in the README. For a tool whose pitch is controlled execution, that is the missing half of the story.

Release provenance is the second gap. The README's update log references published versions such as @linghun/[email protected] on 2026-07-16, while the repository's own package.json still declares version 0.1.0 and is marked private. The repository has no published GitHub releases. So the version you install from npm and the version in the repository are not the same artifact, and the README does not explain how they are kept in step.

The benchmark claim needs the same care. The README reports a Terminal-Bench 2.1 score of 78.43% and an expected sixth place, but states that the submission PR is awaiting merge and that the official ranking depends on that merge. A pending PR is not a published ranking.

Finally, the README says the whitepaper's scenario table (for example +25% to +50% on complex engineering tasks, +80% to +200% on risk and security boundaries) consists of architectural estimates, not precise measurements or a speed promise for any project. The table is presented as an explanation of where the coupling helps, not as a result. Treat it as a hypothesis about the design. The cache hit figures (a 92%-96% target range, up to 98% on high-stability samples) carry the same caveat in the README itself.

Linghun compared with a plain terminal agent loop

The obvious alternative is a conventional terminal agent: a loop that sends the model a prompt, executes whatever tool call comes back, and prints the result. The difference is where the check lives. In a plain loop, "run the tests before claiming success" is a sentence in the system prompt, and the model can skip it. In Linghun, according to the README, the claim itself is gated: the final answer is supposed to be assembled after evidence alignment, and a sub-agent's summary cannot stand in for a verified result.

That trade has a cost the README does not quantify. Gates and permission checks add steps that a plain loop does not perform, and the README's own scenario table concedes that for simple questions and small code edits the gain is only +5% to +15%, with the note that unnecessary gates can interrupt. If your work is short, single-file edits against a model you already trust, the runtime is mostly overhead.

The second alternative is a prompt-and-skills setup. Linghun supports prompts, skills and workflows, but the README argues that prompts cannot guarantee that a write passes a permission check, that a Bash command is classified and logged, or that a completion claim is backed by evidence. Whether that argument holds for your work depends on how often you have seen an agent claim success without running anything. The pre-check engine is also a differentiator in kind: an index and impact scope computed before the model starts is something a prompt cannot supply.

Maintenance, licence and upgrade cost

The repository is not archived. Its last push was on 2026-08-19, roughly a month before this writing, and the README's update log runs through 2026-07-16. The log is dense and dated, which tells you the project was moving quickly through July 2026; it does not tell you what has happened since the last push, and the repository has no published GitHub releases. There is no published versioning or deprecation policy in the README, so an upgrade from one @linghun/cli version to the next has no documented compatibility guarantee.

The practical upgrade cost comes from the pinned pre-check engine. The 2026-07-12 entry says the platform packages ship fixed compatible versions of TypeScript and Pyright. That means the language tooling moves with the Linghun release rather than with your project's own devDependencies, which is good for reproducibility and awkward if your repository needs a newer TypeScript than the bundled one.

Linghun is Apache-2.0. That permits commercial and private use and includes an explicit patent grant, and it requires that the licence and notices be preserved and that modified files carry prominent change notices. It is a permissive licence, not a copyleft one, so it does not force you to publish your own code. The repository's package.json declares the same Apache-2.0 identifier. This is a description of the licence text, not legal advice; if you redistribute a modified build, read the notice and change-notice clauses yourself.

One operational note from the README: do not put real keys in tracked files. The provider template is tracked, and the intended location for real credentials is ~/.linghun/provider.env, with shell environment variables taking precedence over it.

Editorial conclusion

Adopt Linghun if you want a terminal agent whose claims are tied to file reads, tool results and verification records, and if you work on Windows or in mixed-language projects where pre-check indexing matters. Skip it if you need a documented rollback story, a stable published release line, or evidence of maintenance you can verify from the repository itself. Before installing, open docs/updates.md and check the entries for 2026-07-12 and 2026-07-16, which describe the pre-check engine's five supported language chains and the platform packages shipped with them.

Frequently asked questions

How do I install the Linghun CLI?

Install it globally from npm with npm install -g @linghun/cli, then run linghun. You need Node.js 22 or newer and a Node package manager such as npm or pnpm.

How does Linghun configure the model provider and API key?

The .env.example file is a template, and its comment says copying it is optional because the /model setup command creates ~/.linghun/provider.env. Shell environment variables override provider.env, and LINGHUN_AUX_MODEL can be left empty so helper roles follow the main model.

Which languages does the Linghun pre-check engine support?

The update log entry for 2026-07-12 states that the pre-check engine exposes only five mature chains: TypeScript/TSX, Python, Rust, Go and Java. The platform packages for Windows, Linux and macOS carry pinned compatible versions of TypeScript and Pyright.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. linghungegeg/Linghun on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/linghungegeg-linghun.svg)](https://hysenlabs.com/projects/linghungegeg-linghun)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/linghungegeg-linghun.svg)](https://hysenlabs.com/projects/linghungegeg-linghun)

Was this useful?