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.
Humans can run tkv for a local dashboard (mark, claim, create, meta, order, inspect title and body, the tag lens, sync, and doctor diagnose/reindex; agents keep using tk). tkv starts it in the background and returns the shell; tkv stop stops it, and tkv foreground keeps it in the terminal.
tk create --edit is human $EDITOR convenience: after a successful scaffold it opens the new ticket with the same editor contract as tk edit. Agents keep using the printed path.
The implementation is the source of truth.
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.
brew tap p3bot/tap
brew trust p3bot/tap
brew install p3bot/tap/tkgo install github.com/p3bot/tk/cmd/tk@latest
go install github.com/p3bot/tk/cmd/tkv@latestgo build ./...
go build -o tk ./cmd/tk
go build -o tkv ./cmd/tkvRequires 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.
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
tk scope rename <old> <new>
tk scope auto-commit [true|false] [--scope S] # read or set git-root-wide autoCommit
tk scope hold [off|soft|hard [reason]] [--scope S] # read or set this scope's hold
tk scope field list|set|unset [--scope S] # declare custom frontmatter fields in tk.cueinitcreates and registers a new scope, writing a minimaltk.cueand a.gitignorecovering.tk.lock. Exactly one of--name/--auto-nameis required. In a dedicated tk repo, pass--auto-commit(omitting it registers repo-driven).importregisters an existing on-disk scope, files in place; its name and auto-commit mode come from the on-disktk.cue.rebindrewrites a registered scope's paths after a move or clone.forgetunregisters a scope (registry, lens, and note entries only); it never touches the scope's files.listprints parse-stable TSV, one line per scope:name\tdir\troot\tmode\thold\treason, wheremodeistk-driven,repo-driven,plain-files, orunknown,holdisoff,soft,hard, or empty whentk.cuecannot be evaluated, andreasonis the hold reason, empty when there is none.renamerenames a scope end-to-end (registry, lens, note default,tk.cuename, ticket ids).holdprintsoff,soft, orhard, or rewrites the hold on that one scope. It is stored intk.cueas one field, such ashold: {type: "hard", reason: "x"}. A held scope reports it on stderr (scope_hold:), with the reason when there is one.softis for changes larger than a single ticket. No ticket entersin-progress:tk mark in-progress,tk next --claim,tk createwith that status, andtk rehomeof an in-progress ticket into the scope exit 1 and do not write. Other ticket work continues.hardis a complete stop.tkalso refuses other ticket and design writes, includingtk mark done,tk order,tk metachanges,tk rehometo or from the scope, andtk edit. Reads, thetk scopeverbs, notes,tk lens,tk sync,tk repair,tk doctor, andtk reindexstill run.tkcannot block a code change or a direct file edit, so stopping those is up to whoever sees the hold.- A reason is committed and pushed with the scope, so it must not contain anything
private.
tk pulse holdandtk pulse hold_reasonread the state for scripts. - Upgrade
tkandtkvon every machine that shares the scope before setting a hold. An older binary reads any structholdasconfig_unparseable:, refuses writes andtk syncon that git-root, and asks fortk.cueto be fixed. Do not remove the hold to satisfy it.tk scope hold offrestores the old format.
auto-commitprints the evaluatedautoCommitbool, or rewrites it totrue/falsefor every registered scope that shares the dir's git-root (already-that-value is ensure: exit 0, no rewrite). Mode labels stay derived; afalseset is the last tk-owned commit (allowlisted dirty paths ride it), then host git push if unpushed.fieldreads and rewrites custom field declarations underfields:in the ambient scope'stk.cue(list,set,unset). Optionalrequiredis soft policy only (required_missing:on meta/mark; never a hard refuse).
tkv is the human dashboard. Agents keep using tk.
Note: restart a detached tkv after upgrading, because an older binary reads any
struct hold as config_unparseable: (see hold above).
tkv [start] [--listen HOST|HOST:PORT] [--port N] [--no-open] [--scope NAME]
tkv stop
tkv status
tkv foreground [same flags as start]
tkv listen [HOST|HOST:PORT] [--clear] # show, store, or clear the listen address
tkv hosts [NAME...] [--clear] # show, replace, or clear extra hostnames
tkv user list | set NAME | delete NAME # network-mode login usersBy default tkv listens on 127.0.0.1:8736 in loopback mode: plain HTTP, no
login, and only the hosts localhost, 127.0.0.1, and [::1] are answered.
Binding any other address turns on network mode, for using the dashboard from another machine:
tkv user set grant # prompts for a password (or reads one line from stdin)
tkv start --listen 0.0.0.0 # or store it: tkv listen 0.0.0.0- Network mode always serves HTTPS and requires a login before any page or write. There is no unauthenticated network mode, and it refuses to start with no users.
- The certificate is self-signed and generated by tkv, so every browser warns
until the warning is accepted (Chrome-family browsers warn again weekly). The
start banner and
tkv statusprint its SHA-256 fingerprint; compare it with the one the browser shows before accepting. - The listen host is an IP address or
localhost.0.0.0.0serves IPv4 only and::serves IPv6 only. Names other machines use for this one (nas.lan, an mDNS.localname) go intkv hosts; restart after changinglistenorhosts. - Changing a password or deleting a user signs that user's browsers out on the next request, with no restart. Sessions do not expire otherwise; use the Log out button.
- Machine-local files:
~/.config/tk/tkv.cue(listen address, hosts, password hashes; mode 0600), and~/.local/state/tk/tkv/(certificate, key, cookie signing key). Deletingsession.keyand restarting signs every browser out. Failed sign-ins are logged to~/.local/state/tk/tkv.logwith the client IP.
Each scope can keep committed markdown worklogs at <scope-dir>/notes/<slug>.md.
They are not tickets: tk list does not show them, they are not indexed, and
they are not part of the agent skill. Humans (or an agent that needs session
context) use tk note (notes is an alias).
tk note # print this machine's default note (missing is empty)
tk note [slug] # print notes/<slug>.md (one-shot; missing is an error)
tk note --name <slug> # same as tk note [slug]; never writes the default
tk note list # addressable slugs, alphabetical
tk note use # print the effective default slug
tk note use <slug> # set this machine's default for the scope
tk note use --clear # revert to built-in default
tk note add <text...> # append one line to the default
tk note add --name <slug> <text...> # append one line to a named note
tk note set <text...> # replace the default
tk note set --name <slug> - # replace named from stdin
tk note edit # $EDITOR on the default
tk note remove # unlink the default
tk note remove --name <slug> # unlink named (one-shot)use is machine-local (XDG note.cue, keyed by scope name). Documents stay
committed under notes/; the pointer is not stored in tk.cue or
lens.cue. Unset (or use default / --clear) keeps the built-in slug
default. --name and a positional slug stay one-shot selectors. Personal
slugs (grant, alice) with default as the shared pad are a convention,
not a CLI rule.
add, set, edit, and remove never self-commit. On a tk-driven scope,
add, set, and remove ride sync_needed: dirty (same as tk create);
edit and use do not. Durability is tk sync on a tk-driven scope, or a host
commit on a repo-driven scope. Slugs follow the
existing ticket-slug grammar (a-z0-9 and hyphens, 1–48). list, ls, add,
set, edit, remove, rm, help, and use are reserved names and cannot be
document slugs. A missing default on tk note is empty stdout, exit 0. A missing
named note on tk note [slug] is non-zero with the path on stderr and empty
stdout; an empty file is empty stdout, exit 0.
tk pulse note prints the path of notes/<effective-slug>.md whether or not
the file exists.
- stdout is a path or closed TSV; diagnostics and closed tokens go to stderr.
- Exit
0success;2for usage / bad CLI input; other failures are generic non-zero. There is no--jsonand no colour on stdout.NO_COLORsuppresses all ANSI.
| Task | Command |
|---|---|
| Build | go build ./... |
| Test | go test ./... |
| Format | gofmt -w . |
| Vet | go vet ./... |
| Lint | golangci-lint run ./... |