Tachu

Production-grade agentic engine — the Harness that turns any LLM into a reliable, observable, production-ready Agent.

What is Tachu?

Tachu is a production-grade agentic engine — 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, production-capable 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 handles the hard parts — 9-phase execution pipeline, 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 packages: the zero-dependency engine core (@tachu/core), a production-quality official extensions library (@tachu/extensions), and a fully-featured CLI program (@tachu/cli) that doubles as the reference implementation.

Key Features

• 9-Phase Execution Pipeline — session management → safety → intent analysis → pre-check → planning → DAG validation → execution → result validation → output normalization; each phase is a typed, hookable stage
• 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
• Dual Provider Support — production-grade OpenAI and Anthropic adapters; configurable fallback order for zero-downtime provider switching
• 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 — every phase entry/exit, LLM call, tool call, retry, and fallback emits a structured EngineEvent; OTel and JSONL emitters included
• Production-Grade CLI — tachu chat / tachu run / tachu init with full parameter sets, streaming render, session persistence, and Ctrl+C cancellation
• 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 production-grade vector storage or use the built-in in-memory store for development

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

Tachu's four core abstractions are co-equal and orthogonal — each independently registered, independently activated, and composable across all engine phases.

All four share a common descriptor schema (Markdown + YAML frontmatter):

name: unique-name             # required, unique within type
description: ...              # natural language (used for semantic discovery)
tags: [tag1, tag2]            # for filtering and classification
trigger: { type: always }     # activation condition
requires:
  - { kind: tool, name: read-file }  # explicit dependency references

Dual-Plane Matching Model

Every core abstraction is activated through a two-phase process:

graph LR
    Input[Context Input] --> Discovery[Semantic Discovery Plane]
    Discovery --> Index[(Vector Index)]
    Index --> Candidates[Candidate Set]
    Candidates --> Gate[Deterministic Execution Gate]
    Gate -- scopes / whitelist / approval --> Execution[Execution Plane]

• Semantic discovery plane: description is vectorized on registration; at runtime, the current context is matched against the index to produce a candidate set
• Deterministic execution gate: final activation requires passing a deterministic gate (explicit references, whitelist checks, permission scopes, approval checks)

Rules and Skills pass through the gate freely (no side effects). Tools always pass through the full gate. Agents activate freely but all Tool calls they trigger still pass through the Tool gate.

Architecture Overview

Three-Layer Structure

Tachu is published as three layers:

graph TD
    subgraph "Business Layer"
        A[Business Rules / Domain Tools / Custom Adapters / Domain Skills / Agents / Plan Templates]
    end
    subgraph "Extensions Library — @tachu/extensions"
        B[OpenAI & Anthropic Adapters / 7 Common Tools / Terminal+File+Web Backends / Qdrant+LocalFs VectorStore / MCP Adapter / OTel+JSONL Emitters / 4 Common Rules]
    end
    subgraph "Engine Core — @tachu/core"
        C[Protocol Definitions / 9-Phase Pipeline / Lifecycle Hooks / Session / Memory / Safety / Model Router / Runtime State]
    end
    A --> B
    B --> C

9-Phase Execution Pipeline

Every request processed by the engine flows through exactly 9 phases:

graph TD
    Start([Business Request]) --> S1[Phase 1: Session Management]
    S1 --> S2[Phase 2: Minimum Safety Check]
    S2 --> S3[Phase 3: Intent Analysis — LLM]
    S3 -- simple --> S9[Phase 9: Output Normalization]
    S3 -- complex --> S4[Phase 4: Pre-Check]
    S4 --> S5[Phase 5: Task Planning]
    S5 -- Plan mode --> PlanLoop{Plan Review Loop}
    S5 -- Template match --> S6
    S5 -- Dynamic split --> S6[Phase 6: DAG Validation]
    PlanLoop -- confirmed --> S6
    S6 --> S7[Phase 7: Sub-task Execution]
    S7 --> S8[Phase 8: Result Validation — LLM]
    S8 -- pass --> S9
    S8 -- fail --> Retry{Retry / Re-plan}
    Retry -- within limits --> S5
    Retry -- exhausted --> S9
    S9 --> End([Output])

    style S2 fill:#ffeaa7,stroke:#fdcb6e
    style S7 fill:#dfe6e9,stroke:#b2bec3

