Claude Code and Codex agent tasks — visible, reusable, approval-gated. No server, no hidden state.
A small harness layer for Claude Code and Codex
I kept adding new AI coding tools. Each was useful on its own, but stacking them made my setup heavy and tangled — and I'd burn a real slice of my token budget just reconfiguring before any actual work began. I wanted the opposite: something small that adapts to me, not the other way around. That's Tink.
Without Tink, agent tasks live only in chat history — context resets on every run, workflows repeat by hand, and nothing gets better over time.
With Tink, every non-trivial task leaves plain files you can read, diff, and commit: a task contract, a visible plan, verification steps. Reusable workflows — harnesses — are saved only after your explicit approval, then improved from real run data. One command turns those records into a local health dashboard.
Claude Code (plugin):
/plugin marketplace add dotoricode/tink-harness
/plugin install tink@tink-harness
/reload-plugins
/tink:setup
Claude Code or Codex (standalone):
npx tink-harness@latest installThe installer auto-detects LANG (English fallback); pass --lang=en|ko|zh to override. During install you can pick Claude Code, Codex, or both.
Repo-local Codex smoke test (CODEX_HOME)
set CODEX_HOME=%CD%/.codex
npx tink-harness@latest install --yesThen hand Tink a real task instead of reading more docs:
/tink:cast refactor the auth module # Claude Code
$tink:cast refactor the auth module # Codex
cast picks (or drafts) the right harness, writes a visible plan into .tink/current/, and starts the first safe step after your approval.
If this matches your workflow, a ⭐ helps other developers find it.
- Claude Code or Codex keeps losing task context between runs
- You repeat the same review / refactor / debug workflow by hand
- You want visible run state instead of hidden chat memory
- You want reusable agent workflows — saved only after explicit approval
Before (plain Claude Code / Codex):
"refactor the auth module"
→ plan lives in chat only
→ no completion criteria
→ context lost next session
After (/tink:cast refactor the auth module):
→ .tink/current/contract.json — what must be true when done
→ plan.md / checks.md — visible plan and verification steps
→ /tink:verify — proves "done" with evidence, not vibes
→ .tink/runs/…md — compact record, reusable next time
Every non-trivial task leaves plain files you can open, diff, and commit:
.tink/current/ # the active run — always inspectable
contract.json # what must be true when the task is done
plan.md # the visible plan
checks.md # verification to run before claiming "done"
.tink/runs/
2026-06-11-1430-auth-refactor.md # compact record of each finished run
.tink/harnesses/
refactor-review.md # reusable ways of working — approval-gated
What a finished run actually looks like
Run record (.tink/runs/YYYY-MM-DD-HHMM-task.md):
Status: completed
Goal: make Tink easier to invoke in Codex with direct entrypoint skills.
Changed: updated main `tink` skill to recognize `$tink:<action>` aliases; added thin wrapper skills.
Evidence: `find … | rg 'tink(-|/)'` showed all SKILL.md files plus the main skill.
Notes: no reusable memory or harness was changed.
Verify evidence (/tink:verify, two outcomes):
✅ evidence_kind: command
evidence_ref: npm test
observed: 47 tests passed, 0 failures
⚠️ evidence_kind: manual
evidence_ref: clean install smoke (macOS)
observed: not run — CI runner is Linux only
next_action: run manually on macOS before publish
| Tooling | What it gives you | What Tink adds on top |
|---|---|---|
| CLAUDE.md | project-wide instructions | per-task contracts, run state, and verification |
| Slash commands | reusable prompts | harness selection, run records, progress tracking |
| Skills | reusable capability | usage lifecycle: health scores, cleanup and improvement signals |
| MCP | external context and tools | local, approval-gated workflow memory |
Tink composes with all of these — it does not replace them.
After a few runs, one command turns your records into a local dashboard and opens it in your browser:
npx tink-harness dashboard # add --no-open to just generate the fileAn interactive 3D map of your harnesses, the rules and memory they use, and how they connect:
Harness cards sorted by real usage, with plain-language health summaries, attention scores, approval history, and copy-paste next actions for both Claude Code and Codex:
Under the hood it runs two read-only helpers (node .tink/tools/generate-harness-lifecycle-summary.mjs, then node .tink/tools/render-harness-health-report.mjs) and opens .tink/maintenance/harness-health-report.html. The harness health summary shows usage, failed checks, run review cards, ROI hints, and weave/frog candidates. No server, no telemetry, no hidden cache — a static local page. It only prepares suggestions; acting on them keeps the approval gates above.
Tink is knit in reverse: untying tangled workflows and knitting better ones back together. It also nods to Tinker Bell, the small helper at your side.
New AI tools and content flood in every day. Many are worth trying. But the bigger harness-engineering tools — the ones with real power — are built for specific tasks and scales. Switching between them is friction: heavy setup, hard to reconfigure, awkward to use for something small. I kept bouncing between them and resetting my environment from scratch.
Then I used Hermes Agent for a while. What stayed with me wasn't any feature — it was the principle. A system that gets better through use: repeated work turns into reusable skills, mistakes become memory, the tool slowly adapts to the person using it.
Tink started from a simple question:
Could an AI Agent tool like Claude Code or Codex grow with me in the same way?
Not by adding a big framework. Not by running more agents. Just by helping the agent choose the right approach for the current task, create one when nothing fits, and quietly improve the set over time.
I also had to accept something: people can't produce perfect prompts, and AI agents aren't perfect yet either. So the tool needed to go both ways — correcting and refining task instructions, not just executing them faster. That's why cast runs a structured interview when the task is unclear, and why failed checks get recorded so the same mistake doesn't repeat.
The knitting metaphors aren't decorative. cast (코잡기) is how you start — picking or drafting the right harness for this task. frog (풀시오) is how you clean up what stopped being useful. weave (실오라기 정리) is how you tighten what stays. A harness that worked once can be saved and reused; one that didn't gets removed or merged.
It's not finished. But I reach for it every day at work, and it keeps getting more useful. The core bet: if humans and AI agents are both imperfect, the tool between them should help each side compensate for the other — not lock either into a fixed setup.
Commands reference
Tink is plugin-first in Claude Code. Commands are namespaced under tink: /tink:* in Claude Code, $tink:* in Codex. Legacy $tink cast style still works, but $tink:* is preferred.
cast means to place the first loops on the needle (코잡기, Cast on). In Tink, cast is the main path — it reads the task, picks or drafts the right harness, creates .tink/current/ as the visible workbench, and starts the first safe step after approval.
frog means to rip out stitches (풀시오, Frogging). In Tink, frog looks for harnesses that are unused, overlapping, too broad, or no longer worth their context cost. It proposes cleanup, but does not delete without approval.
weave means to weave in the ends (실오라기 정리, Weave in). In Tink, weave improves an existing harness using real use, failures, and corrections.
| Command | What it does |
|---|---|
/tink:cast |
Read the task, pick or draft the right harness, create .tink/current/, start the first safe step |
/tink:deep-cast |
Same as cast but always runs the structured deep interview — without changing your default cast_mode |
/tink:verify |
Run the checks promised in contract.json — proves "done" with evidence, not vibes |
/tink:frog |
Find unused, overlapping, or too-broad harnesses — proposes cleanup, never deletes without approval |
/tink:weave |
Improve a harness from real failures and corrections — saves only after approval |
/tink:setup |
Choose language, install scope, git tracking, and hook policy |
/tink:list |
Inspect available harnesses and recent usage signals |
/tink:update |
Detect install source and show the safe update command |
Cast details: for bigger or fuzzier work, cast can surface visible-thinking harnesses: requirements-interview (ambiguous ideas), plan-consensus (big plans), goal-checkpoint (long runs), delegation-brief (safe handoffs). Focused harnesses like issue-triage, bug-diagnosis-loop, review-two-axis, decision-map, and architecture-deepening are also available — all selected by cast, not separate workflows.
How it works
Everything Tink knows lives in plain files you can read, diff, and delete:
| Path | What it holds |
|---|---|
.tink/harnesses/ |
the harness set — specialized procedures only |
.tink/current/ |
the active run: plan, steps, contract, verification checks |
.tink/runs/ |
compact records of finished runs |
.tink/memory/ |
approved lessons and preferences; drafts wait in memory/candidate/ |
.tink/rules/ + .tink/schemas/ |
a small rule graph for harness selection, plus file schemas |
.tink/maintenance/ + .tink/tools/ |
usage signals and the read-only helpers that render the local dashboard |
Three rules drive all of it:
- Generic work runs without a harness. An ordinary code change, review, or doc edit runs on the base run contract alone — plan, steps, verification evidence. A harness is loaded only when a specialized procedure actually changes what happens: release gates, goal checkpoints, plan critique, requirements interviews, issue triage, hard-bug diagnosis loops, two-axis reviews, decision maps, architecture deepening, or other domain workflows.
- Suggestions only. The dashboard,
frog, andweaveprepare proposals from real usage signals. Nothing reusable — a harness, a memory entry, a deletion — is saved without its own explicit approval. Approving today's run never authorizes changes that future runs would inherit. - Evidence over vibes. Run records, failed checks, evidence summary cards, and friction events decide what gets improved (
weave), promoted from draft to harness, or cleaned up (frog). Weak evidence defaults to keep-and-observe, never to delete.
Design docs index — details for contributors
- Compatibility baseline (Claude Code + Codex, macOS + Windows):
docs/compatibility-policy.md - Repo signals:
docs/repo-signals.md,docs/repo-signals.ko.md· graph-rule adoption plan:docs/graph-rule-adoption-plan.ko.md - Harness health summary:
docs/harness-lifecycle-signals.md,docs/harness-lifecycle-signals.ko.md - External context safety:
docs/mcp-safe-profile.md,docs/external-context-policy.md - Reading
.tink/current/state:docs/work-state.md,docs/work-state.ko.md - Update confidence:
docs/phase-5-update-confidence.md,docs/phase-5-update-confidence.ko.md - Context efficiency:
docs/context-budget-ledger.md,docs/context-budget-ledger.ko.md,docs/context-metrics-evaluator.md,docs/context-metrics-evaluator.ko.md,docs/context-run-history-rollup.md,docs/context-run-history-rollup.ko.md,docs/context-threshold-status.md,docs/context-threshold-status.ko.md,docs/context-run-record-policy.md,docs/context-run-record-policy.ko.md - Planned work:
docs/planned-work-units.md,docs/planned-work-units.ko.md· roadmap and idea audit:docs/tink-idea-implementation-plan.ko.md
Update
Claude Code plugin:
/plugin marketplace update tink-harness
/plugin update tink@tink-harness
/reload-plugins
If update does not find the latest version, uninstall and reinstall:
/plugin uninstall tink@tink-harness
/plugin install tink@tink-harness
Standalone (Claude Code or Codex):
npx tink-harness@latest updateUpdate asks one question — which agent surface to refresh — and handles the rest automatically. Language, install scope, and git policy are reused from install; if you chose not to commit .tink, update never touches your .gitignore. Tink-owned files are always brought to the latest version; your customized harnesses, memory, config, and all .tink/maintenance/ history records are preserved.
If CODEX_HOME is not set, Codex skills default to %USERPROFILE%\.codex on Windows and ~/.codex on macOS/Linux.
Advanced options (visible in the interactive wizard):
Preview only (--dry-run): see exactly what Tink would write, preserve, or remove — no file changes.Overwrite user-modified files (--force): use only when an install is broken and you want official templates to replace local edits. Normal updates keep user-modified files.Clean Codex picker (--clean-codex-picker): removes duplicateSource Command Tink ...entries when switching a repo to Codex-only. Not shown for mixed Claude Code + Codex installs.
The package exposes a tink-harness binary — if it is on your PATH, you can run tink-harness update directly; otherwise keep using npx tink-harness@latest update.
Verify: docs/update-verification-recipe.md or docs/update-verification-recipe.ko.md. Troubleshoot: docs/update-troubleshooting.md or docs/update-troubleshooting.ko.md.
Tink is not a coding agent, workflow engine, multi-agent runtime, or prompt library. It is a small harness layer for Claude Code or Codex.
npm test # template sync, syntax, version parity
npm run test:pack # pack manifest: required files, no secrets
npm run test:e2e # real install into tmpdir, update preservation, Codex surface
npm run check # npm test + test:pack togetherCI runs npm test, test:pack, and test:e2e on Ubuntu and macOS.
Issues and pull requests are welcome. Start with CONTRIBUTING.md — the short version: run npm test && npm run test:pack, keep command templates in sync across their three copies, and describe changes as problem / solution / verification.
If Tink saves you time, a ⭐ helps other developers find it.
MIT