Tau

Imported from Z-Yun-H/Tau (AGENTS.md). Install upstream with npx skills add Z-Yun-H/Tau. Copyright stays with the author.

AGENTS.md — Tau

Read this first. This file is the entry point for AI coding agents (Claude Code, Codex, Cursor, Copilot Workspace, ...) working on the Tau repository. Humans are welcome too — it doubles as the fastest tour of the codebase.

MANDATORY for AI agents: besides this file, read AGENTS/collaboration.md — the AI collaboration operating norms (issue→PR flow, AI labeling, changelog fragments, merge policy). It is binding; violating it is a process failure even when the code itself is correct.

Per-tool skill routing: for the designated SKILL.md of each dev tool (build / test / release / skills / WebUI / tools / AI / plugins / TUI), start from the root SKILL.md router.

Detailed rulebooks live in AGENTS/. The split: this file = what you must know in 60 seconds; AGENTS = what you need when you actually touch a subsystem.

What is Tau

Tau is an AI-powered unified terminal assistant: natural language in, safe commands out. One tau binary with:

• tau ask "<intent>" — AI provider drafts a JSON plan → deterministic safety review → interactive confirmation → execution → history
• tau file | sys | net | text — built-in tool modules (dual-use: human CLI + the catalog the AI planner plans against)
• tau skill — SKILL.md command packs (bundled / user / workspace scopes)
• tau plugin — MCP servers as tool sources (dsh, VS Code, filesystem, ...)
• tau tui / tau-tui — interactive terminal session over the same pipeline
• tau web / tau-web — localhost web UI over the same pipeline
• tau history | alias | config — session memory and configuration

Non-goals: shell replacement, remote/network-exposed daemon, secret management. (The TUI and WebUI are front doors into the same reviewed pipeline, not independent execution paths.)

Golden rules for agents

