Skip to content
p3botPublic

About

Agent ticket board in plain markdown

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

183 Commits

Folders and files

Repository files navigation

tk

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. 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.

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
go install github.com/p3bot/tk/cmd/tkv@latest

Build from Source

go build ./...
go build -o tk ./cmd/tk
go build -o tkv ./cmd/tkv

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
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.cue
  • 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, lens, and note entries only); it never touches the scope's files.
  • list prints parse-stable TSV, one line per scope: name\tdir\troot\tmode\thold\treason, where mode is tk-driven, repo-driven, plain-files, or unknown, hold is off, soft, hard, or empty when tk.cue cannot be evaluated, and reason is the hold reason, empty when there is none.
  • rename renames a scope end-to-end (registry, lens, note default, tk.cue name, ticket ids).
  • hold prints off, soft, or hard, or rewrites the hold on that one scope. It is stored in tk.cue as one field, such as hold: {type: "hard", reason: "x"}. A held scope reports it on stderr (scope_hold:), with the reason when there is one.
    • soft is for changes larger than a single ticket. No ticket enters in-progress: tk mark in-progress, tk next --claim, tk create with that status, and tk rehome of an in-progress ticket into the scope exit 1 and do not write. Other ticket work continues.
    • hard is a complete stop. tk also refuses other ticket and design writes, including tk mark done, tk order, tk meta changes, tk rehome to or from the scope, and tk edit. Reads, the tk scope verbs, notes, tk lens, tk sync, tk repair, tk doctor, and tk reindex still run. tk cannot 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 hold and tk pulse hold_reason read the state for scripts.
    • Upgrade tk and tkv on every machine that shares the scope before setting a hold. An older binary reads any struct hold as config_unparseable:, refuses writes and tk sync on that git-root, and asks for tk.cue to be fixed. Do not remove the hold to satisfy it. tk scope hold off restores the old format.
  • auto-commit prints the evaluated autoCommit bool, or rewrites it to true/false for every registered scope that shares the dir's git-root (already-that-value is ensure: exit 0, no rewrite). Mode labels stay derived; a false set is the last tk-owned commit (allowlisted dirty paths ride it), then host git push if unpushed.
  • field reads and rewrites custom field declarations under fields: in the ambient scope's tk.cue (list, set, unset). Optional required is soft policy only (required_missing: on meta/mark; never a hard refuse).

Dashboard (tkv)

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 users

By 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 status print 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.0 serves IPv4 only and :: serves IPv6 only. Names other machines use for this one (nas.lan, an mDNS .local name) go in tkv hosts; restart after changing listen or hosts.
  • 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). Deleting session.key and restarting signs every browser out. Failed sign-ins are logged to ~/.local/state/tk/tkv.log with the client IP.

Notes

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.

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 ./...

About

Agent ticket board in plain markdown

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages