Tianshu Harness: a TypeScript cognitive runtime for coding agents, with a prefix-cache engine

The failure Tianshu Harness was built to catch: a model that declares victory

The project's stated problem is not model capability. It is runtime behaviour. The README describes a pattern it calls Cognitive Anchor Collapse, where a locally salient signal takes over the policy distribution and the global goal loses weight. Four anchor types are named: lexical anchors (a sentence containing "fix" or "delete" overriding an instruction to explain only), semantic anchors (a locally correct fact such as "the file already exists" being promoted into the centre of the whole task), policy anchors (RLHF priors discarding an earlier analysis once the user says "execute your plan"), and history anchors (new evidence at turn 20 read as an appendix to a hypothesis from turn 3).

The claim is that this is a by-product of successful alignment training, not a defect, and therefore cannot be fixed by better prompting, because a prompt is information rather than state and can itself become a new anchor. That framing is what justifies a separate runtime instead of a longer system prompt. The target user is an engineer running long agent sessions where "should be fixed now" is not an acceptable delivery signal. The project is a TypeScript runtime, Apache-2.0, with a terminal TUI and a Tauri desktop client sharing one agent kernel.

How CVM sits between the model and the filesystem

The architecture is a two-loop design. The inner loop is the model's own reason, decide, act, observe cycle. The outer loop is runtime supervision: observe, measure, evaluate, gate, verify, then continue, correct or halt. The README compresses this to "Probabilistic Cognition inside Deterministic Supervision". The runtime does not change weights and does not make the model deterministic; it externalises goal, state, evidence, resources, permissions and termination conditions out of the conversation history and manages them itself.

Four defensive layers are described. First, a belief constitution injected as a static prompt. Second, a Courage Hook running at preTurn. Third, Sensorium, described as a six-dimension state probe costing under one millisecond per turn. Fourth, RuntimeHookPipeline, with 72 hooks spanning five phases that intercept degenerate behaviour in a trap-and-emulate pattern. Alongside these, a TaskContract holds the global goal as independent state, Evidence requires runtime artefacts (tests, diffs, verification commands) before a completion claim is accepted, and Convergence and doom-loop detection independently judge whether the cognitive trajectory is still advancing. The delivery gate is called deliver_task, backed by a post-commit review, with mechanical changes skipped automatically.

The A/B study the README links is worth reading sceptically. It used one model (DeepSeek-V4-Flash), five tasks, and a single variable: the belief prompt toggle STAR_SOUL=0/1, with Claude Opus 4.7 as reviewer. Task completion went from 4/5 to 5/5 and proactive dissent from 0/5 to 3/5. The README itself states the boundary: the experiment validates only the first of the four layers, belief injection, and found that the effect is strong in the analysis and suggestion stage but decays in the confirmation and execution stage. That is an unusually honest caveat, and it is also the strongest argument for the other three layers existing.

Installing Tianshu Harness and running a first task

The requirement stated in the README is Node.js 24 or newer. Three installation routes are given. The one-line script targets macOS and Linux, with a PowerShell equivalent for Windows. The npm route installs the package globally; note that the installed command is still rivet, the project's original development codename, kept for backward compatibility.

npm install -g tianshu-tui

The package's postinstall script runs an environment check, installs git hooks, fetches a native SQLite build and prunes unused WASM files, all with fallbacks that do not fail the install. After installation, the binary exposed by package.json is rivet, pointing at dist/cli/entry.js. The repository also ships config.example.json and config.example.toml at the top level, plus a .rivet-config.json in the repository root, which is where you should look for the configuration keys your build actually reads.

rivet

The README describes the terminal client as a self-written ANSI TUI with a GlanceBar status bar, a command palette and a Cockpit view. Once inside a session, the two commands worth knowing early are the cache diagnostic and the goal-driven autonomous mode.

/debug cache
/goal

The first reports prefix-cache hit rate and fragmentation reasons, which is the number you actually want on your own provider rather than the quoted figure. The second turns on goal-directed autonomous continuation. Project knowledge is written to .rivet/knowledge/memory.jsonl, and only governance and constraint memories are auto-injected; older problems require an explicit recall so they do not hijack a new task. If you prefer a read-focused start, Zen Mode narrows the tool surface to read-only and promotes to the full set on the first write action.

The prefix-cache engine is the part with the clearest cost story

The cache design is freeze-prefix plus incremental appendix plus boundary compression, with Read-ref deduplication and cache inheritance on resume. The README claims this applies to every model that supports prefix caching, with a steady-state hit rate of 98 to 99 percent in long sessions, and says DeepSeek V4 receives additional targeted optimisation. The package description in package.json repeats the 98 to 99 percent figure.

