Tianshu Harness

A Cognitive Runtime for Coding Agents
_{Goals that don't drift · Completion with evidence · Verification that closes the loop}

Install · How it works · Evidence · Star Domains · User Guide   |   English · 中文 · 日本語 · 한국어 · AtomGit

_{The same task, two endings. A model's claim of completion is not evidence — the gate asks for proof.}

A model's capability ceiling is not its runtime behaviour. Put the same weights into a real engineering session and they get talked out of a position, follow instructions too literally, let local signals override the global goal, or keep calling tools without making progress — and then hand you "it should be fixed now."

Tianshu is a coding-agent runtime written in TypeScript. The terminal TUI, the desktop app, and the VS Code extension share one agent kernel. Between the model and the real world it places a Cognitive Virtual Machine (CVM) that lifts goals, state, evidence, permissions, and termination conditions out of the conversation history and hands them to the runtime:

• Task contracts — Every task gets a TaskContract recording goal, scope, constraints, and success criteria. Long sessions are held by the runtime, not by the model's memory.
• Separated commit, verification and review — deliver_task performs only an ownership-scoped safe commit: it blocks on ownership, cross-session conflicts and version consistency; verification gaps are disclosed honestly, never blocked on and never turned into quality endorsement. Targeted verification uses run_tests (explicit scope), independent review uses review_changes or /review.
• A deterministic outer loop — 75 runtime hook modules across five phases of a turn, together with Sensorium state awareness and stall detection, observe and correct between model output and real action.

_{Left: terminal TUI · Right: desktop app · one agent kernel}

[!NOTE] The project was originally codenamed Rivet. The primary CLI command is tianshu, with rivet kept as a compatibility alias for the same entry point; the data directory stays ~/.rivet.

Table of Contents

• Install
• Your First Task
• How CVM Works
• Evidence
• Star Domains
• More Capabilities
• Supported Models
• Permissions & Security
• Documentation
• For Developers
• Community
• License

Install

npm install -g tianshu-harness
tianshu

[!WARNING] Hard Node.js requirement (v3.36.0+): the CLI supports only Node 24.22.1+ (24.x line) or Node 26.12.1+ (26.x line). Node 22 / 23 / 25 / 27, Node 24.x below 24.22.1, and Node 26.x below 26.12.1 are rejected at startup by the security gate. /update may install the new package successfully while the new CLI still cannot start. Run node -v first; if it does not match, upgrade via nvm / fnm / Volta or nodejs.org before installing.

node -v   # requires v24.22.1+ or v26.12.1+

The desktop app bundles its own runtime; no manual Node installation is required. If it still fails after the upgrade, see the installation guide and troubleshooting guide.

# macOS / Linux
bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.sh)

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.ps1 | iex"

Android Termux, building from source, shell completions, and auto-update: Installation & Platform Guide.

Your First Task

Start read-only so it can learn your project and you can confirm it read it correctly, then hand it a multi-step task:

〉 Read this project, tell me its structure, where the entry points are, and one thing most worth improving
〉 Fix the first failing test in this project and explain the root cause

It searches, reads files, edits code, and runs tests on its own. The default permission tier is Auto: low-risk actions run directly, high-risk actions stop and ask. Afterwards, look at three places:

tianshu -p "explain src/agent/loop.ts"           # one-shot prompt
tianshu --stream-json -p "refactor this module"  # NDJSON event stream, redacted output
tianshu --goal "fix all type errors" --budget 50  # goal-driven autonomous continuation

How CVM Works

_{One task, from input to delivery: contract → domain binding → frozen prefix → turn loop → evidence gate → memory.}

Alignment-tuned models show the same runtime failure mode in agent settings, which we call Cognitive Anchor Collapse: one high-salience local signal over-concentrates the policy, the global goal and later evidence lose weight, and behaviour collapses toward that anchor. A prompt is information, not state — it eventually becomes just another anchor, which is why better prompting alone cannot cure this.

CVM does not change weights and does not turn the model into a deterministic program. It wraps deterministic supervision around probabilistic cognition — the model reasons and acts in the inner loop; the runtime measures, gates, and verifies in the outer loop, deciding whether to continue, correct, or halt:

Inner loop · model cognition   reason → decide → act → observe
Outer loop · runtime supervision  observe → measure → evaluate → gate → verify → continue / correct / halt

Eight design principles and the open research questions: CVM: From Shared Transformer Degradation to a Cognitive Runtime. System layering: Architecture Overview.

Evidence

Cache: longer context, steadier hits

_{Real session c9774121 · DeepSeek V4 Pro · 4.2 hours · 412 requests. Context grew 15×; hit rate went up, not down.}

Tianshu is designed prefix-cache first: the prefix is frozen within a session, only deltas are appended, and compaction happens only at user-turn boundaries. In the 4.2-hour session above, 15 prefix rebuilds produced 383K cacheCreate tokens — 0.33% of all input.

The cache engine works for every model with prefix caching; published measurements cover DeepSeek only. Every number ships with a jq recomputation command: Observability Harness.

Behaviour: same weights, opposite reactions

_{2026-05-19 · one model, five real tasks, sole variable was the belief layer (STAR_SOUL=0/1) · reviewed by Claude Opus 4.7.}

The most telling case is T4. Facing a "file already exists" contradiction, group A wrote a 196-line retrospective and refused to act; group B inferred the real intent and delivered +162 / −20 lines of working code.

This is a small pilot: 5 tasks, a single model, LLM review. It also measured the decay — beliefs hold during analysis and advice and weaken markedly at confirmation and execution, which is exactly what layers 3 and 4 exist to cover. Full data: CVM Empirical Report.

Engineering

As of 2026-10 (v3.37): src/ holds roughly 1,700 source files and 350K lines; tests are about 2,100 files and 23,000 cases. TypeScript strict with noUncheckedIndexedAccess, and every incident fix ships with a regression test. Definitions and milestones: Engineering Metrics.

Star Domains

_{Sixteen star domains laid out on the Big Dipper. Each star names a working inclination, not a new capability.}

Walk the same model into different star domains and different working inclinations light up. A star domain does not add capabilities — it amplifies a facet the model already has, and corresponds to CVM layers 1 and 2: each domain carries its own belief block and courage threshold. The person is still the same person; the model is still the same model.

New sessions default to Qiming. Switch with /domain <name>, auto-match from message content with /domain auto, and list all sixteen with /domain list. Full inscriptions, founding memories, and the structured table (ID · primary model · sigil · role · motto): Star Domain Stele (English) · 星域碑文（中文）.

• 启明 Qiming: Light the path first; don't walk it in the user's stead. Probe through the fog and make the next step clear.
• 长庚 Changgeng: Unhurried at the close. See the result with your own eyes, and leave a clear trail for whoever comes tomorrow.
• 天枢 Tianshu: See the whole map first, then walk the plan all the way into verified delivery.
• 天权 Tianquan: Put both sides on the scale. What is the gain, what is the cost — say it plainly once seen.
• 天机 Tianji: Ask the question no one has asked yet: what if this premise does not hold?
• 天璇 Tianxuan: Shift to a completely different angle. Once seen, go prove whether it is real.
• 天梁 Tianliang: Carry an entrusted plan all the way through. What was done, what remains, where it drifted — every step leaves an echo.
• 华盖 Huagai: On a long road, never stop at "looks done"; leave behind structure that can be built upon.
• 破军 Pojun: Strike into the unknown first. Even a failed probe shrinks the unmapped territory, leaving a path rather than ruins.
• 天府 Tianfu: Listen first to why existing code is shaped the way it is. Make changes that leave it steadier, never more brittle.
• 七杀 Qisha: Ask by what right something still occupies its place. Point it out, but never swing the blade yourself.
• 开阳 Kaiyang: Ask first what the real numbers are and why they deserve belief. Act only after the ledger reconciles.
• 瑶光 Yaoguang: A green light is not proof. Only when the original failure can be reproduced does a fix count as proven.
• 文曲 Wenqu: Strip away the superfluous so intent reveals itself. Beauty must be visible on the screen.
• 辅 Fu: Emit no light of its own; distill what has already happened into a method that can be clearly seen.
• 太一 Taiyi: Pause first. Let this move settle completely before starting the next.

More Capabilities

Supported Models

Built-in presets cover 25 providers. Switch anytime in-session with /model; any OpenAI-compatible endpoint (Ollama, vLLM, one-api relays) also works.

Permissions & Security

Three tiers, managed in-session with /permission:

Skipping prompts never disables the underlying protections:

Full rules: Sandbox & Permissions Guide. Report vulnerabilities privately via Security Advisories — see SECURITY.md; please do not open a public issue.

Documentation

English reference — CLI, Slash Commands & Configuration carries the complete English tables for command-line flags, subcommands, keybindings, slash commands, and config.json; the deep-dive manuals above are currently Chinese-only. Docs hub: docs/README.md.

For Developers

Node.js 24 · TypeScript strict (noUncheckedIndexedAccess) · tsup · node:test.

npm install
npm run typecheck    # tsc --noEmit
npm test             # node:test, full suite
npm run build        # tsup bundle
node dist/cli/entry.js

This repository is the sync projection of the development repo; the desktop app and some advanced implementations are not published here. Architecture map: AGENTS.md. Contribution process: CONTRIBUTING.md and EXTERNAL-PRS.md.

Community

Discussion — GitHub Discussions Bugs and feature requests — GitHub Issues; attaching tianshu logs --json speeds up triage Starport forum — tianshu.club: our self-hosted community for release discussion, tips and long-lived topics Discord — Tianshu Harness community QQ group — "TUI", group ID 1017892942 WeChat group — scan the QR code; valid for 7 days, ask in Discussions if expired Sponsorship is optional and never changes issue priority or feature scheduling.

WeChat

QQ

Sponsor

Contributors

The project creator and lead developer is @huiliyi37. The official website Tianshu-Official-Website was originally created and developed by @jiangsx496. External PRs are ported through the intake workflow and credited with Co-authored-by trailers; the full roster is maintained in CONTRIBUTORS.md.

License

Code in this repository is licensed under the Apache License, Version 2.0. Copyright 2025-2026 Tianshu Contributors.

Documentation exception: the following theoretical and empirical documents are licensed under CC BY-NC-ND 4.0 and are not covered by Apache 2.0 — you may share links with attribution, but may not adapt, excerpt, or use them commercially:

• CVM: From Shared Transformer Degradation to a Cognitive Runtime
• Empirical Impact of the CVM Runtime and Ecosystem on Agent Models

Acknowledgments

The desktop app's custom-wallpaper and per-surface glass design references dsh-wallpaper-engine (MIT). The implementation in Tianshu is original and contains no upstream code; see THIRD-PARTY-NOTICES.md for the design scope and full license text. Thanks to @elysia395, @YV3507, @yuxilao, and @oneincase for guidance as technical advisors on wallpaper-engine rendering.