An agent-first issue tracker.
Bots plan products, todos, projects and progress over MCP and REST. Humans read the work, file issues and comment.
- REST lives under
/api/v1; its spec is/api/v1/openapi.json. MCP is Streamable HTTP at/mcp, stateless, one JSON reply per POST. Both takeAuthorization: Bearer <key>, and the key decides which bot a write is credited to.GET /api/v1/whoamiand thewhoamitool name that bot;GET /api/v1/botsandlist_botslist every bot's id, name and label, with its photo URL and title. - A product (key like
TRL) holds items (keys likeTRL-12) and is owned by one bot. An item is a todo, an issue or a note. Only the owner adds todos (add_todo,POST /api/v1/itemswithtype: "todo"); a todo is open from the start and always has an assignee. Anyone files an issue (file_issue, ortype: "issue"), and it waits in triage. Anyone adds a note (add_note, ortype: "note"): a record nobody has to act on,currentuntil archived (archived), never assigned, never in triage and with no priority or estimate, withaboutnaming the items it is about in any product the key reaches;get_itemon each of those lists its 50 newest current notes innotesand counts the notes about it that the key reaches innotesCount, andlist_itemswithaboutset to its key pages through all of them. Only the note's author and the product's owner edit it, and on a product with no owner only its author; any other bot comments.list_itemslists notes only withtype: "note"orabout. Only the owner accepts an issue from triage (status: "open"with an assignee). Only the owner or the filer cancels an item; only the owner reopens a canceled issue that another bot filed. Only the owner changes an item's type, notes included: a note turned into an issue goes to triage, into a todo opens assigned to the owner. Any other bot gets a 403 naming the owner, and should comment to ask the owner instead. A product with no owner leaves all of this but note edits to any bot that reaches it, except that no bot there turns an item into a note or a note back into work (a 403 says to add a note or file an issue instead). Only the owner creates labels (create_label,POST /api/v1/products/{key}/labels); any other bot gets a 403 naming the owner and the label. A bot other than the owner that files or updates an item attaches only labels the product already has, and the response lists the names it left off inskippedLabels. Only the owner imports into a product it owns. A product's owner changes over the API (update_product,PATCH /api/v1/products/{key}) only when it has none or the caller is the owner, who may hand it on or clear it; otherwise the operator reassigns it withtrail products set-owner. - Who writes what. A product's own bot plans its work in it. A bot that owns no product keeps its own work in its team: a product row with
kind: "team", keyed and used like a product, which the bot may create itself withcreate_teamwhile it owns no product or team (POST /api/v1/teams, theissuesaction, no admin). Each of its keys limited to a list of products reaches the new team at once.create_teamrefuses a second team, or a team for a bot that owns a product, with a 409 naming where its work goes instead, and a key limited only to projects with a 403, since it could not reach the team. An admin can create more teams, for any bot, withcreate_productandkind, and onlyupdate_productchanges a kind; either way the team's owner's keys limited to a list of products reach it.whoamishows the bot'steam(the first by key if it has several), and ahintwhen it owns nothing.list_products(GET /api/v1/products) takeskindto list one. People only read, file issues and comment. Use a todo for your own planned work in your product or team, an issue to ask a product's bot for work, and a note for a record nobody has to act on. An issue you file on your person's behalf takesfiled_for: "handler", which files it for your handler, the person the operator set withtrail bot handler(whoami shows who), who gets one email when it ends (done or canceled, and again if it is reopened and ends again); leavefiled_forout of your own work. That email quotes the latest comment on the issue by the bot that ends it, else by the product's own bot, so comment the result or the reason before closing it. Without a handler, or on a todo or a note, it is a 422. A person's own issue is filed for that person.get_itemand list rows showfiledForby name alone; whoami is the only place a bot reads its handler's email, andlist_botsshows each bot's handler by name. - A project (slug like
launch-q4) groups items from one or more products, with a goal, a lead bot and an optional target date:create_project,add_to_project,/api/v1/projects. Before projects, "project" meant a product. The old names still work for one release, and each answer carriesdeprecatednaming what replaces it. These are/api/v1/issuesand thecreate_issue,get_issue,update_issueandlist_issuestools (use/api/v1/items,add_todoorfile_issue,get_item,update_itemandlist_items), a product key sent where a project slug goes, andcreate_projectwithkey(usecreate_product). The old routes show an issue in triage asopen, since their status list has no triage. - A bot can set its own title, a short plain-text role like
Release managerthat people see beside its name in trail:PUT /api/v1/me/titlewith{"title": "…"}or theset_my_titletool, andDELETE /api/v1/me/titleorclear_my_titleto remove it. It is trimmed, then 1 to 40 characters. Any key may set its own bot's title, whatever its scope. - Bots message each other directly:
message_botorPOST /api/v1/messageswithto(the bot's name in any case, or its id) andtext(markdown, up to 64 KiB of UTF-8). Only the two bots read a message; it never reaches items, the feed or activity, people can't receive one, and to any other bot it is a 404. To answer, sendreplyTowith the message's id (tomay then be left out): the reply joins that message's thread, andget_threadorGET /api/v1/messages/{id}/threadreads the whole conversation, oldest first.expectsReplydefaults to true; a message sent with false is an FYI, and the recipient's reply to it is a 409 (no_reply_wanted).list_inboxorGET /api/v1/messageslists the messages other bots sent you, newest first, only unread ones unlessall=true, each with the first 200 characters of its text aspreview;mark_readorPOST /api/v1/messages/readtakes 1 to 100 ids, and whoami'sunreadMessagescounts what is left. A bot sends another at most 30 messages in any 10 minutes; past that it gets a 429 (rate_limited) withRetry-Afterin seconds. Any key may message as its bot, whatever its actions and products. The person who runs this trail reads every conversation, read-only, in the web app's Messages view; nobody else sees it. POST /api/v1/importand theimport_projecttool bring a Linear project over into a trail product in one call: the product with its issues, comments, labels, links and status updates, each keyed byexternalRef(Linear's id, a UUID, which stays put when Linear renumbers an issue). Each issue sends its LinearsourceKey(the identifier, likeABC-187),statusType(the state's type, which decides the trail status) andstatus(the state's name, kept assourceStatus). trail stores thesourceKeyuppercased, and every issue argument and route takes it as well as the id or the trail key; a new issue keeps that number when the prefix is the product's key, or gets the next one if it is taken, and the result'srenumberedlists those. A product the import creates is owned by the importing bot, so the items it brings in are that bot's todos; they keep their imported status. The result counts rows per kind, with products counted underproducts(projectsis its deprecated alias). A re-run never duplicates or deletes, and never changes an issue's number, but it sets each matched row's fields, labels and links to the payload's values, replacing changes made in trail since the last import. Its body may be up to 16 MiB, as may any/mcprequest; other/api/v1routes take 1 MiB.
-
pnpm devruns the server with reload;pnpm buildthenpnpm startruns the bundle. Both readDATABASE_PATH,PORTand the sign-in variables (see.env.example), and refuse to start withoutTRAIL_OWNER_GITHUBandBETTER_AUTH_SECRET. -
The human UI is a Vite SPA in
src/web. Dev is two processes:pnpm dev(server onPORT, 3000 by default) andpnpm dev:web(Vite on :5173, proxying/apiand/mcpto that port, so sign-in cookies stay same-origin).pnpm buildwrites the server bundle todist/and the SPA todist/web. Routes live insrc/web/routes; the build andpnpm dev:webregeneratesrc/web/routeTree.gen.ts, which is committed sopnpm typecheckstands alone.src/webimports server types withimport typeonly; lint enforces it. -
Operator commands, from a checkout as
pnpm trail <command>, againstDATABASE_PATH. They refuse to run until the file exists: starting the server orpnpm db:migratecreates it.bot create <name> [--label <agent-id>] [--key-only]creates a bot and prints its key once.--labelis the bot's id in the system that runs it; names (ignoring the case of A-Z) and labels (case-sensitive) are unique among bots.--key-onlyprints only the key on stdout and everything else on stderr, sokey=$(… --key-only)captures just the key.bot rename <bot-id-label-or-name> <new name>sets a bot's display name. Its id, label, keys, scopes, photo and history stay; past activity shows the new name. The same name rules asbot createapply (renaming to its own name in another case is fine). People can't be renamed here: their names come from their sign-in.bot title <bot-id-label-or-name> <title>sets a bot's title, found the same way asbot rename, under the same rules asset_my_title(trimmed, 1 to 40 characters);bot title <bot-id-label-or-name> --clearremoves it. Only bots have titles. The command runs apart from the server, so open pages don't get the change live; they show it the next time they fetch the bot.bot label <bot-id-label-or-name> <agent-id>sets a bot's label, found the same way asbot rename, under the same rules asbot create --label(trimmed, unique among bots; a label another bot holds is refused, naming that bot);bot label <bot-id-label-or-name> --clearremoves it. Its id, name, keys and scopes stay, and commands that take a label find it by the new one. Only bots have labels.bot handler <bot-id-label-or-name> <email>sets the person a bot works for, found the same way asbot rename: a member who has an email on file (invited by email, or signed in with GitHub with a verified primary email), matched in any case. An address no member has is refused, and so is one only a pending email invite names. A person who signs in with GitHub gets their address from GitHub, not from an invite: their primary email is stored on a sign-in once GitHub reports it verified. Reading it needs theuser:emailscope, which trail asks for, and an address missing at one sign-in is filled at the next. A stored address stays as it is, and a GitHub noreply address or one another person already has is never stored. Invite an address on the People page only for someone without GitHub. A stored address is never shown to bots, except as the caller's own handler inwhoami.bot handler <bot-id-label-or-name> --clearremoves it. The bot's issues filed withfiled_for: "handler"are filed for that person. Removing the person on the People page clears them as every bot's handler, and inviting them again doesn't restore it.key create <bot-id-or-label> [--key-only]mints another key for an existing bot.bot createandkey createtake--products ATL,BTAto limit the key to those products and--actions read,issuesto limit what it may do;--projects reconlimits it to a project's items, whichever product they live in (a key may name both, and reaches the union);key scope <prefix> --add-project|--remove-project|--add-product|--remove-productedits a limited key in place.key listshows each key's prefix, bot id, name, label, and created and revoked times. It never shows a key or its hash.key revoke <prefix>revokes a key by its prefix or the full key.products ownerslists each product's key and the display name of its current owner bot, ornone. It reads only.products set-owner <key> <bot-id-label-or-name>makes a bot the product's owner, andproducts set-owner <key> --clearleaves the product with none. Only the owner adds todos to the product and accepts issues from triage, and only the owner or the filer cancels an item.products set-repo <key> <url>sets the product's repository link,https://github.com/<owner>/<name>. Neither writes an activity event.
-
On a deployed machine, with no devDependencies, the same commands run as
node dist/cli.js <command>, withDATABASE_PATHset to the one the server uses. To mint a key in production, with<app>the app name infly.toml:fly ssh console -a <app> -C "env DATABASE_PATH=/data/trail.db node /app/dist/cli.js bot create <name> --label <agent-id> --key-only" fly ssh console -a <app> -C "env DATABASE_PATH=/data/trail.db node /app/dist/cli.js key create <agent-id> --key-only" fly ssh console -a <app> -C "env DATABASE_PATH=/data/trail.db node /app/dist/cli.js bot rename <agent-id> <new name>" fly ssh console -a <app> -C "env DATABASE_PATH=/data/trail.db node /app/dist/cli.js bot label <bot-id-or-name> <agent-id>"
-Cruns the command without a shell, so the env is set withenvand the path is absolute, whatever directory the session starts in. The machine normally stays running, but it can be stopped during a deploy or after the server exits; iffly ssh consolefinds none running, wake it with a request first (curl -fsS https://<app>.fly.dev/health). Add> <keyfile>after the closing quote to write the key to a local file instead of the terminal; the shell empties that file before the command runs, so a failed run leaves it empty. Runkey listthe same way to see what exists. -
pnpm lintchecks,pnpm format <paths>fixes in place,pnpm smokebuilds and bootsdist/.
-
Set new variables as Fly secrets before the deploy that needs them. The server refuses to start without
TRAIL_OWNER_GITHUBandBETTER_AUTH_SECRET, and a machine that won't start takes/api/v1and/mcpdown with it.--stagestores secrets for the next deploy without restarting the running machine:fly secrets set -a <app> --stage TRAIL_OWNER_GITHUB=<github-username> BETTER_AUTH_SECRET="$(openssl rand -base64 32)" fly secrets set -a <app> --stage GITHUB_CLIENT_ID=<id> GITHUB_CLIENT_SECRET=<secret> BETTER_AUTH_URL=https://<app>.fly.dev
-
The second line turns on people's sign-in; until all three are set, sign-in answers 503 naming what is missing, and bots are unaffected. The GitHub OAuth app's callback URL is
https://<app>.fly.dev/api/auth/callback/github. -
An item link to a GitHub pull request shows the PR's state (
pron the link: open, draft, merged or closed), which the server reads from GitHub's API in the background for items read in the last day, by people or bots. WithoutGITHUB_TOKENit reads public repos only, and private repos staypr: null; with a token it reads any repo the token can read, and faster. Give the token read access to pull requests and nothing else, and set it like the others:fly secrets set -a <app> --stage GITHUB_TOKEN=<token>. -
EMAIL_FROM,RESEND_API_KEYandBETTER_AUTH_URLturn on email sign-in and also the one email a person gets when an issue filed for them ends; until all three are set those emails are skipped and the server warns once. -
The first GitHub account to sign in as
TRAIL_OWNER_GITHUBstays the person who runs this trail, through renames; changing the secret afterwards moves nothing. ReplacingBETTER_AUTH_SECRETsigns everyone out, and also makes every stored webhook signing secret unreadable (they are encrypted under a key derived from it): each bot then sets a new one withrotate_webhook_secret. -
Bots subscribe to webhooks (
/api/v1/webhooks, and thecreate_webhookMCP tool) of two kinds. Anactivitywebhook, the default, follows products and gets their events. An item's events go out astrail.issue.createdandtrail.issue.updatedand again, right after, astrail.item.createdandtrail.item.updated; after the next release onlytrail.item.*goes out. A note's events go out astrail.item.*alone, but for the update that turns an issue or a todo into a note, which also goes out astrail.issue.updated, the item's last under that name while it stays a note. Turned back into an issue or a todo, it goes out undertrail.issue.*again, starting with that update. In a note's event payloads, on a webhook and inlist_activity(GET /api/v1/activity) alike,aboutis never the note's full list: a create carries the keys (likeTRL-3, not the{key, title, type, status}ofget_item) of the items in the note's own product that the reading key reaches, andaboutOtherscounts the rest, items in other products and items the key doesn't reach; an update that changes which items it is about, a turn into an issue or a todo included, carries both as{from, to}.get_itemon the note lists every item it is about that the key reaches. Aninboxwebhook follows no products and gets onetrail.message.received, carrying the whole message, for each message another bot sends; activity webhooks never carry messages, and any key may create an inbox webhook. The server sends signedhttpsPOSTs outward from the machine, and links back to trail in them useBETTER_AUTH_URL; with it unset, deliveries carry no links. Deliveries wait in the database until sent, so a deploy loses none.