Two cautions belong here. First, the hit rate is a property of the provider's cache implementation as much as of the runtime, so the number you get depends on where you point it; /debug cache exists precisely because the runtime cannot guarantee what the upstream cache does. Second, prefix caching rewards a stable prompt prefix, which is in direct tension with injecting fresh state every turn. The freeze-plus-appendix split is the mechanism that resolves that tension, and it is the design decision I would want to see documented in more depth than the README provides. The user guide section on the prefix cache engine is where that detail would live.

Related cost controls are documented: automatic reasoning-effort downgrade routing, compact operations routed to a flash side path, and peak/off-peak pricing reminders.

Where Tianshu Harness gets in the way

The honest limitation is the one the project states about itself. The A/B evidence covers belief injection only, and the measured effect weakens exactly at the stage where a coding agent does its damage: confirmation and execution. The remaining three layers, Courage Hook, Sensorium and the 72-hook pipeline, are described in the documentation but the README does not present controlled results for them. Treat the four-layer defence as an architectural claim with one layer empirically supported.

There are structural costs too. The README reports the CLI source at 1,078 files and 257,623 lines with 16,471 test cases, and the install pulls a native SQLite build and git hooks through postinstall. That is a large surface for a tool that sits between you and your editor, and postinstall scripts that touch git hooks deserve a read before you run them in a shared environment. The runtime also imposes its own vocabulary and workflow: TaskContract, Evidence, star domains, council and team modes, Plan Mode. If your work is a short script edit, the supervision overhead buys you nothing.

Finally, the star domain system is the most opinionated part of the design. Sixteen domains are described as switchable cognitive disciplines that really swap system prompt, tool whitelist and decision thresholds. The README insists any domain can complete any task and that domains are perspectives rather than capability limits. That is a design position, not a measured result, and it is the feature most likely to divide users.

Tianshu Harness versus a plain model CLI

The natural alternative is a thin agent CLI that pipes your prompt and tool calls to the model and prints the result, with the conversation history as the only state. The difference is not features, it is where state lives. In a thin CLI, the goal, the evidence for completion and the termination condition all live inside the context window, which is exactly the substrate the project argues degrades under long sessions. Tianshu Harness moves those into runtime objects and then verifies against them.

That trade has a visible price. A thin CLI is easier to audit, has fewer moving parts, and does not need a hook pipeline or a cognitive model to explain itself. Tianshu Harness asks you to accept an opinionated theory of agent degradation before you get the benefit of the gate. If you have never seen a model claim completion without evidence, the machinery will look like ceremony. If you have, the deliver_task gate is the feature you are paying for.

Maintenance, licensing and what the release cadence tells you

The repository is not archived, and the last push was on 2026-09-17. Recent releases are v3.21.1 and runtime-v3.21.1 on 2026-09-16, with runtime-v3.21.0 the day before. The version in package.json is 3.21.1. That cadence, with a runtime artefact versioned separately from the CLI, indicates the runtime and the client are released on their own schedules; check which of the two a given changelog entry touches before upgrading.

The licence is Apache-2.0 for both the repository and the npm package. Apache-2.0 includes an express patent grant and requires that you preserve notices and state significant changes when you redistribute. It does not oblige you to publish your own modifications. This is a description of the licence text, not legal advice; if you are embedding the runtime in a product, have your own counsel read the NOTICE and attribution requirements.

Upgrade cost is dominated by the install surface rather than the source. The postinstall chain fetches a native SQLite binary and installs git hooks, so a global upgrade is not a pure JavaScript swap. The package ships a pinned better-sqlite3 under dist/node_modules and prunes unused WASM files, which means platform-specific artefacts are part of every install. Budget for that if you pin versions across a team.

Editorial conclusion

Adopt Tianshu Harness if you run long coding sessions against a prefix-cache-capable model and you want completion claims tied to test, diff or verification evidence rather than to the model's own word. Skip it if you need a small, auditable CLI, if your provider has no prefix caching, or if you cannot accept that the runtime's own A/B study measured belief injection and found that effect decaying at the confirmation and execution stage. Before committing, install with npm install -g tianshu-tui on Node.js 24 or newer, run a real task in a scratch repository, and use /debug cache to confirm the prefix hit rate on your provider rather than trusting the 98 to 99 percent figure quoted for other models.

Frequently asked questions

Official sources

1. huiliyi37/Tianshu-harness on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases