Hallmark

Where you hear about it

• In Claude Code. In any session, in any repo, a hook tells Claude what's waiting, so it mentions it. The status line shows the count. Ask "what needs me?" and Claude runs hall inbox.
• In the terminal app. Your Office sits at the top with a count in the title bar, and the terminal bell rings.
• On the desktop. A notification on macOS, Linux or Windows. Clicking it opens the item in the terminal app.
• On your phone. Through ntfy (open source, and you can host it yourself), Telegram or a Slack webhook. A question with options shows them as buttons.
• A morning digest. One summary of what's waiting, what closed yesterday, and what it used.

Your Workshop sessions are covered too. Claude Code fires a Notification hook when a session needs a permission or has waited for you, and Hallmark files it under the session's item.

# the Claude Code status line
rindahq/platform · H-0041 development · ⚑ 2 need you

How a question travels

1. The agent asks. hall ask "billed usage or raw events?" --options billed,raw --default billed --wait 4h. Its run ends with the status waiting, and Hallmark saves the session ID.
2. You're told. The item moves to Your Office and the notifications go out. A reminder repeats every 2 hours until you answer.
3. You answer anywhere. Tell Claude Code "answer H-0043: billed", run hall answer Q-12 a, press a in the terminal app, or tap the button on your phone.
4. The agent resumes. The daemon runs claude -p --resume <session> with your answer, so the agent keeps its context. Answered within the hour, most of that context is still cached.
5. It's on record. The question, the answer and who gave it go in the journal. Decisions worth keeping become learnings in the Library.

If a question has a default and a wait, and nobody answers in time, the agent goes ahead with the default and the journal says so. Escalations never use a default.

# .hallmark.toml (or your user config)
[notify]
desktop     = true
phone       = "ntfy://ntfy.sh/hallmark-7f3k2q"
quiet_hours = "22:00-07:30"   # phone waits, desktop still shows
remind      = "2h"
digest      = "08:30"

[notify.route]
question  = ["desktop", "phone"]
escalated = ["desktop", "phone"]
stuck     = ["desktop", "phone"]
ready     = ["desktop"]
budget    = ["desktop"]
learnings = ["digest"]

Anyone who knows the topic name can read a topic on the public ntfy.sh. Hallmark sends only the item, the question and the options, never code, and generates a random topic. You can also host ntfy yourself.

Measured today

A one-word reply from Haiku through claude -p still loaded 29.7k tokens of context: 21.2k written to cache and 8.5k read from it. That's the fixed cost of any run before it does any work.

This design conversation, on Opus, has made 114 model calls: 18.1M tokens read from cache, 525k written to cache, and 399k output tokens. Long interactive sessions are where most tokens go, which is why the Workshop is metered too.

Costs are API list-price equivalents. They're a stable unit for comparison, not a bill. Claude plans count usage against limits rather than charging per token, and Hallmark can't read how much of your limit is left, so it enforces its own caps.

How it learns

1. An item closes or escalates. Its journal holds what the reviewer found, what was disputed and how it was settled, and your decisions with reasons.
2. The librarian distils it. A small Haiku run turns the journal into proposed learnings. It updates existing entries rather than adding duplicates. Each costs a few thousand tokens.
3. You approve the learnings. Proposed learnings wait in your inbox until you accept or reject them with hall library review. They live in a local store next to the journal, never in the repository, so no branch can change what its review is told.
4. The reviewer is briefed. Before each review, Hallmark picks the learnings scoped to the changed paths and searches the rest using the diff. It sends the best of them within a set token limit.
5. Learnings earn their place. Each verdict says which learnings it used and whether they held. Contradicted or unused ones are retired.

What a learning looks like

---
id: L-0017
kind: rule      # rule · false-positive · map · decision
scope: ["apps/api/src/webhooks/**"]
lens: correctness
source: [H-0042/F1]
status: accepted
used: 4         # reviews it informed
last_used: 2026-10-09
---
A retry must check that the endpoint still exists
before each attempt. A deleted endpoint keeps its
queued deliveries until the job notices.

• Rules come from findings that turned out right.
• False positives record what not to flag, and why. They cut repeat noise and wasted fix rounds.
• Maps describe what a module does, so the reviewer stops re-exploring the same code. That saves tokens on every review.
• Decisions are your rulings on escalations, with your reasons.

Where qmd fits

qmd is a local search engine for Markdown, built for agents. It combines keyword search, vector search and reranking, with local models stored in SQLite. It has a JSON command line and an MCP server, and it's MIT-licensed. The Library is a folder of Markdown files, so qmd fits it without changes. It also runs locally, so searching the Library costs no Claude tokens.