1. The safety reviewer is sacred. Never weaken packages/engine/src/safety.ts (deny list, risk escalation, step caps) to make a feature easier. If a test around it fails, fix the feature, not the reviewer.
2. The AI never grades itself. Any code path that executes an AI-generated plan must go through runPlan() in packages/engine/src/session.ts. No bypasses.
3. Dry-run by default for anything that mutates (file.rename, text.replace). execute:true is always an explicit, visible choice.
4. No new runtime dependencies without updating AGENTS/architecture.md and justifying it in the PR description. Runtime deps live in the package that actually imports them: commander (@tau/cli; type-only devDep in @tau/tui), chalk (@tau/ui), yaml+zod (@tau/skills), zod (@tau/ai). The only sanctioned exceptions are optionalDependencies (the MCP SDK @modelcontextprotocol/sdk for plugins and the DeepSeek Harness seam @deepseek-ai/dsh-llm for the deepseek provider; other provider SDKs stay out of package.json entirely) — they must be dynamically imported, never bundled, and the app must degrade gracefully when they are absent.
5. Bilingual docs: user-facing README changes go to both README.md (English) and README.zh-CN.md (Chinese). AGENTS.md/AGENTS stay English.
6. Workspace hygiene: packages import each other only through the declared @tau/* workspace:* dependencies (never relative paths across packages, never deep imports like @tau/core/src/...). Every package's public API is its src/index.ts barrel. Vitest aliases @tau/* to source; runtime uses each package's dist after pnpm build.
7. Run the gates before you claim done: pnpm lint && pnpm typecheck && pnpm test — and report the results in the PR body (AI-gate: trailer + "How it was tested"). CI failures get root-caused, never bypassed.
8. Log each working day to changelog/: append a per-day file changelog/YYYY-MM-DD.md (summary, type, Issue/PR refs, impact scope); CHANGELOG.md stays the release-level summary distilled from it. Spec v2 (daily batch layer + Keep-a-Changelog release layer + the distillation rules): AGENTS/collaboration.md §8.
9. Compound requests get decomposed, not squeezed. A single request spanning multiple change types or subsystems MUST be split into independent, individually reviewable units — one Issue per unit, one PR per Issue — with the decomposition plan published for the maintainer BEFORE implementation (see AGENTS/collaboration.md §3 "compound-request decomposition"). Order: norms/docs → refactor → feature.
10. Large refactors ship as a versioned release via unified merge. When a compound request amounts to a large refactor (three or more subsystems, or a version release as its deliverable), the decomposed unit PRs all target an integration branch release/vX.Y.Z-<slug> (not main) and merge into it sequentially (CI-gated, rebased), a release unit bumps the workspace version + archives the changelog last, and ONE unified PR (integration branch → main) carries the release notes and the full unit index. The unified PR is merged by a HUMAN maintainer — an AI never merges it (see AGENTS/collaboration.md §3 "unified merge & versioned release").

Command map

Repo map — pnpm monorepo

app/                        UI layer (thin front doors, no engine logic)
  cli/src/index.ts          bin `tau`: builds commander program; heavy families (ask/tui/web)
                            and @tau/ai load LAZILY in their actions; skills scan runs in ask/ensureCatalog
  cli/src/<family>.ts       thin commander wiring per command family (ask, file, sys, ...)
  tui/src/index.ts          bin `tau-tui`: interactive REPL (slash commands + intents)
  webui/src/server.ts       zero-dependency HTTP API over the engine; Vue 3 + UnoCSS client in webui/client/ (vite)
packages/                   engine layer (each with a public src/index.ts barrel)
  core/src/types.ts         shared domain vocabulary (Plan, ToolDefinition, RiskLevel...)
  core/src/config/          TAU_HOME paths, config store, JSONL history
  engine/src/               session pipeline (runPlan), safety reviewer, executor
  ai/src/                   provider registry + prompt builder + plan schema + models
  ai/src/providers/         mock | ollama | openai | deepseek | zai
  tools/src/                registry + file/sys/net/text tool modules (+ bootstrap.ts)
  plugins/src/              MCP client seam, plugin manager, tool registration
  skills/src/               SKILL.md loader, schema, manager + bundled asset paths
  skills/bundled/           bundled skills (git-helper, docker-helper)
  skills/templates/         `tau skill new` scaffold source
  agent/src/                catalog prep + intent->plan pipeline shared by all UIs
  ui/src/                   chalk theme, confirm prompt, list picker
tests                       live INSIDE each package: <pkg>/tests/*.test.ts
SKILL.md                    root dev-tool skill router (top of the SKILL.md read chain)
AGENTS/                     deep-dive rulebooks for agents (see below)
.claude/skills/             root dev-workflow skills for coding agents; package/app
                            tool-layer skills live at packages/<pkg>/SKILL.md, app/<app>/SKILL.md
changelog/                  daily AI work logs (YYYY-MM-DD.md; AGENTS/collaboration.md §8)
scripts/screenshot/         run-screenshot tooling (term-svg.mjs pty→SVG renderer; per-app
                            docs/screenshots/ hold the committed captures + regeneration docs)
docs/                       human-facing deep dives (architecture, safety, skills, plugins)

AGENTS index — read the relevant file BEFORE touching that subsystem

Change checklist (every PR)

• pnpm lint && pnpm typecheck && pnpm test green — results reported in the PR body
• Compound request? → decomposed into one-Issue-one-PR units and the decomposition plan published before implementation (golden rule 9)
• Large refactor / release batch? → unit PRs target the release/vX.Y.Z-* integration branch, a release unit bumps versions last, and ONE unified human-merged PR carries the release (golden rule 10)
• New behavior has tests (see AGENTS/testing.md for patterns)
• New user-facing flags/commands documented in both READMEs
• Tool added? → registered in packages/tools/src/<module>.ts, catalog renders, risk level reviewed, docs table updated
• Skill-related change? → AGENTS/skills.md checklist
• Plugin-related change? → AGENTS/plugins.md checklist
• docs/safety.md still truthful after your change
• CHANGELOG.md entry under Unreleased AND the working day's changelog/YYYY-MM-DD.md written (summary / type / Issue-PR refs / impact)
• Dead code & needless hardcoding cleaned in every module you touch (behavior unchanged; large cleanups go standalone)
• Docs synced with root-vs-subpackage responsibilities respected (root: README×2, CHANGELOG.md, AGENTS.md; subpackage: package README, docs/, AGENTS/, .claude/skills/) — or state why no doc changed
• AGENTS.md/AGENTS/ + SKILL.md checked and updated when behavior rules or executable-skill workflows changed
• Tech selection unchanged (new framework/lib/tool needs an approved Issue first)
• AI-authored? → PR body notes "此 PR 由 AI 生成"；every AI commit carries the AI-Generated: prefix line AND the AI-declaration: block, presented to the human BEFORE committing (AGENTS/collaboration.md, AGENTS/release.md)
• Commit author/committer email = the maintainer account's official noreply address (88868011+Z-Yun-H@users.noreply.github.com) — never an invented <name>@users.noreply.github.com, GitHub links that to the unrelated user named <name> (AGENTS/release.md "Commit author identity")
• PR title tagged [REFACTOR] / [ARCHITECTURE] when applicable; AI never merges — human review required

Commit style

Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:. Scope optional: feat(ask): support streaming plans.

Flow by change type: features / refactors / architecture changes need an Issue first (Closes #N in the PR body); simple, unambiguous fixes may be committed directly on a branch — main is protected, so every change still lands through a PR. One PR = one Issue; unrelated changes never mix.

When unsure

• Prefer the boring solution.
• Prefer read-only tools over shell.
• Prefer asking in the PR over guessing silently.