Key pipeline properties:

• Full-path safety gating — Phase 2 runs on every request, including fast-path simple responses
• Context guard — Phase 3 decides whether session history is relevant; irrelevant history is not forwarded
• Three-strikes limit — Task-level retries are bounded at 3 (configurable); system-level retries at 2
• Last-message-wins — A new request on the same session cancels the current execution via AbortController

Installation

Tachu requires Bun as the runtime.

# Install the engine core
bun add @tachu/core

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

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

After global installation, verify with:

tachu --version

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 (TypeScript)

import { Engine } from '@tachu/core';
import { OpenAIProviderAdapter } from '@tachu/extensions/providers';
import { FileBackend, TerminalBackend } from '@tachu/extensions/backends';
import type { EngineConfig, InputEnvelope, ExecutionContext } from '@tachu/core';

const config: EngineConfig = {
  retry: { taskMaxRetries: 3, systemMaxRetries: 2 },
  planning: { planCount: 1, enableValidation: true },
  agent: { maxNestingDepth: 1 },
  context: { maxTokens: 8000, compressionThreshold: 0.8 },
  execution: { defaultTimeout: 120_000 },
  models: {
    capabilityMapping: {
      'high-reasoning': 'gpt-4o',
      'fast-cheap': 'gpt-4o-mini',
    },
    providerFallbackOrder: ['openai'],
  },
  safety: { maxInputSize: 1_000_000, maxRecursionDepth: 10 },
  hooks: { writeHookTimeout: 5000, failureBehavior: 'continue' },
  storage: {},
};

const engine = new Engine(config);

// Register a provider
engine.useProvider(new OpenAIProviderAdapter({ apiKey: process.env.OPENAI_API_KEY! }));

// Stream results
const input: InputEnvelope = {
  content: 'Write a TypeScript function that debounces async operations',
  metadata: { modality: 'text' },
};

const context: ExecutionContext = {
  requestId: crypto.randomUUID(),
  sessionId: 'session-001',
  traceId: crypto.randomUUID(),
  principal: { userId: 'user-001' },
  budget: { maxTokens: 20_000, maxDurationMs: 60_000 },
  scopes: ['read', 'write'],
};

for await (const chunk of engine.runStream(input, context)) {
  if (chunk.type === 'delta') process.stdout.write(chunk.content);
  if (chunk.type === 'done') console.log('\n\nCompleted:', chunk.output.status);
}

Package Layout

Package Summary

Dependency Relationship

graph LR
    cli["@tachu/cli"]
    extensions["@tachu/extensions"]
    core["@tachu/core"]

    cli --> extensions
    cli --> core
    extensions --> core

    style core fill:#74b9ff,stroke:#0984e3
    style extensions fill:#a29bfe,stroke:#6c5ce7
    style cli fill:#fd79a8,stroke:#e84393

Core Package Internal Structure

@tachu/core / src/
├── types/          # All TypeScript interfaces: descriptors, context, I/O, config
├── engine/         # Engine entry class, phase handlers, orchestrator, scheduler
├── registry/       # Registry: register/lookup/startup validation for all 4 abstractions
├── modules/        # 8 core modules (session, memory, runtime-state, model-router,
│                   #   provider, safety, observability, hooks)
├── prompt/         # PromptAssembler: token budgeting, KV-cache-friendly ordering
└── vector/         # VectorStore interface + built-in lightweight implementation

Providers & Integrations

LLM Providers

Provider fallback is configured via models.providerFallbackOrder. When a system-level error occurs (timeout, API error), the engine automatically switches to the next provider in the list without re-planning.

MCP (Model Context Protocol)

import { McpToolAdapter } from '@tachu/extensions/mcp';