It brings a Node 22 or Bun runtime, about 2 GB of local models, and on macOS a Homebrew SQLite. That's a lot to require of every install, so Hallmark makes it an option. Built-in search works everywhere; hall init offers qmd when it finds it. Hallmark always queries a single collection, because qmd ranks results from several collections in one shared pool.

# .hallmark.toml
[library]
search         = "qmd"     # or "builtin"
collection     = "hallmark-platform"
briefing_limit = "6k"      # tokens sent to each review
auto_accept    = ["map"]   # kinds that skip your approval
retire_after   = "90d"     # unused learnings

$ hall library search "webhook retries" --json
{"results": [{"id": "L-0017", "kind": "rule",
  "scope": ["apps/api/src/webhooks/**"],
  "score": 0.91, "used": 4}]}

$ hall ready
{"error": {
   "code": "ITEM_IN_REVIEW",
   "message": "H-0042 is in review, round 2.",
   "next": ["hall pull-back H-0042",
            "hall log H-0042 --kind review"]}}
$ echo $?
4

One Rust binary, hall, does everything. Run it with no arguments and it opens the terminal app, the human view of everything above. The subcommands are what agents, hooks and the daemon call. Because the hooks call the binary rather than shell scripts, it runs the same on macOS, Linux and Windows.

The app only reads the journal. Closing it never stops work; the loops run in hall daemon. Opening it on another terminal, or after a restart, shows the same state.

• Board. Items by state, with ones that need you flagged at the top.
• Journal. The selected item's full history, newest at the bottom, with a scrubber to replay it as above.
• Findings. Every finding with its lens, severity, file and line, the commit that claims to fix it and the review that verified it.
• History. Closed and dropped items, filterable by outcome, lens or rejection reason. It answers "what got rejected this week, and why".
• Live. The output of whatever the daemon is running now: a test run, or the reviewer's progress.
• Usage. Tokens and API-equivalent cost by room, item, model or day, against your budgets.
• Repos. Every repository on this machine that uses Hallmark, with counts of items needing you. tab switches between them.

• ratatui and crossterm for the interface. crossterm drives Windows consoles as well as Unix terminals.
• notify to redraw when a journal file changes.
• clap for subcommands, serde_json for the journal, fs4 for file locks.
• cargo-dist to release binaries for all three systems, with Homebrew, an install script and a Nix flake.

Each item has an append-only file of events. Nothing is edited or deleted, so the history you read is the history that happened. Hooks write your session's events and the daemon writes the loop's. Every write goes through hall, which holds a file lock.

.git/hallmark/                  shared by every worktree
├─ items/H-0042/
│  ├─ item.json              title, branch, state
│  ├─ events.jsonl           the journal
│  ├─ reviews/r1.md          full review reports
│  └─ checks/r1.log          failing check output
└─ queue/                    tickets waiting for the assayer

A SQLite index, rebuilt from these files at any time, answers usage and history questions quickly. The journal lives in each repo's git directory, so it outlives worktrees and is never committed. A small registry in your user state directory lists which repos use Hallmark, so the terminal app can show them all. hall export H-0042 writes the whole record as Markdown, and the PR body links to it.

{"t":"10:04:12","actor":"you","event":"ready",
 "sha":"7c2d018","note":"cap at 6 attempts done"}
{"t":"10:24:31","actor":"assayer","event":"review",
 "round":2,"sha":"b81f3e4","verdict":"changes",
 "findings":["F1","F2"],"report":"reviews/r2.md"}
{"t":"10:38:05","actor":"fixer","event":"commit",
 "sha":"2a9e771","fixes":["F1","F2"]}

• Your prompts and the agent's turn summaries, through Claude Code hooks
• Every commit, and which findings it claims to fix
• Every check run, with exit code, duration and failing output
• Every verdict, with each finding's lens, severity, file, line and scenario
• Every decision you make, with your reason
• The hallmark, the PR link and the time spent in each state

# .hallmark.toml
base         = "main"
worktree     = "git worktree add ../{repo}-{id} -b {branch}"
ship         = "git push -u origin {branch} && gh pr create --fill"
gates        = []                  # hall init fills these
reviewer     = "claude -p"
max_rejects  = 3
stuck_after  = "30m"
lenses       = "all"
rules        = ["CLAUDE.md", "AGENTS.md"]

[budget]                           # no caps unless you set them
review_model = "opus"
fix_model    = "sonnet"

# .hallmark.toml
worktree = "rig wt new {branch}"
ship     = "rig submit --pr"
gates    = ["rig test", "rig run build"]
rules    = ["CLAUDE.md",
            "docs/plan/README.md#leave-alone"]

Every command is a setting, so a repo can use its own tooling without Hallmark knowing about it. The reviewer and fixer commands are settings too. Claude Code comes first because its hooks and skills make the session part of the record.