Taskrivet can take one ticket you choose from a local ticket service, open the agent you choose in a persistent terminal with a bounded context file, and post a report back to the ticket when you confirm it. You make each decision. Nothing in this loop picks work, claims a ticket, or runs an agent unattended.
tickets / ticket ──► work KEY --tool NAME ──► attach / links / watch ──► handback ──► handback --confirm
(read only) import, session, follow the agent and preview post through your
run folder, terminal its ledger records adapter, read back
Taskrivet never changes a ticket's stage, tags, owner, or holds, and never marks a ticket done. The only ticket write is a report you confirm.
Examples use the installed taskrivet command. From a checkout, run
python3 -m taskrivet instead.
Settings live in a private file, ~/.taskrivet/config.json by default
(TASKRIVET_CONFIG overrides the path). It must be a regular file owned by you
with mode 0600; Taskrivet refuses any other file. taskrivet config set writes
it atomically with mode 0600. It is not a credential store: keep tokens and keys
out of it.
| Setting | Meaning |
|---|---|
ticket_service.origin |
Loopback HTTP origin of a service that implements the ticket read protocol below. |
ticket_service.ticket_url |
Optional browser link template containing {key}, on a loopback origin. |
ticket_service.timeout |
Read timeout in seconds, 1–600. Default 30. |
ticket_adapter.argv |
Absolute path and arguments of your report adapter. Without it, reports can be previewed but not posted. |
ticket_adapter.timeout |
Adapter timeout in seconds, 1–600. Default 30. |
launchers.NAME |
A launcher override: argv, an optional label, or disabled with a reason. |
workdir |
Default working folder for work. Otherwise the current folder is used. |
runs_dir |
Where run folders go. Default ~/.taskrivet/runs. |
taskrivet config set ticket_service.origin http://127.0.0.1:8080
taskrivet config set ticket_service.ticket_url 'http://127.0.0.1:8080/#/ticket/{key}'
taskrivet config set workdir "$HOME/src/project"
taskrivet doctorThe origin above is a synthetic example. taskrivet doctor checks Python, the
config file, the ticket service, the ledger, the session service, launchers, the
adapter, and the run folder. It starts nothing and writes nothing, and it exits
with status 1 when a check fails. --offline skips the ticket service.
| Command | Purpose |
|---|---|
tickets [--q TEXT] [--status STATE] [--kind work|case|decision|all] [--limit N] [--offset N] |
One page of tickets with readiness and holds. Defaults: all states, work items, 50 rows. |
ticket KEY |
One ticket: holds, objective, acceptance, linked tickets, and any local tasks bound to it. |
ticket-import KEY [--ack] [--refresh] [--scope KEY] |
Bind the current ticket revision to a local task. Launches nothing. |
work KEY --tool NAME [--ack] [--refresh] [--cwd DIR] [--lease SECONDS] [--no-prompt] [--dry-run] |
Import, start a ledger session, and open the agent in a terminal. |
sessions |
Terminals in this ledger's session service. |
attach ID [--no-follow] [--no-input] |
Replay a terminal's scrollback and follow it. Ctrl-] detaches. |
links [--ticket KEY] [--no-live] |
Ticket-linked tasks with their session, agent terminal, latest checkpoint, and report state. |
watch [--task ID] [--ticket KEY] [--after SEQ] [--interval SECONDS] [--count N] |
Follow ledger events as they are recorded. |
handback TARGET [--note TEXT] [--confirm] |
Preview a report for a task, or for a ticket's latest task. --confirm posts it. |
launchers |
Agent launchers you can pick, and whether each is ready. |
doctor [--offline] |
Setup checks. |
config show|path|get KEY|set KEY VALUE|unset KEY |
Read or change the private config. VALUE is JSON or plain text. |
A typical run:
taskrivet --format table tickets --limit 20
taskrivet --format table ticket DEMO-42
taskrivet work DEMO-42 --tool codex --dry-run
taskrivet work DEMO-42 --tool codex --ack
taskrivet attach 3f9c1a2b # a unique prefix of at least 4 characters
taskrivet --format table links --ticket DEMO-42
taskrivet handback DEMO-42 # preview
taskrivet handback DEMO-42 --confirmsessions, attach, links, ticket, and doctor never start the session
service. Ledger commands, watch included, reconcile expired leases as they read.
JSON is the default and the stable interface for scripts. --format table, before
or after the subcommand, prints a view for people; TASKRIVET_FORMAT=table makes
it the default. watch prints one JSON object per line.
A failed command exits with status 2 and writes a JSON error to stderr, such as
{"error": "...", "type": "HoldsPending", "ticket": "DEMO-42", "holds": [...]}.
With --format table the error is plain text.
The ticket service must answer two GET requests with JSON:
GET /api/tix?status=STATE&limit=N&offset=N[&q=TEXT]returnsgenerated_at,stale,total, andtickets, plusloading,errors, orrefresh_errorwhen a read is incomplete.GET /api/tix/ticket?key=KEY&seen=0returns one ticket with itsdetail,notes,tags,stage,readiness, andlinks_resolved, or{"error": ...}.
Only loopback HTTP origins are accepted. Redirects and proxy settings are ignored, and responses are size-bounded. A list the service reports as loading or incomplete is refused instead of being shown as partial. A list is marked stale when the service does not report it as fresh, when it has no usable timestamp, or when it is more than five minutes old. A failed read is an error, never an empty list.
Ticket detail is bounded to 24,000 bytes and notes to 8,000 bytes, and anything
cut is marked. The objective and acceptance criteria come from lines labelled
Objective: or Goal:, and Acceptance:, Acceptance criteria:, or Done when:.
A ticket without acceptance criteria is imported with a note telling the agent to
ask you before treating the work as done.
The ticket revision is a SHA-256 hash of the key, kind, title, and detail. Stage,
tags, and readiness are not part of it: they are holds, read again on every work.
A hold is a known reason the ticket is not cleared for unattended execution:
- a
no-autotag, or a detail line saying the ticket is not authorized for autonomous execution - an operator decision the source says is required
- the ticket is already active or executing, or its stage needs reconciliation or review
- readiness that is not
READY, not verified, or stale - blocking dependencies, whose state Taskrivet does not check
work refuses to launch while any current hold is unacknowledged. --ack records
that you reviewed the holds listed at that moment, as a holds.acknowledged event.
It clears nothing: the holds stay on the ticket and are written into the run's
context file. A later launch reuses your acknowledgement only while every current
hold was among the ones you acknowledged. A new hold needs --ack again.
- Reads the ticket and resolves the launcher you named.
- Refuses if a hold is unacknowledged.
--dry-runstops here and shows the plan. - Imports the ticket as a task named after it, such as
ticket-demo-42, or reuses the open task already bound to it. The task reserves the resource keyticket:<KEY>plus any--scopekeys. If the ticket's revision changed since the import, it refuses until you pass--refresh, which attaches the new ticket text and recordssource.refreshed. - Starts a ledger session owned by
taskrivet-work:<tool>. The lease defaults to four hours and each checkpoint renews it. If the bound task is not ready, for example because it is still running or awaits review,workrefuses: attach to its terminal, or decide the task first withretry,accept, orcancel. - Writes a run folder,
<runs_dir>/<task>/<first 12 characters of the session>/, holdingcontext.md(objective, acceptance, acknowledged holds, bounded ticket text, and the ledger commands),ticket.json, andpacket.json(the task's context packet within 48,000 bytes). Folders are 0700 and files are 0600. - Opens the agent in a terminal of this ledger's session service, in the working
folder, through
/usr/bin/envwithTASKRIVET_TASK,TASKRIVET_SESSION,TASKRIVET_TICKET,TASKRIVET_CONTEXT, andTASKRIVET_RUNset. When the launcher takes a prompt, the agent starts with a short prompt pointing atcontext.md.--no-promptopens it without one. - Records
agent.launchedwith the tool, terminal, and session.
If the terminal cannot be opened, the session is failed with category
terminal_start. If the service connection was lost mid-request, the failure
says the outcome is unknown: run taskrivet sessions before trying again.
The agent records progress with taskrivet checkpoint, fail, and finish, as
shown in its context file. finish moves the task to your review. Acceptance is
still your separate taskrivet accept decision.
A launcher says how to open an agent CLI with an initial prompt. Built-in profiles
cover tools whose prompt option was checked against their own --help:
| Prompt form | Tools |
|---|---|
| first argument | claude, codex, droid, cursor-agent, cline, grok, vibe, qodercli |
-i PROMPT |
copilot, gemini |
--prompt PROMPT |
opencode, kilo |
Any other installed agent found by taskrivet tools opens with no arguments. It
can still find its context through TASKRIVET_CONTEXT. Tools change their options
between versions, so a private launcher overrides a built-in profile:
taskrivet config set launchers.my-agent '{"argv": ["/opt/tools/my-agent", "--context", "{context}", "{prompt}"], "label": "My agent"}'
taskrivet config set launchers.claude.disabled 'Paid lane; needs approval first'{prompt} and {context} are replaced inside arguments. The first element must
be an absolute path to an executable. With --no-prompt, arguments containing
{prompt} are dropped. A disabled launcher is refused with its reason.
The command line and the desktop share one session service per ledger. Its folder
is ~/.taskrivet/sessions-<12 hex characters>, derived from the ledger path, and
TASKRIVET_SESSION_DIR overrides it. When the desktop has not started a service,
work starts a standard-library Python service with the same socket, token, and
protocol, so the desktop shows those terminals too. The service holds up to 24
terminals with up to 1 MiB of recent output each, in memory only. A Python
service whose socket is removed or replaced stops accepting connections and exits
once its terminals have ended.
attach replays the bounded scrollback and then follows live output. When stdin
is a terminal, your keystrokes and window size reach the agent; --no-input only
watches. Ctrl-] detaches and leaves the agent running. --no-follow prints the
scrollback and returns.
taskrivet handback TARGET builds a report from the ledger and shows it: the local
task state, the latest session, the latest checkpoint's summary, evidence, and next
step, the finish evidence, self-reported tokens, recorded failures, and your
--note. Reports are bounded to 3,960 bytes — room is reserved so the appended marker
line still fits a 4,000-character note cap at the ticket service — and end by
saying that they do not accept the work or change the ticket. A preview never
calls the adapter.
--confirm posts the report:
- The report is stored as pending with a stable marker,
taskrivet-handback:<id>, appended after a blank line. - Taskrivet asks the adapter to
findthe marker. If the ticket already has it, the report is recorded as delivered and nothing is posted. - Otherwise it asks the adapter to
post, then tofindthe marker again. Only a successful readback records the report as delivered. - Any error, timeout, or failed readback keeps the report pending, adds an attempt,
and records the error. Running
--confirmagain reconciles through the same marker, so a post whose reply was lost is not duplicated.
Confirming the exact report that was already delivered posts nothing. --confirm
is refused when TASKRIVET_SESSION is set, because that shell belongs to an agent
run. This guards against accidents. It is not a security boundary.
The adapter is any executable you configure in ticket_adapter.argv. Taskrivet
runs it once per operation, writes one JSON request to its stdin, and reads one
JSON object of at most 1 MB from its stdout. A non-zero exit, invalid JSON, or a
timeout counts as a failure whose outcome is unknown. The adapter inherits your
environment without the run-scoped TASKRIVET_* variables.
{"protocol": 1, "op": "find", "ticket": "DEMO-42", "marker": "taskrivet-handback:0123456789abcdef"}
{"found": true}
{"protocol": 1, "op": "post", "ticket": "DEMO-42", "marker": "taskrivet-handback:0123456789abcdef",
"body": "Taskrivet report for DEMO-42 ...\n\ntaskrivet-handback:0123456789abcdef",
"sender": "Taskrivet", "role": "agent"}
{"posted": true}Return {"error": "reason"} for any failure. An adapter must:
- keep
findread-only, and reportfound: trueonly when a note on that ticket contains the marker - add one note with the full body on
post, and change nothing else: no stage, tags, holds, owner, or acceptance - return an error, not
posted: true, when it cannot tell whether the post landed - use the ticket service's supported API rather than writing to its database
- keep its own credentials, for example by reading them from the OS keychain at call time. Taskrivet passes and stores none.
A minimal adapter that keeps reports in a local file shows the shape:
#!/usr/bin/env python3
import json, sys
from pathlib import Path
store = Path.home() / ".taskrivet" / "example-notes.json"
request = json.load(sys.stdin)
notes = json.loads(store.read_text()) if store.exists() else {}
thread = notes.setdefault(request["ticket"], [])
if request["op"] == "find":
print(json.dumps({"found": any(request["marker"] in note for note in thread)}))
elif request["op"] == "post":
thread.append(request["body"])
store.write_text(json.dumps(notes))
print(json.dumps({"posted": True}))
else:
print(json.dumps({"error": "unsupported operation"}))- You choose the ticket and the agent. Eligible, imported, or acknowledged does not mean authorized, and Taskrivet does not claim the ticket at its source.
- The agent runs as you, with your files, network, and credentials. It is not sandboxed, and ledger limits do not stop it.
- Ticket text is untrusted reference data.
workwrites it into the run folder, and the agent you launch may send it to its model provider. - Tokens are self-reported, not measured billing. A finished session is not accepted work, and a delivered report is not acceptance.
- The ledger keeps ticket bindings and reports in schema 2. Existing ledgers gain the new tables in place, and earlier Taskrivet versions keep reading them.