huiliyi37/Tianshu-harness

Tianshu Harness – A TypeScript‑based AI coding‑assistant runtime

What it is – Tianshu (天枢) is an open‑source AI agent platform written in TypeScript that lets large‑language‑model (LLM) providers act as coding partners rather than simple question‑answer tools. The same core engine powers both a terminal‑based TUI (called rivet) and a cross‑platform desktop GUI built with Tauri, so you can work in the console you prefer without losing any capabilities.

Key ideas

• Cognitive Virtual Machine (CVM) – 72 runtime hooks are inserted between the model’s output and the actual file‑system or shell actions. The CVM observes, validates and can correct the model’s behaviour (e.g., refusing to overwrite an existing file, asking for clarification, or rejecting unsafe commands). The README includes an A/B study showing a jump from 4/5 to 5/5 task‑completion when CVM is enabled.
• Multi‑agent orchestration – Commands prefixed with /scout, /team, /council, /galaxy let you run lightweight read‑only agents, parallel workers, or full‑blown collaborative “councils” that execute complex tasks in waves and verify each step.
• Unified project memory – All knowledge the agent gathers is stored in .rivet/knowledge/memory.jsonl. Only governance‑type memories are automatically injected into new tasks, preventing old context from hijacking fresh work.
• Prefix‑cache engine – Designed for DeepSeek V4, the system freezes the system prompt and tool definitions at the start of a session and only appends a tiny incremental “appendix” each turn. This yields a 95‑99 % cache‑hit rate for long conversations, dramatically cutting token costs.
• Zen mode – New sessions start with a read‑only toolset; the model must explicitly “unlock” the full tool surface, which avoids unnecessary prompt bloat and keeps the cache stable.
• Plan mode & Star‑domains – The agent can switch cognitive “domains” (星域) such as 启明, 天权, 天梁, etc., each with its own system prompt, tool whitelist and decision thresholds. In Plan mode the model first produces a structured plan, waits for user approval, then executes the plan in controlled waves.

Supported platforms

• macOS (Apple Silicon & Intel) – .dmg
• Windows 10/11 – .exe (requires WebView2 Runtime ≥ 120)
• Linux – AppImage (glibc ≥ 2.35, X11 recommended)
• Android/Termux – via a proot‑distro Ubuntu container (experimental)

Installation shortcuts

Method	Command (macOS/Linux)	Windows
One‑click script	bash <(curl -fsSL https://raw.githubusercontent.com/huili37/Tianshu-Tui/main/scripts/install-tui.sh)	`powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/huili37/Tianshu-Tui/main/scripts/install-tui.ps1
npm global	npm install -g tianshu-tui && rivet	same
Desktop binary	Download from the Releases page and run the installer.
Build from source	git clone https://github.com/huili37/Tianshu-Tui.git && npm install && npm run build && npm start

Basic usage

rivet                     # start the interactive TUI / GUI
rivet -p "解释 src/agent/loop.ts"          # one‑off prompt, plain text output
rivet -p "列出所有 TODO" --json           # JSON result for scripts
rivet --goal "修复所有类型错误" --budget 50   # autonomous goal‑driven mode (max 50 turns)

The CLI also offers sub‑commands for configuration (rivet config), session management (rivet sessions), logs, and a side‑car HTTP/SSE server (rivet serve).

When would you use it?

• Continuous coding assistance – Let the model read, edit, refactor, and test code across multiple turns without you having to copy‑paste prompts.
• Safety‑critical automation – The CVM hooks act as a guardrail, preventing destructive file operations and forcing the model to justify actions.
• Team‑style AI collaboration – Use /team or /council to run several specialized agents (e.g., a planner, a reviewer, a tester) in parallel and merge their outputs.
• Cost‑sensitive long sessions – The prefix‑cache engine keeps token usage low for models that charge per input token (DeepSeek V4).
• Structured delivery pipelines – Plan mode lets you generate a written plan, get explicit approval, then have the agent execute the plan step‑by‑step, producing a traceable audit log.

Documentation & community

• Official website: https://tianshuharness.com
• Chinese README (default) with English, Japanese and Korean translations.
• Detailed user guide, sandbox‑permission model, provider configuration, and engineering‑metrics docs are linked from the main README.
• The project is Apache 2.0 licensed and ships with a massive test suite (≈ 16 k test cases, test‑to‑code line ratio ~1:1) to ensure reliability.

Bottom line – Tianshu Harness is a full‑featured, cross‑environment AI coding assistant that adds a safety‑oriented runtime layer, multi‑agent orchestration, and aggressive token‑cost optimisation on top of LLMs. It is suitable for developers who want an AI partner that can reliably perform end‑to‑end code changes while keeping the process observable and controllable.