use cases · 6 scenes
How people use it
Small scenes, with the commands that make them work. All the data is made up.
A developer's day log
a developer · Write the day as it happens. Tasks fall out of the prose and turn up in Today.
An agent's task board
a team of agents · A project vault with an issues board. Agents claim, work and finish; you review.
Project vaults for a team
a small team · A vault per project in a shared folder. Each person sees every vault in their own Today.
Research notes with links
a researcher · Pages that link to each other, backlinks for free, and queries over everything.
Capture from scripts and cron
a tinkerer · Your scripts write to the same notebook you do, safely, and you see it in the Log.
A bug tracker with screenshots
a maintainer · File a bug with a screenshot in it, see the image in the terminal, let an agent read it.
It’s 9:10 and the coffee is still hot. You open a terminal pane next to your editor and type thc j. Today’s journal opens with the caret on a fresh line, and nothing else asks for your attention.
You write the standup notes as a paragraph. Halfway through you remember the flaky login test, so you start a line with [ ] , add due:fri !high #work, and keep going. The tokens underline while you type; when you leave the line, due fri · !high slides into the quiet column on the right. Later, a note about the token parser needs to mention due: itself, so you put it in quotes and it stays a word.
At 11 you press Esc. Today shows the login test under Next 7 days, next to a reminder you set last week. x marks the morning’s small task done. ⌥Z back in the journal hides everything but your words for the long afternoon write-up.
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ─────────────────────────────────────────────────━━━━━━━━━────────────────────────────────────────── § Journal › Sun 04 Oct SUN 04 OCT 2026 THU 01 • FRI 02 • SAT 03 • [SUN 04 •] MON 05 TUE 06 WED 07 ───────────────────────────────────────────────────────────────────────────────────────────── Shipped the parser fix. The cold start went from 2.1 ms to 1.4 ms. [ ] Review the migration PR #api due fri · !high [ ] Write up the cache bug for [[Release checklist]] [ ] Pair on the flaky test sched:mon▮ 2026-10-05 ✓ § sun 04 oct · 33 words · autosaved ⌃T task ⌃O open ⌃P ⌃N day Esc done F1 keys thc 0.9.65
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ─────────────────────────────────────────────────━━━━━━━━━────────────────────────────────────────── § Journal › Sun 04 Oct SUN 04 OCT 2026 THU 01 • FRI 02 • SAT 03 • [SUN 04 •] MON 05 TUE 06 WED 07 ───────────────────────────────────────────────────────────────────────────────────────────── Shipped the parser fix. The cold start went from 2.1 ms to 1.4 ms. [ ] Review the migration PR #api due fri · !high [ ] Write up the cache bug for [[Release checklist]] [ ] Pair on the flaky test sched:mon▮ 2026-10-05 ✓ § sun 04 oct · 33 words · autosaved ⌃T task ⌃O open ⌃P ⌃N day Esc done F1 keys thc 0.9.65
At six, before you close the pane, you look at what the agent did while you were in meetings.
The commands
$ thc j # today, caret at the end
$ thc add "Standup: auth refactor is close, PR up after lunch #work"
added 5ghwy Standup: auth refactor is close, PR up after lunch #work in today's journal
$ thc todo "Fix flaky login test" --due fri -p high -t work
added 750tz [ ] Fix flaky login test due fri · !high · in today's journal
$ thc add 'Parser: "due:" inside quotes stays text'
added 50n5d Parser: "due:" inside quotes stays text in today's journalMidday, from any shell:
$ thc today
$ thc agenda --days 7
Fri Oct 9 · fri
750tz [ ] Fix flaky login test due fri · !high · in today's journal
pd0s6 [ ] Ship release notes fri 16:00 · in today's journalEnd of day:
$ thc q 'done>=today' # what got finished
$ thc log --by claude --since 1d # what the agent touched
$ thc review # accept or revert, oldest first
Review · 2 changes by claude · oldest first
...
$ thc j yesterday # if you need to look backWhy thc fits
- The log is the to-do list. You don’t switch to a task app to make a task; you write
[ ]in the middle of a thought, and Today finds it. - It lives where you already are. A pane in your terminal, one keystroke from your editor, with keys that match your shell.
- Nothing slips past you. Agent changes wait in the review lane until you’ve seen them, and every write is undoable.
This is how thc is built with its own agents.
The project has its own vault, picked up from a .thc.toml in the repo. Its settings.toml sends captures to a page called ¶ Issues, and a saved view, @issues, lays that page out as a board: Todo, Doing, Waiting, To review.
You file an issue in one line between two other things. An agent starting a session runs thc prime, asks thc next for the top ready task (in the order you put them on the page, skipping anything blocked), and claims it with a guarded write. A second agent reaching for the same item gets exit 4 and moves on. The first one writes what it finds under the issue, one note per finding, and marks it done. It can’t accept its own work: the issue sits in To review until you look.
The commands
You, filing:
$ thc todo "Export drops nested tags" -p high -t export
added 7gthv [ ] Export drops nested tags !high · in IssuesThe agent, working:
$ export THC_ACTOR=claude
$ thc next
7gthv [ ] Export drops nested tags !high · in Issues
from ¶ Issues · claim: thc set 7gthv status=doing owner=claude --expect status=todo --vault ~/thought-vaults/acme-site
$ thc set 7gthv status=doing owner=claude --expect status=todo
updated 7gthv [/] Export drops nested tags !high · in Issues
$ thc add --plain --under 7gthv "Reproduced: tags under a heading are dropped. Cause: export walks one level."
added 917ff Reproduced: tags under a heading are dropped. Cause: export walks one level. ◆ claude · in Export drops nested tags
$ thc done 7gthv
done 7gthv [x] Export drops nested tags !high · in IssuesAnother agent, a moment too late:
$ thc set 7gthv status=doing owner=codex --expect status=todo --json
{"error":{"kind":"stale","message":"expected status=todo, found doing · nothing written", …}}
$ echo $?
4You, reviewing:
$ thc q is:to-review
7gthv [x] Export drops nested tags !high · in Issues
$ thc review
Review · 3 changes by claude · oldest first
...Or in the app: 7, then r. a accepts, u undoes.
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ────────────────────────────────────────────────────────────────────━━━━━━━───────────────────────── Log · to review 1 oldest first r all changes ▌ 10:41 ◆ claude HC1Q73 created edx71 Summarize unread newsletters into [[Reading List]] + in § today · due tomorrow · #reading to review · 1 by claude ● live a accept u undo A accept all r all changes ? keys
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ────────────────────────────────────────────────────────────────────━━━━━━━───────────────────────── Log · to review 1 oldest first r all changes ▌ 10:41 ◆ claude HC1Q73 created edx71 Summarize unread newsletters into [[Reading List]] + in § today · due tomorrow · #reading to review · 1 by claude ● live a accept u undo A accept all r all changes ? keys
A whole team
thc team up pm engineer designer --agent claude starts one agent per role, each briefed for its job with thc prime --role and picking only work routed to it with thc next --role. They talk through the board (thc msg designer "…" --on 7gthv), and nobody starts until you’ve accepted the lead’s first plan. More in the agents guide.
Why thc fits
- No new tool for the agents. They already know a CLI; this one has
--json, stable exit codes and guarded writes, which is all a board needs. - Claims can’t race.
--expectmakes the claim atomic across agents and devices. - You stay the reviewer. Every write is signed, To review is derived from the log, and any of it undoes in one step.
Three of you work on two client projects, acme and globex, and each of you keeps a personal vault at home. The client work lives in a shared Dropbox folder: one vault per project, synced like any other files.
You join acme on Monday. You add the folder, and the header turns sea-blue: [•] acme. Inside the acme repo there’s a .thc.toml, so every thc you run there, and every agent you start there, writes to acme without being told. Your personal notes stay at home.
Your Today still shows everything that’s yours, from every vault. A row from acme says so in its meta, in acme’s colour, and when you mark it done it’s done in acme, for everyone. A reminder in globex reaches you named: globex · Send the draft · due 17:00.
The commands
$ thc vault add ~/Dropbox/clients/acme/thought # join a shared vault
$ thc vault ls
$ cd ~/code/acme && thc vaultOne .thc.toml in the repo points everything at the project:
vault = "acme"
The vault carries settings for everyone who has it, in its own settings.toml:
[vault]
name_short = "acme"
[theme]
accent = "sea"
[capture]
target = "¶ Issues"
Ask across vaults:
$ thc q 'vault:* status:open due<=+7d sort:due'
$ thc q 'vault:* status:open group:vault'
$ thc q 'vault:(acme or globex) #launch'
$ thc done globex/k7q2m # an id from another vault works anywhereMake a Today just for one client, and keep the default:
$ thc view copy today acme-today
$ thc view set acme-today --scope vault:acme
$ thc q @acme-todayAn agent in the acme repo sees acme only:
$ cd ~/code/acme && THC_ACTOR=claude thc primeIn the app, V opens the vault picker with open and inbox counts, and space t v splits Today into a section per vault.
Why thc fits
- Silos where they help, one view where you need it. Projects stay separate and shareable; Today is still about you.
- No server to run. A shared folder is the whole backend. Each device writes its own log files, so the sync tool never sees a collision, and a real conflict keeps both versions.
- Agents stay in their lane. The folder decides the vault, so an agent working in one repo can’t wander into another client’s notes.
You’re reading about replicated logs. Each paper gets a line in the journal the day you read it, with a [[link]] to the idea it touches: [[Replay ordering]], [[Tombstones]]. Typing [[ offers the pages you have; a new name makes the page when the line saves. You misspell one as [[Tombstoens]] and thc offers the page you meant before it makes a second one.
A week later you open ¶ Replay ordering. Your own notes are at the top. Under them, linked from lists every journal line that mentions it, with its day. You didn’t file anything; the links did.
For the long write-up you switch on Focus, and the screen is just the column of text, the date and a word count.
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ─────────────────────────────────────────━━━━━━━──────────────────────────────────────────────────── ¶ Pages › Q4 Planning Q4 Planning ───────────────────────────────────────────────────────────────────────────────────────────── [ ] ▮raft Q4 OKRs mon · due oct 10 · !high [ ] Collect last quarter's metrics due tue [ ] Review draft with the team due fri · Theme for the quarter: fewer, deeper bets ────────────────────────────────────── linked from 01 ─────────────────────────────────────── · Kickoff for Q4 planning, see [[Q4 Planning]] § thu oct 01 ¶ Q4 Planning · 19 words · autosaved ⌃T task ⌃O open Esc done F1 keys thc 0.9.65
[•] personal Today Inbox 2 Tasks Pages Journal Search Log 1 Sat Oct 3 · 10:41 ─────────────────────────────────────────━━━━━━━──────────────────────────────────────────────────── ¶ Pages › Q4 Planning Q4 Planning ───────────────────────────────────────────────────────────────────────────────────────────── [ ] ▮raft Q4 OKRs mon · due oct 10 · !high [ ] Collect last quarter's metrics due tue [ ] Review draft with the team due fri · Theme for the quarter: fewer, deeper bets ────────────────────────────────────── linked from 01 ─────────────────────────────────────── · Kickoff for Q4 planning, see [[Q4 Planning]] § thu oct 01 ¶ Q4 Planning · 19 words · autosaved ⌃T task ⌃O open Esc done F1 keys thc 0.9.65
The commands
Capture as you read:
$ thc add "Paper: CRDTs for outlines, see [[Replay ordering]] #paper"
added 2p7vh Paper: CRDTs for outlines, see [[Replay ordering]] #paper in today's journal
$ thc todo "Reread section 4 of the tombstones paper" -t paper --sched satBring in an outline you drafted elsewhere:
$ thc import - --page "Replay ordering" < outline.md
imported 3 nodes under ¶ Replay ordering · tx SNK244 · thc undo --tx SNK244 reverts all of itFind things:
$ thc search tombstones
$ thc show gcqh0 # a page, its children and its backlinks
gcqh0 Replay ordering
dp87y Open questions
linked from
2p7vh Paper: CRDTs for outlines, see [[Replay ordering]] #paper in today's journal
$ thc q '#paper created>=-2w sort:date'
$ thc q 'ancestor:( text:Replay ) status:open'Write:
$ thc p "Replay ordering" # open the page to write inInside, a click on a link follows it (so does ⌃O with the cursor in one), ⌃O anywhere jumps to any page or day by name, and ⌥Z toggles Focus. :focus planner adds a month calendar and the links beside the text.
Why thc fits
- Links do the filing. Write where you are; the page collects its mentions on its own.
- Plain text all the way down. Paste Markdown in, copy Markdown out, and
thc exportwrites a folder Obsidian can read. - Questions, not folders. A query finds the open threads under a topic, or what you read in the last two weeks, without a tagging scheme decided in advance.
The nightly backup job fails about once a month. Until now it emailed you, and you missed it. Now it adds a task to your inbox instead, keyed by date, so a cron job that retries three times still leaves one task. A post-commit hook drops a line into the day’s journal for every commit, so the day log writes itself. On Fridays a small script plans the release as one batch.
You see all of it the way you see an agent’s work: signed, in the Log, and undoable.
The commands
A script that’s safe to re-run:
#!/bin/sh
export THC_ACTOR=backup
day=$(date +%F)
if ! restic backup ~/work >/tmp/backup.log 2>&1; then
thc todo "Nightly backup failed, see /tmp/backup.log" \
--inbox -p high -t ops --key "backup-$day"
fi$ ./backup-check.sh
added jdxp1 [ ] Nightly backup failed, see /tmp/backup.log !high
$ ./backup-check.sh
exists jdxp1 [ ] Nightly backup failed, see /tmp/backup.log !highThe cron line:
15 3 * * * ~/bin/backup-check.shA git hook, .git/hooks/post-commit:
#!/bin/sh
sha=$(git rev-parse --short HEAD)
THC_ACTOR=git thc add --plain --key "commit-$sha" \
"$(git log -1 --format=%s) ($sha)" >/dev/null--plain keeps a commit message’s #123 as text rather than a tag.
Read with --json and check exit codes:
$ thc q 'status:open #ops' --fields short,text,priority
$ thc set jdxp1 status=doing --expect status=todo || echo "someone got there first ($?)"
$ thc daemon status >/dev/null || echo "offline: alerts paused" # exit 3 when it isn't runningA batch, all or nothing:
$ cat release.jsonl
{"cmd":"add","text":"Release 0.4","inbox":true,"as":"rel"}
{"cmd":"todo","text":"Tag the build due:thu","under":"$rel","key":"rel-0.4-tag"}
{"cmd":"todo","text":"Write notes !med","under":"$rel","key":"rel-0.4-notes"}
$ thc apply release.jsonl --dry-run
apply · 3 ops → 1 transaction (dry run)
+ add Release 0.4 → inbox
+ todo [ ] Tag the build due Thu → under Release 0.4
+ todo [ ] Write notes → under Release 0.4
3 ok · nothing written
$ thc apply release.jsonl
applied 3 ops · tx M86CBM · thc undo --tx M86CBM reverts all of itWhen a script misbehaves:
$ thc log --by backup --since 1d
$ thc undo --by backup --since 1dWhy thc fits
- Idempotent by design.
--keygives the same note on every run and every device, so retries and double-fired crons are harmless. - A real contract.
--jsonoutput only ever grows, exit codes mean one thing each, andthc schema <cmd>describes them. - Scripts are actors too.
THC_ACTORsigns every write, so a noisy script is onethc undo --byaway from gone.
A layout glitch shows up in the settings screen. You take a screenshot (⌃⇧⌘4), switch to the thc pane, and file it in one line. Enter on the new issue opens it as a document: the task line on top, an empty body below. You write two lines of steps and press ⌘V. The screenshot attaches as its own line, and in WezTerm, iTerm2, kitty or Ghostty it draws right there under its chip, sized to the column.
The agent you hand it to doesn’t need eyes on your screen. thc show --json gives it the image’s path, size and dimensions, so it opens the file itself, reproduces the bug, and writes what it found under the issue, with a screenshot of the fix next to yours.
The commands
The project vault sends captures to the issues page ([capture] target = "¶ Issues" in its settings.toml):
$ thc todo "Settings panel overlaps the footer at 80 columns" -p high -t layout
added 4mzq2 [ ] Settings panel overlaps the footer at 80 columns !high · in IssuesAttach from the command line, if the screenshot is already a file:
$ thc attach 4mzq2 overlap.png --caption "80 columns"
attached files/2026/10/mwxqh-overlap.png · 1280×720 · 240 KB under 4mzq2What the agent reads:
$ thc show 4mzq2 --json --depth 1{
"short": "4mzq2",
"text": "Settings panel overlaps the footer at 80 columns",
"status": "todo",
"priority": "high",
"attachments": [{
"path": "files/2026/10/mwxqh-overlap.png",
"caption": "80 columns",
"mime": "image/png", "bytes": 245760, "w": 1280, "h": 720,
"missing": false
}]
}
The agent works it, and attaches its evidence the same way:
$ export THC_ACTOR=claude
$ thc set 4mzq2 status=doing owner=claude --expect status=todo
$ thc add --plain --under 4mzq2 "Cause: the footer height isn't subtracted below 90 columns."
$ thc attach 4mzq2 after.png --caption "after the fix"
$ thc done 4mzq2You check it: the issue waits in is:to-review, the two screenshots sit side by side in its body, and a in the review lane closes it.
$ thc doctor # a missing file, or one nothing refers to, shows up hereWhy thc fits
- The screenshot lives with the bug. It’s a file in the vault and a Markdown line in the note: it syncs, exports and survives any tool.
- You see it where you work. Inline images in the terminals that can draw them, a clickable chip everywhere else, and a plain chip over SSH.
- Agents get the evidence, not a description of it. The JSON hands them the file, and their own attachments come back signed.