Intro

Tuff is a Rust-powered CLI for managing agent capabilities such as skills, tools, hooks, and workflows. It provides lifecycle tracking, drift detection, baseline diffs, and merge-aware updates. It works with Codex, Claude Code, Cursor, GitHub Copilot, and any agent harness that follows the open Agents standard.

Why Tuff exists

Agent coding tools increasingly depend on capabilities: skills that teach an agent how to work in a project, tools it can call, hooks that run at key events, and workflows that compose them together. Together, they define how an agent works.

Today these capabilities are either siloed on one engineer’s machine, invisible to the rest of the team, or copied by hand across projects and left to drift silently.

Tuff treats each capability as something that can be installed, tracked, updated, and checked for drift over time.
Tuff manages the lifecycle and structure around a capability, while the capability content itself can stay with the team or project that owns it.

These are common situations teams encounter as capabilities are shared across repositories, coding harnesses, and developer machines.

Problem context	What changes with Tuff
A skill gets copied between projects and slowly diverges.	Tuff records a baseline, so edits show up as drift instead of becoming invisible forks.
A capability file shows up in the project with no record of its origin, author, or version.	The lockfile records source and version metadata, so provenance is explicit.
Agent behavior differs across machines and nobody knows why.	Project capabilities are versioned in the repo for a shared baseline; personal overrides stay in global scope.
A skill built for Claude Code is useless in Cursor or Codex.	Tuff maps the same managed capability into each supported harness through adapters.
An upstream fix arrives after the local copy has been edited.	Updates use baseline, local, and upstream state together, so local customization is preserved where possible.
A new project starts by copying whatever someone remembers.	Setup becomes a repeatable CLI step instead of tribal knowledge.

Capabilities

Skills Reusable instructions that shape how an agent works.

Tools Executable capabilities with typed parameters and clear contracts.

Hooks Event-driven automation that runs at key points in a task.

Workflows Composable patterns that bundle skills, tools, and hooks.

All four types share the same lifecycle: install, baseline, drift detection, diff, and merge-aware update through tuff create, tuff add, tuff update, and tuff diff.

Features

Lifecycle management

Install from anywhere: local directories, git repositories, or existing agent files already in .agents/ or .claude/ with tuff add.
Drift detection: every install records a pristine baseline. Any edit to an agent file becomes visible as modified in tuff list.
Three-way merge updates: for git-sourced capabilities, tuff update merges upstream changes with your local edits using diffy. Conflicts are reported with exact file paths and are never silently overwritten.

Multi-harness output

Open Agents (.agents/): serves Codex, Cursor, OpenCode, GitHub Copilot, Gemini CLI, Roo, Cline, Windsurf. Skills: SKILL.md, tools: automatic MCP server registration, hooks: TOML config, workflows: dependency manifests.
Claude Code (.claude/): native directory format with JSON tool configs and MCP auto-registration.

Scope and team workflows

Project scope: tuff.lock is committed to the repo; project preferences use tuff.config.json.
Global scope: Tuff’s user config/state/cache directories hold personal capabilities and caches.
Project always wins when both exist. tuff status flags shadowed globals.

CI-ready validation

tuff check exits 1 on any failure: drift, missing files, invalid state.
tuff check --json for machine-readable CI output.
Copy-paste GitHub Actions workflow in the CLI reference.