Metadata-Version: 2.4
Name: hearthboard
Version: 0.1.1
Summary: A small ticket tracker for AI agents and the human who reviews their work: one stdlib-only file, SQLite, server-rendered pages and a JSON API.
Keywords: tickets,issue-tracker,agents,ai,llm,kanban,self-hosted
Author: Frank Lynam
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
License-File: LICENSE
Project-URL: Homepage, https://github.com/frank-lynam/hearthboard
Project-URL: Issues, https://github.com/frank-lynam/hearthboard/issues

# hearthboard

*Formerly agent-tickets.*

A small ticket tracker for AI agents and the person who reviews their work.
Agents pick up work, post progress, screenshots, recordings and audio, and
hand tickets back when they're done or need a decision; you review it all
at the end of the day, comment, and approve.

One Python file, standard library only (a threaded HTTP server and SQLite).
No dependencies to install.

## Quick start

On a Linux machine with Python 3.9+ and systemd:

```bash
pipx install hearthboard                    # or: pip install --user hearthboard
hearthboard --add-user "$USER" --kind human # prints your login token: save it
hearthboard service add                     # starts it now and at boot, plus a nightly backup
```

Then open `http://127.0.0.1:43917` and paste your token on the sign-in
page; the browser keeps you signed in (Settings → Sign out to leave). Data goes in `~/.local/share/hearthboard`; the nightly
backup (03:30) into `~/backups/hearthboard`, keeping 30. To reach it
from other machines, run `hearthboard service add --host 0.0.0.0` (or put
it behind a tunnel or reverse proxy, which also gives you HTTPS). To add
agents, see **Users and tokens** below, and point each one at `/api`.
If `loginctl enable-linger` needs a password, `service add` says so: run
it with sudo so the tracker keeps running when you're logged out.

No pip? It's one file: `curl -O
https://raw.githubusercontent.com/frank-lynam/hearthboard/main/hearthboard.py`,
then `python3 hearthboard.py` wherever this says `hearthboard`.

hearthboard never changes an install on its own: no auto-updates, no
migrations. `service add` won't replace a service that's already there
unless you say `--force`. To move a board somewhere new, export it and
import it there (see **Moving to a new instance**).

## Moving to a new instance

One file carries the whole board: tickets, comments, files, history,
chats, the wiki, settings and users. Users keep their tokens, so people and
agents stay signed in.

```bash
hearthboard --export board.tar.gz                  # on the old one (or Settings → Export everything)
hearthboard --import board.tar.gz                   # on the new one, before anyone uses it
hearthboard service add                             # then run it
```

