Tachu

An agentic engine under active development — the Harness that aims to turn any LLM into a reliable, observable Agent.

Project Status — Release Candidate. The engine follows a loop spine: turnStart guard → deterministic tool-routing prep → the tool-use deep single agentic loop (the only multi-step LLM decision surface) → turnStop validation → output normalization. Registry, prompt assembler, CLI, OpenAI / Anthropic / Qwen / Gemini adapters, MCP adapters, vector stores and observability emitters are wired up and tested. tool-routing makes no LLM call and always constructs a single tool-use task; inside the loop the LLM decides whether to call tools, dispatch a read-only sub-agent, or answer directly; validation runs deterministic rules (with optional semantic judge) as a turnStop guard via the unified HookAction seam. Runtime provider fallback and semantic judge production hardening remain post-rc work. Install via the @rc dist-tag.

What is Tachu?

Tachu aims to be an agentic engine you can build a real product on — not a toy demo, not a thin wrapper. It is the Harness in the equation Agent = Model + Harness: it provides the structural skeleton (protocol, lifecycle, safety, memory, orchestration) so that any LLM becomes a reliable, observable Agent.

The engine is intentionally domain-agnostic: it knows nothing about your business logic, your users, or your domain vocabulary. Instead, it defines a small set of core abstractions (Rules, Skills, Tools, Agents) through which your business fills in all the intelligence. Tachu is designed to handle the hard parts — a deep single agentic loop with a loop-lifecycle guard surface, dual-plane semantic matching, context window management, token-precise prompt assembly, structured retry/fallback, cancellation propagation, and end-to-end observability.

Tachu ships as a Bun-native TypeScript monorepo with three published packages — the zero-dependency engine core (@tachu/core), an official extensions library (@tachu/extensions), and a fully-featured CLI program (@tachu/cli) that doubles as the reference implementation — plus @tachu/host-defaults for shared CLI/embedded host wiring, and an optional private sidecar package (@tachu/web-fetch-server) for remote browser-backed web tools.

Project Status

Current release: 1.0.0-rc.13 on the rc dist-tag.

Version terminology: The product line is Tachu v1. Release candidates are stabilization builds for 1.0.0, not a separate framework generation. HTTP paths like /v1/extract are API versions only. See detailed-design § version glossary.

This is a release candidate. The table below is a readability index only; runtime behavior, defaults, and edge cases are authoritative in the cited source files and tests.

Legend: ✅ implemented and tested · 🟡 stub / placeholder present, real implementation in progress · 🔴 not yet started.

Key Features

• Deep Single Agentic Loop — turnStart → safety → deterministic tool-routing → the tool-use loop → turnStop validation → output; every request follows the same loop spine with Rules / Hooks / Observability / budget accounting mounted on loop-lifecycle events; multi-step LLM decisions happen only inside the loop (see ADR-0006)
• Loop-Lifecycle Guard Surface — 9 hook points (turnStart/preLLM/postLLM/preToolUse/postToolUse/turnStop/preSubagent/postSubagent/preCompact) replace the old per-phase hooks; pre/post guards at turnStart/turnStop use the unified HookAction seam (guard/finding/mutate/approve/deny, fail-closed) with built-in SafetyModule baseline and Result Validation
• Subagent Dispatch — the loop LLM can spawn a read-only sub-agent via the built-in dispatch_agent tool (Single-Writer Rule, summary-only contract, maxDepth defaults to 1)
• Dual-Plane Matching — semantic discovery (vector similarity) + deterministic execution gate (scopes, whitelist, approval) for every Rule, Skill, Tool, and Agent
• Four Core Abstractions — declare Rules, Skills, Tools, and Agents as Markdown + YAML frontmatter descriptors; the engine resolves, activates, and orchestrates them automatically
• OpenAI & Anthropic Adapters — streaming, function calling, configurable baseURL / organization / timeoutMs; works with Azure OpenAI, LiteLLM, OpenRouter, or any self-hosted gateway
• MCP Integration — connect any MCP server (stdio or SSE) via McpToolAdapter; MCP tools become first-class engine Tools
• Token-Precise Prompt Assembly — tiktoken-based exact token counting; KV-cache-friendly prompt layout; automatic context compression (Head-Middle-Tail strategy)
• Structured Memory — session context window with configurable limits; archive-before-summarize guarantee; vector recall for long-term memory
• OpenTelemetry Observability — loop-spine vocabulary first: loop_step_enter/loop_step_exit (in-turn module boundaries), flat per-step loop events (tool_loop_step_* / tool_call_* / llm_call_* / hook_fired) with parentStepId correlation; retry and fallback all emit structured EngineEvents; OTel and JSONL emitters included
• Interactive CLI — tachu chat / tachu run / tachu init with full parameter sets, streaming render, session persistence, and Ctrl+C cancellation
• Terminal Markdown rendering — final assistant replies are rendered via marked + marked-terminal + cli-highlight; headings, bold / italic, lists, block quotes, links, tables and fenced code blocks (with syntax highlighting) are all supported. Automatically disabled under NO_COLOR / non-TTY / --no-color; explicitly controllable with --markdown / --no-markdown on tachu run.
• Fail-Closed Safety Baseline — loop protection, budget circuit-breaker, and basic input validation are hardwired into the engine and cannot be disabled
• Qdrant & LocalFs Vector Stores — plug in Qdrant for multi-process deployments or use the file-backed store for local/single-process setups

