tk

module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2026 License: MPL-2.0

README

tk — Agent Ticket Management CLI

tk tracks feature work as plain markdown files, one ticket per file, edited in place. It indexes, queues, and locates tickets; the filesystem is the editor.

The implementation is the source of truth.

Supported platforms

macOS and Linux only. Windows is not supported — there is no flock or path substitute, and tk fails with a clear startup error on an unsupported OS rather than half-running. This is a deliberate v1 scope limit.

Installation

Homebrew (Linux/macOS)
brew tap p3bot/tap
brew trust p3bot/tap
brew install p3bot/tap/tk
Go Install
go install github.com/p3bot/tk/cmd/tk@latest
Build from Source
go build ./...
go build -o tk ./cmd/tk

Requires Go 1.26. Pure Go, no cgo. The external git binary is used only to derive a code-root / git-root; it is shelled out, never linked.

Scopes

A scope is a directory of ticket markdown files plus its tk.cue (the scope's name, auto-commit mode, and schema). Scopes are registered per machine in the XDG config directory (${XDG_CONFIG_HOME:-~/.config}/tk/).

tk scope init <dir> (--name <name> | --auto-name) [--code-root <path>] [--auto-commit]
tk scope import <dir> [--code-root <path>]
tk scope rebind <dir> --name <name> [--code-root <path>]
tk scope forget <name>
tk scope list          # bare `tk scope` and `tk scopes` also run list
  • init creates and registers a new scope, writing a minimal tk.cue and a .gitignore covering .tk.lock. Exactly one of --name / --auto-name is required. In a dedicated tk repo, pass --auto-commit (omitting it registers repo-driven).
  • import registers an existing on-disk scope, files in place; its name and auto-commit mode come from the on-disk tk.cue.
  • rebind rewrites a registered scope's paths after a move or clone.
  • forget unregisters a scope (registry and lens entries only); it never touches the scope's files.
  • list prints parse-stable TSV, one line per scope: name\tdir\troot\tmode, where mode is tk-driven, repo-driven, plain-files, or unknown.

Output and exit codes

  • stdout is a path or closed TSV; diagnostics and closed tokens go to stderr.
  • Exit 0 success; 2 for usage / bad CLI input; other failures are generic non-zero. There is no --json and no colour on stdout. NO_COLOR suppresses all ANSI.

Development

Task Command
Build go build ./...
Test go test ./...
Format gofmt -w .
Vet go vet ./...
Lint golangci-lint run ./...

Directories

Path Synopsis
cmd
tk command
Command tk is the agent ticket management CLI.
 Command tk is the agent ticket management CLI.
internal
atomicfile
Package atomicfile writes a file via same-directory temp + rename so readers never see a half-written file and an interrupted write cannot truncate an existing one.
 Package atomicfile writes a file via same-directory temp + rename so readers never see a half-written file and an interrupted write cannot truncate an existing one.
cli
Package cli is tk's Cobra command tree, exit codes, signals, and output rules.
 Package cli is tk's Cobra command tree, exit codes, signals, and output rules.
collision
Package collision is the pure total order for same-id collision keeper pick.
 Package collision is the pure total order for same-id collision keeper pick.
flock
Package flock provides exclusive, blocking POSIX advisory locks via syscall.Flock.
 Package flock provides exclusive, blocking POSIX advisory locks via syscall.Flock.
fmmerge
Package fmmerge is a pure 3-way frontmatter merge over three raw git stage blobs.
 Package fmmerge is a pure 3-way frontmatter merge over three raw git stage blobs.
frontmatter
Package frontmatter models a ticket file's leading YAML frontmatter.
 Package frontmatter models a ticket file's leading YAML frontmatter.
git
Package git wraps the external git binary for path-scoped staging, commits, porcelain status, and mid-rebase detection.
 Package git wraps the external git binary for path-scoped staging, commits, porcelain status, and mid-rebase detection.
gitroot
Package gitroot derives a directory's enclosing git repository root via the external git binary.
 Package gitroot derives a directory's enclosing git repository root via the external git binary.
gitstate
Package gitstate manages per-git-root operational state in machine-local XDG state — never under <git-root>/.git/.
 Package gitstate manages per-git-root operational state in machine-local XDG state — never under <git-root>/.git/.
id
Package id implements the ticket-id wire contract: predicates, crypto/rand short-id mint, and deterministic collision-repair extension.
 Package id implements the ticket-id wire contract: predicates, crypto/rand short-id mint, and deterministic collision-repair extension.
index
Package index is tk's machine-wide SQLite read model: a derived, rebuildable store under XDG state (never inside a scope, never synced).
 Package index is tk's machine-wide SQLite read model: a derived, rebuildable store under XDG state (never inside a scope, never synced).
integrity
Package integrity is the doctor diagnose report and the shared repair orchestration above pure internal/repair: acquiring entry for doctor, locks-held batch apply + edge_verify for both doctor and sync integrity.
 Package integrity is the doctor diagnose report and the shared repair orchestration above pure internal/repair: acquiring entry for doctor, locks-held batch apply + edge_verify for both doctor and sync integrity.
order
Package order implements fractional-index rank keys whose byte-wise string comparison equals rank order.
 Package order implements fractional-index rank keys whose byte-wise string comparison equals rank order.
pathutil
Package pathutil holds boundary-safe path predicates over filesystem paths.
 Package pathutil holds boundary-safe path predicates over filesystem paths.
rebasedriver
Package rebasedriver resolves one conflicted ticket .md at a paused rebase.
 Package rebasedriver resolves one conflicted ticket .md at a paused rebase.
reconcile
Package reconcile is tk's read-through: it brings the derived SQLite index into agreement with ticket files before a command reads it, git-free.
 Package reconcile is tk's read-through: it brings the derived SQLite index into agreement with ticket files before a command reads it, git-free.
registry
Package registry is the machine-local XDG config tier: which scopes are registered, at which paths, plus the per-scope lens.
 Package registry is the machine-local XDG config tier: which scopes are registered, at which paths, plus the per-scope lens.
repair
Package repair holds deterministic, bit-identical integrity-repair procedures: id-collision loser pick and short-id extension, equal-order and over-long-order re-space, and archive-layout move.
 Package repair holds deterministic, bit-identical integrity-repair procedures: id-collision loser pick and short-id extension, equal-order and over-long-order re-space, and archive-layout move.
resolve
Package resolve implements ambient scope resolution.
 Package resolve implements ambient scope resolution.
rewrite
Package rewrite is the shared multi-file in-scope rewrite durability engine.
 Package rewrite is the shared multi-file in-scope rewrite durability engine.
scope
Package scope implements --auto-name derivation from a code-root basename.
 Package scope implements --auto-name derivation from a code-root basename.
scopeadmin
Package scopeadmin orchestrates the scope-administration verbs (init, import, rebind, forget, list) over the machine-local registry.
 Package scopeadmin orchestrates the scope-administration verbs (init, import, rebind, forget, list) over the machine-local registry.
scopeconfig
Package scopeconfig evaluates a scope's tk.cue into a validated Schema.
 Package scopeconfig evaluates a scope's tk.cue into a validated Schema.
scopefile
Package scopefile holds scope-directory file policy shared by write verbs, doctor, and sync: allowlist classification, dirty counting, and the per-scope flock path.
 Package scopefile holds scope-directory file policy shared by write verbs, doctor, and sync: allowlist classification, dirty counting, and the per-scope flock path.
selfcommit
Package selfcommit is the single reusable self-commit step for auto-commit scopes.
 Package selfcommit is the single reusable self-commit step for auto-commit scopes.
skill
Package skill holds the agent skill contract printed by `tk skill`.
 Package skill holds the agent skill contract printed by `tk skill`.
slug
Package slug implements create-time filename slugify: pure, deterministic, no uniqueness pass.
 Package slug implements create-time filename slugify: pure, deterministic, no uniqueness pass.
status
Package status defines built-in ticket statuses, the closed Category set, and terminal/list/next predicates.
 Package status defines built-in ticket statuses, the closed Category set, and terminal/list/next predicates.
syncengine
Package syncengine is tk's sole push boundary: selection policy (auto-commit-only filter, unreachable/disabled/config-error reporting, participants grouped by git-root) and the per-root flow (preflight, lock order, snapshot, fetch/integrate, mid-rebase resume, sync-time integrity via integrity.RunBatches, push-if-ahead).
 Package syncengine is tk's sole push boundary: selection policy (auto-commit-only filter, unreachable/disabled/config-error reporting, participants grouped by git-root) and the per-root flow (preflight, lock order, snapshot, fetch/integrate, mid-rebase resume, sync-time integrity via integrity.RunBatches, push-if-ahead).
testgit
Package testgit runs git in tests under a hermetic config env.
 Package testgit runs git in tests under a hermetic config env.
title
Package title extracts the first ATX H1 from a markdown body.
 Package title extracts the first ATX H1 from a markdown body.
token
Package token defines the closed set of machine-readable stderr tokens tk emits at line start.
 Package token defines the closed set of machine-readable stderr tokens tk emits at line start.
xdg
Package xdg resolves tk's machine-local XDG config/state dirs and the machine-global flock over the config tier.
 Package xdg resolves tk's machine-local XDG config/state dirs and the machine-global flock over the config tier.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.