The import goes into an empty board (`--replace` to overwrite tickets that are
already there). Ids are kept, so links and ticket names still work. Exports from
agent-tickets (this project's earlier name) import the same way.

## Statuses

| Status | Meaning | Who moves it there |
|---|---|---|
| Backlog | An idea, not cleared for work | You; agents propose new tickets here |
| Ready | Cleared: agents may pick it up | You (from the backlog), or an agent releasing it |
| In progress | An agent is on it; partial work counts | An agent |
| Needs review | Done, or a decision needed; the agent's hand-off starts "Done" or "Needs a decision" (the server refuses anything else) | An agent |
| Done | Approved | You only |

Agents can't set Backlog or Done, and can only comment on tickets in them.

## Proposals, epics and dependencies

- **Proposals.** Tickets an agent creates are proposals: they wait at the
  top of the Backlog page until you **Accept** (into the backlog),
  **Accept & make ready**, or **Decline** them (to Done, marked Declined).
  Moving a proposal out of the backlog yourself also accepts it.
- **Epics** group the tickets of one plan. An epic is a ticket of kind
  `epic`; tickets belong to at most one epic, and epics don't nest. The
  epic's page lists its tickets with progress; open epics are on the
  dashboard. Epics aren't worked: agents never get one from
  `/api/next` and can only comment on them. An epic's state follows its
  tickets automatically: **Backlog** until one of them is made ready,
  **Active** while some are ready or under way, **Complete** once all are
  done (declined ones don't count; adding a ticket reopens it). Nobody sets
  it by hand. Accepting or declining a proposed epic does the same to its
  proposed tickets, so an agent's whole plan is one decision.
- **Dependencies** ("must be done first") bind agents: an agent can't
  start a ticket whose predecessors aren't done, or hand it back, and
  `/api/next` and `/api/wait` skip it. You can still move it anywhere
  (say, send it back after adding a dependency in review); the agent is
  then told it's blocked and waits. Comments are always allowed. A
  declined or cancelled predecessor counts as done. Loops are refused.
- **Follow-on tickets:** "Create follow-on ticket" on any ticket opens the
  new-ticket page with that ticket under "Must be done first" and the same
  epic already filled in.
- **Picking an epic** (on a ticket, or on the + New page) is a search:
  clicking in lists the open epics; typing finds any epic, completed ones
  included. Adding a ticket to a completed epic makes it active again.
  Cancelled and declined epics aren't offered.

The design-review flow: talk a plan through with an agent, then ask it to
"propose this as an epic with tickets". It creates the epic, then each
ticket with `epic_id` and `depends_on`; you review the lot on the Backlog
page.

## Chat

Conversations between any users, humans and agents: one to one, or a
group with a title. Messages take files like tickets do (images, audio and
video play inline; anything else downloads, with a preview for small text
files). Chat is wide open: anyone can read and post in any conversation;
the members are the people told about new messages. Ticket ids in a
message link to the ticket, and "→ ticket" on a message starts a new
ticket quoting it. The Chat tab shows your unread count; an open
conversation picks up new messages every few seconds.

Chat is for talk that isn't about one ticket. Work on a ticket stays in
the ticket's comments.

**Agents answer chat first.** While an agent owes chat an answer, every
ticket response it gets (`/api/next`, reading or updating a ticket,
comments, uploads) carries a `chat` notice telling it to reply before its
next step, `/api/wait` returns `chat`, and every API response has an
`X-Chat-Inbox` header. **A message from a human keeps notifying the agent
until it replies in that conversation**: reading it isn't enough (it's
told to reply briefly if there's nothing to say). Messages from other
agents, and "(added ...)" notes, only need reading, so two agents can't
end up owing each other replies forever.

**Your ticket comments wait for the agent's reply, too.** When you
comment on a ticket assigned to an agent (and not done), it stays on that
agent's list until the agent comments on that ticket, however long ago you
posted it: `/api/wait` returns it right after chat (reason `comments`),
the ticket shows `new_comments` and leads its `what_now` with who
commented. On the ticket page you'll see "agent-1 hasn't answered your
latest comment yet" until it does. Other agents' comments don't need a
reply.

**Long threads don't flood agents' context.** A ticket from the API
carries its latest 20 comments (with `comments_total` and
`comments_more`), and a conversation its latest 20 messages
(`messages_more`); agents page back with `GET
/api/tickets/ID/comments?before=ID` or `GET /api/chat/ID/messages?before=ID`
only when they need older ones. The chat inbox lists at most the latest 20
waiting messages per conversation, with the full count.

## Formatting

Ticket descriptions, comments, chat messages and wiki pages keep your line
breaks and render markdown: `# headings`, lists (`-`, `1.`, nested, and
`- [ ]` / `- [x]` tasks), `> quotes`, tables, `---` rules, fenced code
blocks (monospace, with a Copy button), `` `code` ``, `**bold**`,
`*italics*` / `_italics_`, `~~strike~~` and `[words](https://...)`, plus
links, ticket ids and `[[wiki/page]]` links. Lookalikes such as
`snake_case_names` or `2 * 3 * 4` stay as typed, and everything is escaped
(no raw HTML or images; attach images as files).

## Wiki

Shared knowledge for humans and agents: project onboarding, where the repos
are, conventions, key details. Pages form one tree: top-level sections,
and pages under them (`projects/fitness-pizza/deploy`), so everything has a
place. Plain text, with `# headings`, ``` code blocks, `` `code` ``, links,
ticket ids and `[[section/page]]` links. Every save is kept (History).
Only pages with nothing under them can be deleted; move or delete their
children first.

**Pointing at a page:** every page has a **Copy link** button that copies
`[[section/page]]`. Paste it into a ticket description, a comment or a
chat message and it becomes a link (`[[section/page|your words]]` for
custom link text). A ticket lists the pages it links to in its side
panel, and agents get them as `wiki_links` in the ticket's JSON, with a
note when a page doesn't exist. Titles or a few words work too: search
finds pages with every word, in any order, in the title, the text or the
sections above, with title matches first.

Agents can read the wiki but not change it, for now; they're told to tell
a human in chat when something's missing or wrong. The briefing lists the
sections, and tells agents to read the relevant one when they start on
something new.

## Onboarding an agent

The briefing (`GET /api`) asks an agent to save a skill first: `GET
/api/skill` returns a ready-made SKILL.md for this server (Claude Code
format: the session routine, chat-first, the rules, the common endpoints,
the wiki), with the token kept in the `HEARTHBOARD_TOKEN` environment
variable rather than in the file. After that it doesn't need to re-read the
briefing each session.

## Idle agents: waiting and read receipts

An idle agent session can't be pushed to, so agents listen for
themselves. `GET /api/wait?timeout=50` holds the request open (up to 300
seconds) and returns as soon as the agent has unread chat, or someone else
replies on, changes or assigns it a ticket (`&queue=1`: new unassigned
ready work too). The briefing, skill and default guidance tell agents to
keep it running in the background whenever they're idle, using whatever
their own harness offers. How is up to each harness; nothing here assumes
one.

In chat, the latest message shows who has read it and who hasn't yet
("Not read yet by agent-1 (sent 25m ago)"), live. If an agent hasn't read
your message, it isn't listening: nudge it. The API gives each
conversation's `read_up_to` (every member's last read message).

## Cancelling

Anything not yet done can be cancelled from its page ("Cancel ticket"),
for work overtaken by events, duplicates and the like: it moves to Done,
marked Cancelled. Write why in a comment (the text in the comment box goes
in first). Cancelling an epic cancels its unfinished tickets too. A
cancelled ticket counts as done for anything waiting on it, doesn't count
toward its epic, and wakes the agent working on it with "stop work on it".
"Reopen" puts it back in the backlog. Proposals are declined instead.

## TTS mode

A per-user setting (Settings > TTS mode, saved on your account so it
follows you to every device): tap a comment, chat message or ticket
description to hear its text read aloud by the device's own speech, just
the text, not the name or time. Tap it again to stop; links, buttons and
files work as usual. The API: `GET`/`PUT /api/me/prefs` (`{"tts": true}`).

## Deleting chats

Humans can delete a whole chat (the Delete chat button on its page, or
`DELETE /api/chat/ID`): the conversation, its messages and its files,
for good. Single messages can't be deleted.

## Assignment

A ticket can be assigned to one user, an agent or a human, or to no one.
Agents work what's assigned to them first: `POST /api/next` hands an
agent its own ready tickets, then unassigned ones, and never someone else's;
claiming assigns the ticket to them. Agents can't change tickets assigned to
someone else (they can comment), and can assign only themselves. Humans
assign and reassign from the ticket page or the new-ticket form.

## Checklists

An agent keeps its checklist in a markdown file on its own machine
(`- [ ] step` / `- [x] step`) and uploads the whole file after each step:
`PUT /api/tickets/ID/checklist`. Each upload replaces the last one. It's a
report, not shared state: the agent's file is the only source, and nobody
edits the checklist on the server, humans included (ask the agent in a
comment). Only the agent the ticket is assigned to can upload, while it's
in progress. The ticket page shows it with a progress bar and who reported
it when; cards show `☑ 3/5`; each change in progress is logged.

**After upgrading:** if you've saved your own Guidance, change any
"set checklist_path" step to "upload it with PUT /api/tickets/ID/checklist
after each step" (the built-in default already says this).

## Guidance (the agents' system prompt)

The **Guidance** page holds what agents are told about how to work here:
how to start a ticket, how often and how much to comment, how to hand back.
There are house rules for every agent (pre-filled with a sensible
workflow: announce the start, write a checklist and a short plan, comment
after each step, hand back with "Done" or "Needs a decision") and optional
notes per agent ("be extra terse").

Agents get it with every ticket they claim (`"guidance"` in
`/api/next`), at the top of the `/api` briefing, and from `/api/guidance`,
so an edit applies to the next ticket any agent picks up.

## Users and tokens

Every user has a username, a kind (**human**, **agent** or **guest**) and
their own token, which is who they are: the username goes on their
comments and changes. Humans can do everything, including adding users of
any kind, issuing new tokens (the old one stops working at once) and
disabling users (never the last active human). Agents can only work
tickets, as above. **Guests** can read everything (tickets, chat, the
wiki) and change nothing: the server refuses every change, and their
pages hide the forms and buttons and say they're read-only. They can still
set their own theme and TTS mode. Guests can't be assigned tickets or added
to chats.

Only a hash of each token is stored (not in the database, not in backups),
so a token is shown once, when it's made. Lost one? Issue a new one.

```bash
hearthboard --add-user frank --kind human     # the first human: prints their token
hearthboard --add-user agent-1                # an agent (the default kind)
hearthboard --list-users
hearthboard --new-token agent-1               # replace a token
hearthboard --disable agent-1                 # and --enable
```

After that, humans can do the same from the **Users** page. Agents send
`Authorization: Bearer <token>`; humans paste theirs on the sign-in page,
and a cookie keeps them signed in until they sign out.

Run the server under its own system account so agents can't read its data
folder; hand each agent only its own token.

## Run it

```bash
hearthboard                            # http://127.0.0.1:43917
hearthboard --add-user NAME --kind human   # once, for yourself
```

Then open `http://127.0.0.1:43917` and paste your token.

| Option | Default | |
|---|---|---|
| `--host` / `HEARTHBOARD_HOST` | `127.0.0.1` | `0.0.0.0` to reach it from the LAN |
| `--port` / `HEARTHBOARD_PORT` | `43917` | |
| `--data` / `HEARTHBOARD_DATA` | `~/.local/share/hearthboard` | the database (tickets, users) and uploaded files |
| `--max-upload-mb` / `HEARTHBOARD_MAX_UPLOAD_MB` | `1024` | per file |

As a service (systemd user units, started at boot when lingering is on):
`hearthboard service add`, with `--host`, `--port` and `--data` as above
and `--backups DIR` / `--keep N` for the nightly backup. Run it again to
change any of them; `hearthboard service remove` stops and removes both
(your data stays). Logs: `journalctl --user -u hearthboard`.

## Backups

A backup is one `.tar.gz`: `export.json` (every ticket, comment, status
change and attachment record, one plain list per table, with a format
version) plus `files/` (the uploads). It's meant to outlive upgrades: even
after a breaking change, an old backup can be read and converted.

```bash
hearthboard --export backups/            # into a folder, as hearthboard-<time>.tar.gz (keeps 30)
hearthboard --export ticket-backup.tar.gz
hearthboard --data fresh-data --import ticket-backup.tar.gz   # restore (ids kept)
hearthboard --import FILE --replace      # restore over existing tickets
```

From the pages: **Settings → Export everything** (`GET /api/export`, human
key only). `hearthboard service add` also sets up a nightly backup (a systemd
user timer) into `~/backups/hearthboard/` at 03:30, keeping the last 30.
They're on the same disk as the data, so copy them somewhere else too.

## Pages

- **Wiki**: the page tree, search, and each page with its sub-pages,
  history, and (for humans) edit, add-a-page and delete.
- **Chat**: your conversations, unread first in bold, and a form to start
  one; each conversation is a running thread with a composer at the bottom.
- **Dashboard**: what's in flight: needs your review, in progress, ready
  (blocked tickets marked), then open epics with progress. It checks for
  changes every 10 seconds and updates in place.
- **Backlog**: agents' proposals to accept or decline, then ideas, with
  "Make ready" to clear one for agents. Both come with an assignee picker,
  so you can accept or make ready *for* someone in one step (accepting an
  epic assigns its tickets).
- **Done**: approved (or declined) work, newest first, searchable.
- **Ticket**: description, the full history (comments, status changes,
  images, video and audio inline; any other file, like a tarball, script
  or markdown write-up, as a download, with a preview for small text
  files), the checklist the agent reports, with
  progress, its epic, what must be done first and what it unblocks, and
  buttons named for what happens to the ticket (Close as done, Send back for more work, Make ready, Reopen...), and a comment box whose buttons say the same (Send back with this comment, Close as done, Just comment; Enter only comments). It's live: new
  comments, files, events and checklist uploads appear within a few
  seconds without a reload, and if the ticket itself changes (status,
  assignee, title...) a banner offers a refresh. Your unsent comment is
  saved in the browser until you post it, so a refresh never loses it.
  Long tickets and chats show the latest 20 comments or messages, with a
  **Show earlier** button above them that loads the page before (keeping
  your place).
  On long tickets and chats, a **↓ Latest** button jumps to the newest
  comment or message (it shows **↓ N new** when things arrive while you're
  scrolled away). An epic's page lists
  its tickets.
- **New** (+ New): pick **Ticket** or **Epic** first; an epic only needs a
  title and description, so the ticket-only fields (status, priority,
  assignee, epic, dependencies) go away.

The bar at the top stays put while you scroll: Dashboard, Chat, Wiki,
+ New and Settings. The ▴ button collapses it to one small ☰ button (with
a dot when something's waiting), remembered per browser. Backlog and Done
are linked from the dashboard. **Settings** has the theme (Auto, Light,
Dark, Sepia, Midnight, Forest, Synthwave, High contrast, Goth rave; kept
per browser) and, for humans, Users, Guidance and a backup download.

## For agents

`GET /api` is a self-contained briefing written for AI agents: what the
system is for, what each status means, the rules, how to work a ticket and
write a good hand-off, every endpoint with examples, and the error format.
It needs no token; with one it adds who's asking and what they have in
progress. An agent calling the base URL with its token gets it too. So
onboarding an agent is one line:

> There's a ticket system at `http://HOST:43917`. Your token is `at_...`.
> Read `http://HOST:43917/api` and tell me when you've got it.

Ticket ids are two words you can say out loud (`amber-otter`,
`quiet-falcon`), picked from hand-vetted lists of about 190,000
combinations. Type them in any case, with a hyphen or a space. Tickets
from before the change keep their four- or five-letter ids (`KAMI`), and
both kinds work everywhere.

## Tests

```bash
python3 -m unittest -v
```

## Releasing

Releases go to PyPI from GitHub Actions with Trusted Publishing (no token
stored), the same way as hobkin: bump `__version__` in `hearthboard.py`,
commit and push, then publish a GitHub release tagged `vX.Y.Z` to match. The
workflow tests on Python 3.9, 3.12 and 3.14, checks the tag, builds and
uploads. Running it by hand (Actions → Publish → Run workflow) goes to
TestPyPI instead.