Vision

太初有道，万物之始。以声明式描述符创造 Agent 万物。 In the beginning was the Tao — all things arise from it. With declarative descriptors, conjure Agent capability from nothing.

The long-term vision of Tachu is a universal Agent framework where the engine provides the skeleton and business provides the blood: any organization can build production-grade agentic systems on top of a stable, observable, auditable foundation without re-solving the hard problems of safety, context management, retry logic, and multi-provider orchestration every time.

Tachu is built around three convictions:

1. The Harness is the hard part. Model intelligence is commoditized; reliable orchestration is not. Tachu invests deeply in the engine infrastructure so application developers can focus on domain logic.
2. Declaration over implementation. Rules, Skills, Tools, and Agents are declared as plain Markdown files. The engine resolves them. No framework-specific boilerplate.
3. Observable by default. Every internal event is structured and emittable. Production systems need complete traces — Tachu provides them without opt-in instrumentation.

Core Abstractions

Rules, Skills, Tools, and Agents are Markdown + YAML descriptors. Semantic discovery proposes candidates; deterministic gates authorize execution (especially Tools).

Details: Overview · abstractions · Dual-plane matching.

Architecture (summary)

Every request follows the loop spine: turnStart guard → deterministic tool-routing → the built-in tool-use deep single agentic loop (the only multi-step LLM surface) → turnStop validation → output. Cross-cutting concerns (Rules / Hooks / budget / observability) mount on 9 loop-lifecycle events, not the old phase pipeline.

Details: Pipeline phases · Overview design.

Installation

Tachu requires Bun as the runtime.

Install via the @rc dist-tag (or an exact version) until Tachu reaches stable.

# Install the engine core
bun add @tachu/core@rc

# Install the extensions library (providers, tools, backends, vector stores)
bun add @tachu/extensions@rc

# Install and use the CLI globally
bun add -g @tachu/cli@rc

After global installation, verify with:

tachu --version   # expect 1.0.0-rc.13 or newer

Quick Start

CLI

# 1. Initialize a new project workspace
tachu init --template minimal --provider openai

# 2. Set your API key (used by the OpenAI provider adapter)
export OPENAI_API_KEY=sk-...

# 3. Run a single prompt
tachu run "Summarize the last 5 git commits in this repository"

# 4. Start an interactive chat session
tachu chat

# Resume the most recent session
tachu chat --resume

Programmatic embedding: see Configuration and @tachu/host-defaults.

Documentation

Web Fetch Server (optional)

For browser-backed web-fetch / web-search, run the private sidecar — see packages/web-fetch-server/README.md.

bun run dev:server:install-browser
bun run dev:server

License

Apache License 2.0 © 2026 Tachu Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. A copy of the License is included in the LICENSE file or may be obtained at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.