const adapter = new McpToolAdapter();

// Connect via stdio (local process)
await adapter.connect('stdio://path/to/mcp-server');

// Connect via SSE (remote server)
await adapter.connect('http://localhost:3000/sse');

// MCP tools are automatically registered in the engine Registry
const tools = await adapter.listTools(); // returns ToolDescriptor[]
engine.registry.registerAll(tools);

The McpToolAdapter handles MCP session lifecycle, capability negotiation, and propagates engine cancellation signals to the MCP server.

Vector Stores

import { QdrantVectorStore } from '@tachu/extensions/vector';

const vectorStore = new QdrantVectorStore({
  url: 'http://localhost:6333',
  collectionName: 'tachu-descriptors',
});

engine.useVectorStore(vectorStore);

Observability Emitters

Execution Backends

Design Principles

Tachu is built on seven core engineering principles drawn from its architecture:

1. Dual-Plane Matching — All four core abstractions are discovered semantically (vector similarity) but activated deterministically (scopes, whitelist, approval). Semantic discovery is advisory; execution gates are authoritative.

2. Full-Path Safety Gating — The minimum safety check (Phase 2) runs on every request path, including the fast path for simple questions. Safety is never traded for performance.

3. Three-Strikes Retry Limit — Both the task-level retry loop and the system-level retry loop are strictly bounded. Unlimited retry is not allowed. When limits are exhausted, the engine outputs step-level completion status rather than a generic failure.

4. KV-Cache-Friendly Prompt Assembly — The System Prompt is assembled in a stable order (hard rules → soft preferences → skills → tool definitions) so that the prefix remains unchanged across turns, maximizing KV cache reuse and reducing LLM cost.

5. Last-Message-Wins Cancellation — When a new message arrives in the same session, the current execution is cancelled via AbortController and the new input is processed in the existing context. This guarantees coherent context while avoiding stale work.

6. Engine Agnostic of Business Permissions — The engine only evaluates coarse-grained scopes from the execution context at the Tool gate. Fine-grained business authorization is the responsibility of Tool implementations or dedicated authorization Tools.

7. Fail-Closed Safety Baseline — Loop protection, budget circuit-breaking, and basic input validation are hardwired into the engine core and cannot be disabled by configuration. Even with a completely empty business configuration, the engine does not run unconstrained.

Configuration

The engine is configured via a tachu.config.ts file at the project root (generated by tachu init):

import type { EngineConfig } from '@tachu/core';

const config: EngineConfig = {
  // Descriptor registry
  registry: {
    descriptorRoot: '.tachu',          // root directory for Rules/Skills/Tools/Agents
  },

  // Runtime behaviour
  runtime: {
    planMode: false,                   // enable Plan mode by default
    maxConcurrency: 4,                 // max parallel sub-tasks
  },

  // Context window & memory
  memory: {
    maxTokens: 8000,                   // context window token limit
    compressionThreshold: 0.8,         // trigger compression at 80% capacity
    archivePath: '.tachu/archive.jsonl',
    vectorIndexLimit: 10000,           // max entries in the built-in vector index
  },

  // Budget constraints
  budget: {
    maxTokens: 50000,                  // total token budget per execution
    maxToolCalls: 50,                  // max tool calls per execution
    maxWallTimeMs: 300000,             // 5 minutes wall-time limit
  },

  // Safety baseline (hardwired minimum; add business policies via hooks)
  safety: {
    maxInputSize: 1_000_000,           // bytes
    maxRecursionDepth: 10,
    enablePromptInjectionCheck: true,
  },

  // Model routing
  models: {
    capabilityMapping: {
      'high-reasoning': { provider: 'openai', model: 'gpt-4o' },
      'fast-cheap':     { provider: 'openai', model: 'gpt-4o-mini' },
      'vision':         { provider: 'openai', model: 'gpt-4o' },
    },
    providerFallbackOrder: ['openai', 'anthropic'],
  },

  // Observability
  observability: {
    emitter: 'jsonl',
    jsonlPath: '.tachu/events.jsonl',
  },
};

