tack
A stack-agnostic harness for AI-assisted development.
The AI does the thinking. tack makes it consistent, safe, cheaper, automatic, and trackable,
in any language, for new projects and existing ones.
Most agent setups tell the AI how to behave. tack checks that it did.
$ tack loop "make the failing tests in tests/test_textutils.py pass"
[tack] iteration 1/3: running agent
│ **The bug:** `slugify` in `textutils.py` only lowercased the text and turned each space into a hyphen.
│ **The fix:** it now lowercases the text, keeps only the runs of letters and digits,
│ and joins them with single hyphens.
[tack] iteration 1/3: verifying
PASS 0.0s demo:format uv run ruff format --check .
PASS 0.0s demo:lint uv run ruff check .
PASS 0.2s demo:test uv run pytest -q
[tack] loop PASSED: 1 iteration(s), 40s
[tack] log: .tack/runs/20261121T054631Z-make-the-failing-tests-in-tests-test-tex.jsonl
A real run with Claude Code on a project with a buggy function. If a check had failed, tack would have fed the failure output back and tried again.
Why not just use a plain AI?
| A plain AI coding agent... | With tack |
|---|---|
| Says "done" when it thinks it's done | Can't finish until the project's real checks pass (a Stop hook runs them) |
| Forgets everything between sessions | PROGRESS.md is shown at the start of every session, and Claude can't finish real work without updating it |
| Forgets which skill to use | A playbook routes it: "landing page" → your design skill, automatically |
Usually avoids rm -rf /, force-pushes, and editing .env |
Can't do them. Guard hooks block them before they run |
| Burns tokens formatting files and figuring out how to run your tests | Formatting runs on save; one contract tells every agent how to verify |
| Follows whatever conventions you remember to repeat | Same rules for every agent and every human (AGENTS.md) |
| Needs you watching | tack loop works unattended; CI and an @claude bot run on every PR |
| Leaves no record | Every loop run is logged: attempts, check results, time, cost |
| Ties you to one tool | Works with Claude Code, Codex, Cursor, Gemini, Aider, or any CLI agent |
Quick start
# install the CLI (zero dependencies, Python 3.11+)
pip install tack-harness # or: uv tool install tack-harness / pipx install tack-harness
Start a new project. Claude interviews you, writes the spec, picks the stack, and scaffolds it with the ecosystem's official generator:
tack new my-app
cd my-app && claude "/bootstrap"
Add tack to an existing project. It detects every language in the repo, including monorepos:
cd your-project
tack init # writes tack.toml, AGENTS.md, CLAUDE.md, .claude/ (your own files are merged, never clobbered)
tack verify # run every check
tack doctor # find anything missing or misconfigured
Or use it as a Claude Code plugin (skills, subagents, and hooks with no CLI):
/plugin install tack --marketplace Mohidkz05/tack
How it works
flowchart TB
subgraph start [" "]
N["tack new my-app<br/><i>bootstrap skill: interview → SPEC.md →<br/>stack → official generator</i>"]
I["tack init<br/><i>detect stacks in an<br/>existing repo</i>"]
end
N --> C
I --> C
C["<b>tack.toml</b>: the verification contract<br/>format · lint · typecheck · test per component, any language"]
C --> L
subgraph L ["Everyday loop"]
direction LR
P[plan] --> B["build<br/>(test first)"] --> R[review] --> S[ship]
end
L --> H
H["<b>Hooks enforce it</b><br/>guard commands · protect secrets & lockfiles ·<br/>format on edit · no finishing until checks pass"]
H --> A["<b>Automation</b><br/>tack loop · CI on every push · @claude PR bot · run logs"]
1. One contract for every language
tack.toml maps a fixed set of checks onto each component's real tools. Hooks, agents, CI and tack loop only ever say "verify". They never need to know the stack.
[[components]]
name = "api"
path = "services/api"
stack = "python"
[components.commands]
format_check = "uv run ruff format --check ."
lint = "uv run ruff check ."
typecheck = "uv run mypy ."
test = "uv run pytest -q"
[[components]]
name = "web"
path = "web"
stack = "node"
[components.commands]
format_check = "pnpm exec prettier --check ."
lint = "pnpm run lint"
typecheck = "pnpm exec tsc --noEmit"
test = "pnpm run test"
Components run in parallel. --changed checks only the components touched since the last commit, so a 30-package monorepo verifies just what you changed. See the manifest reference.
| Detected automatically | From |
|---|---|
| Python | pyproject.toml / requirements.txt (uv, poetry, pip · ruff/black · mypy/pyright · pytest) |
| JavaScript / TypeScript | package.json (npm, pnpm, yarn, bun · prettier/biome · eslint · tsc · your scripts) |
| Go | go.mod (gofmt · go vet / golangci-lint · go test) |
| Rust | Cargo.toml (cargo fmt · clippy · cargo test), workspaces collapsed into one component |
| Java / Kotlin | pom.xml, build.gradle(.kts) (wrapper-aware, spotless) |
| Anything else | Makefile targets (make lint, make test, ...) |
2. Good habits, written down once
Skills (.claude/skills/) |
Subagents (.claude/agents/) |
|---|---|
plan: short, checkable plan before non-trivial work |
reviewer: fresh-context review, verified findings only |
build: red → green → refactor, finish on green checks |
test-writer: behavior-focused tests in the project's style |
review: correctness, contract, tests, security, scope |
security-reviewer: source-to-sink security review |
debug: reproduce → root cause → fix → prove |
|
commit: small Conventional Commits, never --no-verify |
|
ship: full checks, review, notes, PR |
|
bootstrap: turn a blank repo into a verified skeleton |
AGENTS.md holds the rules every agent reads (Codex, Cursor, and Gemini read it natively); CLAUDE.md imports it.
3. Guardrails that don't depend on the model behaving
| Hook | What it does |
|---|---|
SessionStart |
Tells the agent the components, the definition of done, and the saved PROGRESS.md |
PreToolUse · Bash |
Denies rm -rf //~, force-push to main, curl | sh, dd/mkfs, writes to .env. Asks before git reset --hard, sudo, --no-verify, publishing |
PreToolUse · Edit |
Blocks edits to secrets (.env, keys) and lockfiles (use the package manager) |
PostToolUse |
Formats the file that was just edited, with that component's formatter |
UserPromptSubmit · PreToolUse |
Playbook routing: points the agent at the right skill for what you asked or the file it's editing |
Stop |
Runs fast checks on what changed, and requires PROGRESS.md notes after real work. Sends the agent back (once) if either is missing |
All hooks are one stdlib-only file vendored into the project (.claude/hooks/tack). Teammates and CI need nothing installed, and it has no .py extension, so your linters and test runners never see it.
4. Your playbook: standard stacks and automatic skill routing
A playbook is a small repo with your picks: stacks/ (what to build with, per project type) and routes.toml ("in this situation, use this skill"). Connect one once for your whole machine:
tack playbook use Mohidkz05/playbook # or your fork, or a local folder
tack playbook # stacks, routes, and which skills you're missing
tack playbook route "make the landing page look better"
# redesign → redesign-existing-projects ✓
From then on, in every tack project:
- Skills are picked for you. When what you type, or the file Claude is about to edit, matches a route, Claude is told which skill to load (once per session per route). Design routes are grouped, so only the most specific design skill fires.
- New projects start from your stack picks.
bootstrapproposes the playbook's pick for the project type. tack doctorlists routed skills you haven't installed, and how to install them.
The playbook repo updates itself: a weekly job researches new releases and skills, and opens a PR with sources.
5. Automation
tack loop "add a /health endpoint with a test" # agent → verify → feed failures back → repeat
tack loop "fix the flaky test" --agent "codex exec {prompt}" --max-iters 3
tack runs # history: status, attempts, time, cost
tack add ci # GitHub Actions verify workflow, set up for your stacks
tack add claude-github # @claude on issues/PRs + automatic PR review
tack loop works with any agent CLI: {prompt} is replaced with the prompt (or it goes to stdin). Runs are logged as JSONL in .tack/runs/. Use --json for machine-readable output in scripts and pipelines.
Updates without clobbering your edits
tack update refreshes everything tack installed:
- Files you haven't touched are updated. tack tracks their hashes in
.tack/lock.json. - Files you've edited are kept and listed. Use
--forceto replace them. AGENTS.md: only the text between<!-- tack:begin -->and<!-- tack:end -->belongs to tack..claude/settings.jsonis merged. Your permissions and hooks stay; outdated tack entries are removed.- Files tack no longer ships are removed, unless you edited them.
The tack repo keeps itself current too. A weekly workflow checks for new Claude Code releases; Claude reads the changelog, updates tack if anything changed, runs the tests, and opens a PR. Dependabot covers the actions and dev dependencies.
Commands
| Command | |
|---|---|
tack new <dir> [--start] |
New project, ready for /bootstrap (--start launches Claude Code) |
tack init [path] |
Add tack to an existing project |
tack update [--detect] |
Refresh tack's files, keep your edits; --detect picks up new components |
tack add [ci|claude-github] |
Add an add-on (no args lists them) |
tack verify [--only lint,test] [-c api] [--changed] [--json|--markdown] |
Run the checks |
tack loop "<task>" [--agent CMD] [-n 5] |
Let an agent work until the checks pass |
tack runs |
Recent loop runs |
tack playbook [use|sync|route] |
Connect, update, and test your playbook |
tack doctor |
Diagnose the setup |
tack detect [--write] |
Show detected components / merge them into tack.toml |
Every command that matters is also available without installing anything: python3 .claude/hooks/tack verify | detect.
How tack relates to other tools
tack is deliberately small. Methodology packs like Superpowers and spec frameworks like Spec Kit and OpenSpec are mostly instructions for the agent. tack's focus is the enforcement layer underneath: a language-agnostic verification contract, hooks that block what instructions can only discourage, and automation that runs without supervision. They compose well. Use a spec framework for planning, and tack to make sure what gets built actually passes.
Development
git clone https://github.com/Mohidkz05/tack && cd tack
uv sync
uv run pytest # 143 tests, run in CI on Linux/macOS/Windows × Python 3.11-3.13
uv run tack verify # tack checks itself
python3 scripts/build_plugin.py # regenerate plugin/ after changing templates
tack is built with tack: this repo has its own tack.toml, hooks, skills, and PROGRESS.md. See CONTRIBUTING.md and the build plan.
License
Metadata
Release files for tack-harness 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tack_harness-0.2.0.tar.gz | 118.6 kB | With provenance | Details for tack_harness-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tack_harness-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for tack_harness-0.2.0-py3-none-any.whl |
Total release size: 176.1 kB
Release files / tack_harness-0.2.0.tar.gz
| Download URL | tack_harness-0.2.0.tar.gz |
|---|---|
| Size | 118.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08331223cd4326f42e07b126716cb77127d47453bb60fc2204c12792d1a63643
|
|
BLAKE2b-256 checksum How to use checksums |
e293764b02b0902036f30f29ead9cae73f33e3bd5dc214bfa628c27c8b4c9bd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / tack_harness-0.2.0-py3-none-any.whl
| Download URL | tack_harness-0.2.0-py3-none-any.whl |
|---|---|
| Size | 57.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca83c759bb4253b0929264fd94536c60cf197916234805e37dbf19f1f3757e4c
|
|
BLAKE2b-256 checksum How to use checksums |
1930b47396e744aac56bc7447810f5d8dc04b4bbbc5d332080517bfe161cc5a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for tack-harness 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tack_harness-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.