export default config;

All fields have sensible defaults. tachu init generates this file pre-filled for your chosen provider.

CLI Reference

tachu init

Initialize a new Tachu project workspace.

tachu init [options]

Options:
  --template <name>    Scaffold template: minimal | full  (default: minimal)
  --force              Overwrite existing files without prompting
  --path <dir>         Target directory                   (default: CWD)
  --provider <name>    Default provider: openai | anthropic | mock  (default: mock)
  --no-examples        Skip generating example rule/tool descriptors
  -h, --help           Show help

Generates .tachu/ directory skeleton + tachu.config.ts + .gitignore entries.

tachu run <prompt>

Execute a single prompt and stream the result to stdout.

tachu run <prompt> [options]

Arguments:
  <prompt>             The prompt text (or pipe via stdin)

Options:
  --session <id>       Use a specific session ID
  --resume             Resume the most recent session
  --model <name>       Override the high-reasoning model
  --provider <name>    Override the default provider
  --input <file>       Read prompt from a file
  --json               Parse prompt as JSON (structured input)
  --output <fmt>       Output format: text | json | markdown  (default: text)
  --no-validation      Skip Phase 8 result validation
  --plan-mode          Enable Plan mode (pause after Phase 5 for approval)
  --verbose, -v        Verbose output (phase transitions, LLM call details)
  --no-color           Disable ANSI color output (also respects NO_COLOR env var)
  --timeout <ms>       Wall-time limit (overrides budget.maxWallTimeMs)
  -h, --help           Show help

tachu chat

Start an interactive multi-turn chat session.

tachu chat [options]

Options:
  --session <id>       Use a specific session ID
  --resume             Resume the most recent session
  --history            List all sessions and exit (no interactive prompt)
  --export <file>      Export a session to Markdown and exit
  --model <name>       Override the high-reasoning model
  --provider <name>    Override the default provider
  --plan-mode          Enable Plan mode
  --verbose, -v        Verbose output
  --no-color           Disable color output
  -h, --help           Show help

Built-in interactive commands (prefix with /):

Ctrl+C behaviour:

• First press: cancel the current LLM/Tool call (return to prompt, session intact)
• Second press within 1 second: save session and exit gracefully
• Third press: force exit

Extension Guide

Tachu is extended by creating Markdown descriptor files in the .tachu/ directory. No code changes are required for Rules, Skills, and Tools — only Agents need executable functions registered separately.

Custom Rule

<!-- .tachu/rules/no-external-calls.md -->
---
name: no-external-calls
description: Prevent the agent from making external network calls without explicit approval
type: rule
scope: [execution]
tags: [security, network]
---

Do not make HTTP requests, DNS lookups, or any other external network calls unless
the tool being invoked has `requiresApproval: true` and the user has confirmed.

Custom Skill

<!-- .tachu/skills/git-workflow/SKILL.md -->
---
name: git-workflow
description: Git branching, commit, and PR workflow knowledge for this repository
tags: [development, git]
requires:
  - { kind: tool, name: run-command }
---

## Git Workflow

This repository follows trunk-based development with short-lived feature branches.

### Branch Naming
- Feature: `feat/<ticket>-<short-desc>`
- Fix: `fix/<ticket>-<short-desc>`

### Commit Convention
Use Conventional Commits: `type(scope): subject`
...

Custom Tool

<!-- .tachu/tools/query-db.md -->
---
name: query-db
description: Execute a read-only SQL query against the application database
sideEffect: readonly
idempotent: true
requiresApproval: false
timeout: 10000
inputSchema:
  type: object
  properties:
    sql:   { type: string, description: "SQL SELECT statement" }
    limit: { type: number, description: "Max rows to return", default: 100 }
  required: [sql]
execute: queryDatabase
---

Executes a parameterized read-only SQL query. Results are returned as a JSON array.

Register the execution function in your engine-factory.ts:

engine.registry.registerExecutor('queryDatabase', async (input, ctx) => {
  const { sql, limit = 100 } = input as { sql: string; limit?: number };
  return db.query(sql).limit(limit).execute();
});

Custom Agent

<!-- .tachu/agents/code-reviewer.md -->
---
name: code-reviewer
description: Reviews pull request diffs and produces structured code review feedback
sideEffect: readonly
idempotent: true
requiresApproval: false
timeout: 180000
maxDepth: 1
availableTools: [read-file, search-code, run-command]
---

You are a careful code reviewer. When given a diff or a set of files:
1. Understand the intent of the change
2. Review for correctness, clarity, security, and performance
3. Produce a structured review with severity levels: critical / major / minor / nit

Observability & Safety

OpenTelemetry Integration

Every engine event maps to an OTel span, enabling full distributed tracing:

import { OtelEmitter } from '@tachu/extensions/emitters';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new SimpleSpanProcessor(new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }))
);
provider.register();

const engine = new Engine({
  ...config,
  // The OtelEmitter consumes EngineEvents and creates OTel spans
});
engine.useEmitter(new OtelEmitter());

Events emitted for every request:

Safety Module

The Safety module operates in two independent layers:

Engine baseline (non-disableable):

• Input size enforcement (maxInputSize bytes)
• Recursion depth limit (maxRecursionDepth)
• Budget circuit-breaker (terminates immediately when token/time budget is exhausted)

Business-injectable policies (via hooks or configuration):

• Prompt injection detection (enablePromptInjectionCheck: true)
• Sensitive operation interception (register via engine.registerSafetyPolicy())
• Output content compliance checks

// Register a custom safety policy
engine.registerSafetyPolicy(async (input, ctx) => {
  if (containsPersonalData(input.content)) {
    return { passed: false, violations: [{ type: 'pii', message: 'PII detected in input' }] };
  }
  return { passed: true, violations: [] };
});

Roadmap

v1.0.0 — Delivered

• @tachu/core: Engine, 9-phase pipeline, 8 modules, Registry, PromptAssembler, InMemoryVectorStore, full error taxonomy
• @tachu/extensions: OpenAI + Anthropic providers, 7 tools, Terminal/File/Web backends, LocalFs + Qdrant VectorStore, MCP stdio+SSE adapters, OTel+JSONL emitters, 4 common rules
• @tachu/cli: tachu init / tachu run / tachu chat with full parameter sets, session persistence, streaming renderer
• Test suite (≥80% line coverage) and performance benchmarks
• English and Chinese READMEs

v1.x — Planned

• Additional VectorStore adapters (Pinecone, pgvector)
• Additional Provider adapters (Google Gemini, Mistral)
• Additional MCP tool integrations
• More built-in compression strategies
• Structured Plan template library

v2 — Vision

• Multi-agent collaboration (agent-to-agent communication protocol)
• Persistent long-term memory across deployment restarts
• Fine-grained budget allocation per sub-task

Contributing

Requirements

• Bun >= 1.1.0
• TypeScript 5.x (provided via dev dependencies)

Development Workflow

# Clone and install
git clone https://github.com/dangaogit/tachu
cd tachu
bun install

# Run all tests
bun test

# Type check
bun run typecheck

# Build all packages
bun run build

# Run a specific package's tests
bun test --filter packages/core

Project Conventions

• File names: kebab-case
• Classes and types: PascalCase
• Functions and variables: camelCase
• Constants: SCREAMING_SNAKE_CASE
• All public APIs must have TSDoc comments (@param, @returns, @throws, @example)
• Test files co-located with source: *.test.ts
• Integration tests under __tests__/

Pull requests require:

• All tests passing (bun test)
• Zero TypeScript errors (bun run typecheck)
• Coverage thresholds met (≥80% line, ≥70% branch)
• TSDoc on any new public API

See CONTRIBUTING.md for full guidelines.

Benchmarks

Performance baselines are established in packages/core/benchmarks/ and run with bun test:

Benchmarks serve as regression baselines; there are no minimum performance requirements for v1.

Documentation

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.