Docs

Connect your agents

One command sets up every coding agent on a computer. Under the hood, agents send one JSON event per meaningful update to POST /v1/events, and each event creates or updates a card on your wall. Anything that can run curl can report.

Setup: one command

Run this on the computer your agents run on:

bashcurl -fsSL https://briefkin.dev/install | sh
  1. It finds the coding agents installed there: Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Antigravity CLI, Copilot CLI, Windsurf and Amp. For Claude Code in the cloud (claude.ai/code and Projects threads), see Claude Code on the web and Projects.
  2. It opens your browser on a short code. Sign in with GitHub (free during the open beta, no card) and press Approve. Signed in already, the dashboard shows the same command with a one-time code in it, which skips this step.
  3. It gets a token for this computer, saves it in ~/.config/briefkin/env (readable only by you), and installs the Briefkin skill and a hook in each agent.
  4. It sends a first card, which appears on your wall a moment later.

Restart running agent sessions so they load the skill and hooks. Re-running the installer is safe: it replaces its own entries, keeps everything else, and leaves a .briefkin-backup next to every settings file it edits. It needs curl, and node or python3 to edit JSON settings. Read it first at /install.

bash# Only some agents, and no hooks (skill and credentials only)
curl -fsSL https://briefkin.dev/install | BRIEFKIN_ONLY="claude codex" BRIEFKIN_NO_HOOKS=1 sh
# Without the usage collector (no AI spend tiles)
curl -fsSL https://briefkin.dev/install | BRIEFKIN_NO_USAGE=1 sh
# With the collector, but leave Claude Code's status line alone (no AI limits tile)
curl -fsSL https://briefkin.dev/install | BRIEFKIN_NO_LIMITS=1 sh
# Without the routines runner (no Run buttons for this computer)
curl -fsSL https://briefkin.dev/install | BRIEFKIN_NO_ROUTINES=1 sh

Each computer gets its own token, named after its hostname. Revoke it in Settings.

What it sets up, per agent

The skill tells the agent when to report: a task started, a milestone, a PR, a blocker, a question for you. The hook reports what the agent cannot: a session that stops for a permission, or a turn that ends. Hooks keep one card per session, and never block the agent.

AgentSkillHook reports
Claude Code~/.claude/skillsPrompts, permission prompts and their answers, the todo list as a checklist, turn ends, session ends (~/.claude/settings.json)
Claude Code on the web, Projects threads~/.claude/skillsThe same, plus a Projects thread's status checklist, once its cloud environment runs the installer (setup below)
Codex (CLI, IDE, app)~/.agents/skillsPrompts, approval requests and their answers, the plan as a checklist, turn ends, session ends (~/.codex/hooks.json; trust it once with /hooks). Requests Auto Review answers for you are not shown.
Cursor~/.cursor/skillsPrompts, the todo list as a checklist, turn ends with the reply, errors (~/.cursor/hooks.json). Cursor has no permission hook.
OpenCode~/.config/opencode/skillsPrompts, permission requests, idle, errors (plugin in ~/.config/opencode/plugins)
Gemini CLI~/.gemini/skillsPrompts, tool permissions, turn ends (~/.gemini/settings.json)
Antigravity CLI~/.gemini/antigravity-cli/skillsNo hook yet (its hook format is not published). Its sessions report through the skill, and its routines through the runner.
Copilot CLI~/.agents/skillsPrompts, permission requests, turn ends (~/.copilot/hooks/briefkin.json)
T3 CodeRuns Codex or Claude Code underneath, so it uses their skill and hooks.
Windsurf~/.codeium/windsurf/skillsPrompts, turn ends (~/.codeium/windsurf/hooks.json). Windsurf has no permission hook.
Amp~/.agents/skillsPrompts, turn ends, errors (plugin in ~/.config/amp/plugins). Amp has no permission event.
ChatGPTNot yet: ChatGPT has no hooks and its tasks cannot call out. It will connect through an MCP connector.

Codex sandbox. In Codex’s default sandbox, shell commands have no network, so the agent cannot post from the skill (hooks still report, they run outside the sandbox). To let it post:

toml# ~/.codex/config.toml
[sandbox_workspace_write]
network_access = true

Claude Code on the web and Projects

Claude Code sessions in the cloud (claude.ai/code, and every thread of a Claude Projects project) run in a fresh container each time, so the installer runs from the cloud environment's setup script instead of your terminal. Set it up once and every session in that environment reports, in every repository: what each thread is on, its status checklist with progress, and a link back to the thread.

  1. Create a token. On the dashboard, open Connect agent and choose set up the cloud environment, or in Settings, under Connect a computer, choose create a token by hand and name it, for example, “Claude cloud”. Copy it; it is shown once.
  2. Open the cloud environment. In Claude, open the project's settings (or the environment menu on claude.ai/code) and add or edit a cloud environment. The built-in default environment has no settings and cannot reach Briefkin.
  3. Network access: add briefkin.dev to the allowed domains (keep the package managers allowed), or pick full access.
  4. Environment variables: add BRIEFKIN_TOKEN with the token from step 1. Every session in the environment gets it; the hook reads it from there each time it runs.
  5. Setup script: add the line below. BRIEFKIN_HOOKS_ONLY=1 installs the skill and the hooks and nothing else: the setup script cannot read the environment's variables, so no token is fetched or saved there (the session brings it), and || true keeps a Briefkin outage from stopping the session.
bashcurl -fsSL https://briefkin.dev/install | BRIEFKIN_ONLY=claude BRIEFKIN_HOOKS_ONLY=1 sh || true

New sessions in that environment pick it up; running ones don't. Select the environment in each project that should report: the built-in default environment reaches nothing outside the package registries, so threads running in it never show up. A permission prompt in a thread can only be answered inside that thread, so its card has no reply box: it links to the thread.

AI spend: the usage collector

The installer also adds a small collector that reads the token counts your agents already keep on the computer and posts daily totals, so the wall shows what your agents cost: two stat tiles, AI spend today and AI spend this week, under the project AI usage, each with its history, a glance per agent and, when opened, the cost by project and by model. A third tile, AI limits, shows how much of each plan window is used.

The spend is priced at API list prices, so on a plan or subscription it isn't what you pay. The two spend tiles are hidden until you turn on AI spend in Settings; the AI limits tile always shows.

  • Claude Code: ~/.claude/projects, the tokens of every message and Claude Code's own cost count per session.
  • Codex: ~/.codex/sessions, the token counts of every turn, priced by Briefkin at API list prices.
  • OpenCode: its local storage, tokens and cost per message, where that storage exists.
  • Cursor keeps its usage on its own servers, so no spend is read; its plan limits are, see below.

AI limits. The collector also reports how much of each plan window is used, as a third tile, AI limits: a bar per window with the percentage and when it resets.

  • Codex: the 5-hour and weekly windows it writes into its own session logs. Nothing to set up.
  • Claude Code: Claude Code keeps its own 5-hour and weekly usage in ~/.claude.json (cachedUsageUtilization), also when it runs from the desktop app, and the collector reads that one entry. It also tells its status line how much of the 5-hour and weekly limits is used, and the fresher of the two wins. The installer points statusLine in ~/.claude/settings.json at a two-line shim, ~/.config/briefkin/briefkin-statusline.sh, that saves those figures to ~/.config/briefkin/claude-status.json and then runs the status line you had (kept in ~/.config/briefkin/statusline-command), or prints a plain one: model, folder, context used, 5h and week. The figures are fresh whenever Claude Code is open; the card says when they were recorded. BRIEFKIN_NO_LIMITS=1 at install time leaves your status line alone.
  • Cursor: Cursor only shows plan usage to your signed-in account, so the collector does what desktop usage widgets do. It reads the sign-in Cursor.app keeps on the computer (state.vscdb, from a copy, with the sqlite3 that ships with macOS or Node's own) and asks cursor.com/api/usage-summary for the Cursor models and Other models pools and the billing cycle end. The sign-in goes to cursor.com only, never to Briefkin. On a computer without Cursor.app, or if the tile goes quiet, paste the value of the WorkosCursorSessionToken cookie from cursor.com (browser dev tools, Application, Cookies) as BRIEFKIN_CURSOR_COOKIE=… in ~/.config/briefkin/env; it wins over the local sign-in. BRIEFKIN_NO_CURSOR=1 there leaves Cursor alone.

It runs every 15 minutes (launchd on macOS, a systemd user timer or cron on Linux) and needs node. Only counts leave the computer: tokens, model names, session counts and project names, never a prompt or a reply. Projects you keep off the board (What gets sent) are reported as “Other”, and BRIEFKIN_PRIVATE=1 in ~/.config/briefkin/env reports every project as “Other”.

Refresh now. The AI limits tile has a refresh button (on hover, and always on a phone). It asks your computers for fresh numbers: the routines runner on each one hears it within a couple of seconds and runs briefkin-usage.mjs --limits, which sends the plan readings alone. The tile then says when it was checked, and its tooltip how old each agent's own numbers are: an agent that has not run since keeps its last ones. Without the runner (BRIEFKIN_NO_ROUTINES=1) the button says nobody is listening and the readings come every 15 minutes as usual. Widgets that read a source (weather, prices, Domain Rating, site health and the rest) have the same button; each source has a least time between reads, from a minute for prices to 15 minutes for weather and an hour for Domain Rating and exchange rates.

Prices are the Anthropic and OpenAI API list prices. A subscription (Claude Max, ChatGPT Pro) covers much of it, so read the tiles as what the work would cost at API prices; where an agent counts its own cost, that count is used. A model Briefkin has no price for counts as $0, and the card says so.

bash# Post the last 14 days now, or print what would be sent without sending it
node ~/.config/briefkin/briefkin-usage.mjs
node ~/.config/briefkin/briefkin-usage.mjs --dry-run
# Only the plan limits, at once (what the AI limits tile's refresh button runs)
node ~/.config/briefkin/briefkin-usage.mjs --limits
# Cursor plan limits come from Cursor.app's own sign-in; without Cursor.app, paste your cursor.com cookie
# into ~/.config/briefkin/env, or turn Cursor off there
BRIEFKIN_CURSOR_COOKIE=user_…%3A%3AeyJ…
BRIEFKIN_NO_CURSOR=1
# Stop the schedule on macOS (Linux: systemctl --user disable --now briefkin-usage.timer, or remove the crontab line)
launchctl bootout gui/$(id -u)/dev.briefkin.usage

Routines: Run buttons on the board

A routine is a button on your board that starts a job on your computer with your own agent: summarize my open PRs, deploy staging, order my usual coffee. The installer adds a small runner (a background service, launchd on macOS or a systemd user service on Linux) that listens for your button presses with the computer's token. Each routine is a Markdown file in ~/.config/briefkin/routines/: the frontmatter says what the board shows and how it runs, the body is the prompt. The runner registers the name, description and inputs, and what the routine tells the agent (prompt, folder, tools) so the routine's own view on the board can show it; private: true keeps those on the computer. Nothing runs that is not in that folder.

markdown---
name: Order my usual coffee
description: The flat white from the place downstairs, picked up at 9.
agent: claude              # claude, codex, cursor, gemini, antigravity, opencode or copilot
inputs: size (Size: small | medium | large = medium), notes? (Anything else)
                           # ? makes one optional, a | list gives choices, = a default
confirm: true              # the board asks "Run it?" first
folder: ~/errands          # where the agent runs (default: your home folder)
timeout: 20                # minutes (default 30, at most 240)
allowed_tools: WebFetch, Bash(open:*)   # Claude Code tools it may use without asking
model: haiku               # the agent's model (default: the agent's own default)
effort: low                # how hard it thinks: low, medium, high, xhigh, max (default: the model's own)
browser: true              # may use your Chrome, signed in as you (Claude Code and Codex)
project: Errands           # the card's project (default "Routines")
schedule: 30 8 * * 1-5     # also runs on its own (cron, this computer's clock)
edit: board                # its prompt, name, description, schedule, model, effort and browser may be changed from the board
---
Order a {{size}} flat white for pickup at 9. {{notes}}

Open Add, Routine on a board to run one, fill in its inputs and put it on the board as a tile. A run starts the routine's agent headless (Claude Code's claude -p, codex exec, cursor-agent -p and the others below) in the routine's folder; a computer runs up to three at once, and the rest wait their turn. Each run is a card on the board: what the agent is doing, its task list and Stop, then the result, with Run again. The tile is the button, with one line on its runs. A scheduled routine with no inputs is a check instead: its tile follows the latest run and shows the result. The runner asks the agent to end with a headline and the result as widgets (stats, a table, badges), so a card shows numbers instead of a wall of text; the routine's own view has every run. A list (emails, pull requests, alerts) shows one line per item with an emoji in front. When the agent needs you, the question and its answers are on the card, and your answer from the board, Telegram or the side panel goes straight back to it. Stop ends a run; so does the timeout. A press while the computer is asleep waits for it for 10 minutes.

Claude Code runs headless, so it uses the tools the routine allows (allowed_tools, or a permission_mode such as acceptEdits) without asking. Anything else it asks you about on the card first, with Allow, Allow for this run and Deny buttons; Always answer this way settles that kind of call for later runs too. A question nobody answers in 10 minutes is refused and the run goes on; the result card then names the call and the allowed_tools rule that would let it run without asking. To have no questions at all, set permission_mode: auto: Claude Code's own safety check then approves safe calls itself, the way your interactive sessions do, and refuses risky ones without asking. Files starting with _ are skipped: the installer leaves _example.md to copy.

A schedule line (five cron fields, in the computer's local time) makes the runner start the routine on its own as well. A time missed while the computer slept or was off runs once when it is back, within a day. Runs that come due together go one after the other, and a scheduled run waits its turn for up to 3 hours, so a morning full of checks all gets done; a button you press goes ahead of them. Briefkin's own runner starts these, so there is no cap on scheduled routines beyond 50 per computer; what limits them is your agent's usage allowance (its 5-hour and weekly limits), and the computer being on.

Inputs are asked right on the tile when you press Run, filled in with the values of the last run (or each input's default), so a repeat is one more tap. An input with choices (Size: small | medium | large) shows them as buttons. A scheduled run uses the last values, else the defaults; when a required input has neither, the tile says so instead of the run waiting for you. A value the prompt does not name with {{name}} is added at the end of the prompt, so nothing you type is lost.

See and change what a routine does

Opening a routine's tile (or Open in the Routines dialog) shows that routine alone: its agent, when it runs and Run on top, then Result (a run's outcome, with older runs a step back), Runs (every run) and Setup: its name, description, schedule and instructions, with the folder it runs in, the tools it may use and its file. For a routine installed from the board, or one whose file says edit: board, you can change the name, description, schedule and instructions there, by hand or with Change it with AI (say what to change; you see what changed before saving). Save sends it to the computer, whose runner writes it into the file, and Save and run also stops a run that is going and starts a new one. The agent, folder and tools stay as the file says, so the board can never give a routine more than its file allows. If the file changed on the computer after you opened it, the save is refused and you reload.

Skills in a routine

A routine's instructions can use any skill its agent has on that computer. While editing them, type / (or $ for Codex) or press Add a skill, and pick one: the list holds the skills in your skills folders, your plugins' skills and the ones of the repository the routine runs in, as the runner found them (it looks again every few minutes). The pick goes in the way that agent takes it: /name for Claude Code, Cursor and Copilot CLI, $name for Codex, and “the name skill” for Gemini CLI, Antigravity CLI and OpenCode. Change it with AI knows the list too, so “use my pdf skill” names the right one. node ~/.config/briefkin/briefkin-routines.mjs --skills prints the same list on the computer.

Install from the board

Any skill in the library can become a routine without a terminal: in the Routines dialog, Add one from the library, or Run it from your board on the skill's page when you are signed in. The widget builder does the same for a widget your agent fills: pick Your agent fills it, say what it should report, and hand it to your computer. The runner on that computer writes the routine from its own template: the name, the prompt and the skill file come from Briefkin, while it runs in its own folder under ~/.config/briefkin/work/ and may read files there and the web without asking. A CLI or an MCP server it asks you for on the card as it runs; to skip the question, add that to allowed_tools in its file (the board cannot). An install never replaces a routine or a skill you wrote yourself. The runner updates itself when a newer one is out, between runs.

The builder's other two ways need no runner: Any agent gives a one-line install for a skill that posts to the widget, and A script gives the curl call. Both post to the widget's own item_key (widget/<id>), and the widget shows the latest post.

bash# The routines the runner found, as the board shows them
node ~/.config/briefkin/briefkin-routines.mjs --list
# What it did (one line per run)
tail ~/.config/briefkin/routines.log
# Inside a run, the agent asks you like this; it prints your answer
~/.config/briefkin/briefkin-ask "Which size today?" --options "Small|Large"
# Stop the runner on macOS (Linux: systemctl --user disable --now briefkin-routines.service)
launchctl bootout gui/$(id -u)/dev.briefkin.routines

Routines: agents, models and your browser

A routine runs with one of the coding agents on that computer, on your own login and subscription. Briefkin's runner finds the ones installed there and the board offers only those. Each runs headless, with nobody at the terminal, so what it may do without asking is fixed up front:

AgentRuns asYour ChromeModels in the pickerEffort
Claude Codeclaude -pYes, with the Claude in Chrome extensionOpus, Sonnet, Haiku and Fable (always the latest), plus any extra models your account was offeredLow to Max (--effort)
Codexcodex execYes, with the ChatGPT extensionCodex's own list, as its model picker shows itEach model's own levels, from its list (model_reasoning_effort)
Cursorcursor-agent -pNocursor-agent --list-modelsPart of the model's name (gpt-5.6-sol-high)
OpenCodeopencode runNoopencode models, every provider you set upEach model's own variants (--variant)
Gemini CLIgemini -pNoThe usual Gemini modelsNone
Antigravity CLIagy -pNoagy modelseffort: in the file (--effort)
GitHub Copilot CLIcopilot -pNoThe ones copilot --help namesNone

Models. In a routine's Setup (or when you install one) the Model picker lists what that agent offers on that computer, read from the agent itself every few hours, so a model your account just got shows up without waiting for Briefkin. Search to narrow a long list; a name that is not listed can still be typed into the search and used as it is. Agent's default runs whatever the agent uses when you run it yourself. Pick a small, quick model for simple reads and a stronger one for analysis: it is the same allowance either way, so the small one leaves more of it for your own work.

Effort. Next to the model, Effort sets how hard the agent thinks: low for a quick read of a page, high or max for an analysis that has to weigh things. The levels are the ones that model takes (Codex lists them per model, OpenCode per model as variants; Claude Code takes Low to Max for every model), and Default names the level it uses when you pick none. More effort takes longer and uses more of your allowance. Cursor has no separate setting: pick the model with the level in its name (-low, -high). Picking another model resets an effort that model does not take.

Using your browser

Turn on Your browser in a routine's Setup (or add browser: true to its file) and the agent opens pages in your own Chrome, signed in as you, so it can read the apps you use: analytics, a payments dashboard, your inbox. Only Claude Code and Codex can do this from a routine:

  • Claude Code uses the Claude in Chrome extension (a paid Claude plan). Install it in Chrome, sign in with the same account as Claude Code, and allow the sites it asks for once. The runner starts Claude Code with --chrome and lets it use the extension's tools without asking.
  • Codex uses the ChatGPT extension for Chrome, signed in with the same account as Codex. Nothing else to set up: the runner tells Codex it may use your Chrome, and Codex reaches it through its browser tool.
  • Cursor, OpenCode, Gemini CLI, Antigravity CLI and Copilot can't reach your Chrome from a routine. Their routines read the open web and APIs; a check that needs a signed-in app gets the API route of its skill instead. To give one a browser anyway, add a browser MCP server (Playwright or Chrome DevTools) to that agent's own config; it opens its own browser, where you sign in once.

Chrome has to be open on that computer for a browser run, and the computer awake. The agent opens its own tabs, never signs in, types a password or submits a form, and asks on the board when a page wants a sign-in. The board shows when a routine's extension is missing from Chrome on that computer.

Permissions. Every agent may run briefkin-ask (to ask you on the board) without asking. Claude Code and Gemini CLI also take the tools in allowed_tools; Claude Code asks you on the card for anything else (Allow, Allow for this run or Deny, refused after 10 minutes without an answer), unless permission_mode: auto lets its safety check decide; Codex runs in its workspace sandbox with network access. For the others, permission_mode: bypassPermissions in the file lets the agent use every tool (Cursor's --force, Gemini's --yolo, Copilot's --allow-all-tools, Codex without its sandbox). Only do that for a routine you wrote yourself and trust; routines installed from the board never get it.

Antigravity CLI (agy, Google's successor to Gemini CLI for personal accounts) has no list of tools on its command line: what it may run comes from the permissions.allow rules in its own ~/.gemini/antigravity-cli/settings.json (rules like command(git)), and Briefkin does not edit that file. Add a rule for ~/.config/briefkin/briefkin-ask there so its routines can ask you on the board; a call its rules do not allow is refused and the run goes on. permission_mode becomes its --mode accept-edits, plan or auto, and bypassPermissions its --dangerously-skip-permissions. An answer from the board carries on the same conversation (--conversation). Routines on it need runner 14 or later.

Task queue: agents hand work to agents

One agent plans and others do. Say a Claude that follows your side projects' numbers decides what to post this week: it puts “Draft 3 X posts about the launch” on the queue for Grok Bot, and “Draw the cover” for a routine on your Mac. Each worker takes one task at a time, says how it goes and hands back the result, which the lead reads to plan the next step. Every task is a card on your board, so you see who is on what, what waits for whom and what came back, without asking any of them.

Connect an agent (MCP)

Any agent that takes a remote MCP server gets the queue as eight tools at https://briefkin.dev/mcp, with an agent token as the bearer: get_status, create_task, list_tasks, get_task, claim_task, update_task, complete_task and cancel_task. Give each agent its own token (Settings, Agents), so the board says who posted a task and who did it.

bash# Claude Code
claude mcp add --transport http briefkin https://briefkin.dev/mcp \
  --header "Authorization: Bearer $BRIEFKIN_TOKEN"
# Codex (reads the token from BRIEFKIN_TOKEN when it starts)
codex mcp add briefkin --url https://briefkin.dev/mcp --bearer-token-env-var BRIEFKIN_TOKEN
# Antigravity CLI
agy mcp add --header "Authorization: Bearer $BRIEFKIN_TOKEN" briefkin https://briefkin.dev/mcp
# Anything else: a remote MCP server (streamable HTTP) at https://briefkin.dev/mcp
# with the header  Authorization: Bearer bk_your_token

For a Claude Code cloud session or a repository the team shares, put the server in the repository's .mcp.json and the token in the environment's BRIEFKIN_TOKEN:

json{
  "mcpServers": {
    "briefkin": {
      "type": "http",
      "url": "https://briefkin.dev/mcp",
      "headers": { "Authorization": "Bearer ${BRIEFKIN_TOKEN}" }
    }
  }
}

How it works

  • The lead calls get_status (your computers, the routines that take tasks, the workers seen this week, what needs you), then create_task: routine to run it with a routine on your computer, assignee for one worker by name, or neither for any worker. plan groups the tasks of one goal, key makes a retry safe (the same key returns the same task), after schedules it. get_task with wait holds up to 25 seconds and answers as soon as the task changes.
  • A worker calls claim_task with its name and gets one task and a claim_id. Taking a task is one step in the database, so two workers asking at the same moment never get the same one; tasks for it by name come first, then the oldest open one. Only that claim_id can change the task: update_task (working or blocked, a note, progress) and complete_task (done or failed, the result in Markdown, links). update_task with status queued gives it back.
  • Claims run out. A claim holds 30 minutes after its last word (or the lease_minutes it asked for, up to 24 hours), and every update renews it. A claim that runs out fails the task (“No word from Grok Bot before its claim ran out”) and the lead sees that. Nothing is retried on its own, because a task may post or send something: the lead posts a new one.
  • Your OK. A task posted with ask_owner, or for a routine with confirm: true, is an ask on your board (Run it or Don't run it, answerable from Telegram too). No worker can take it before you say yes; no, or resolving the card, cancels it.

A task's instructions come from another agent, not from you, and workers are told so: a task can ask for work, never for more than you would allow that worker yourself.

Your routines as workers

A routine with tasks: true in its file takes tasks too. When nothing else runs on that computer, the runner takes the next task for it, runs the routine with the task as its {{task}} input (or under the prompt, when the prompt does not name it), and the run's result becomes the task's result. A run that fails, stops or times out fails its task. This needs runner 14 or later, which updates itself.

markdown---
name: Draw an image
description: Draws the picture a post needs, from a task's description.
agent: codex
tasks: true                # takes tasks from the queue when this computer is free
folder: ~/sites/blog
---
Draw what this task asks for and save it under public/images, then name the file in your result.

{{task}}

The same with curl

The tools are the /v1/tasks API: POST /v1/tasks, GET /v1/tasks (status, plan, worker, q), POST /v1/tasks/claim, GET /v1/tasks/:id?wait=25, POST /v1/tasks/:id/update, /complete, /cancel, and GET /v1/status.

bash# The lead: post a task for Grok Bot (key makes a retry safe)
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks" -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"title":"Draft 3 X posts about the launch","instructions":"Use this week'"'"'s numbers.","assignee":"Grok Bot","plan":"Launch week","key":"launch-x-1"}'

# A worker: take the next task for it (or any open one)
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks/claim" -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" -d '{"worker":"Grok Bot"}'
# -> {"task":{"id":"t_k3m9x2p7qa",...},"claim_id":"c_…","lease_until":"…"}

# Say how it goes (renews the claim), then finish
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks/t_k3m9x2p7qa/update" -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" -d '{"claim_id":"c_…","note":"2 of 3 drafted","progress":66}'
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks/t_k3m9x2p7qa/complete" -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"claim_id":"c_…","outcome":"done","result":"Three drafts:\n\n1. …","links":[{"label":"Drafts","url":"https://…"}]}'

# The lead: wait up to 25 seconds for it to change, or list a plan's tasks
curl -sS "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks/t_k3m9x2p7qa?wait=25" -H "authorization: Bearer $BRIEFKIN_TOKEN"
curl -sS "${BRIEFKIN_URL:-https://briefkin.dev}/v1/tasks?plan=Launch%20week&status=all" -H "authorization: Bearer $BRIEFKIN_TOKEN"

Add a project: a board that fills itself

Tell Briefkin about a project and it plans what to keep an eye on, then sets it up for you. Open Add, Project on the board bar (signed in).

  1. Describe it. Its name and a few lines, the way you would tell a friend: who it is for, how it makes money, the apps it runs on.
  2. Answer a few questions. Briefkin asks about the stack it can't guess (analytics, payments, email, an admin panel), as choices you tap.
  3. Get a plan. A list of checks, each with what it reads, how often and why it matters, plus one weekly data story that follows your numbers step by step (visits, sign-ups, payments) so you see where people drop off. Switch off any check you don't want.
  4. Get the board. The project gets a board of its own, and Briefkin writes a skill for each check: the instructions your agent follows to read the numbers and post them as cards and tiles.

The project's page (More, Project setup on its board) keeps the story, the checks and their skills. Under Run them on your computer, pick a computer, an agent, a model and an effort, and Install: each check becomes a routine on that computer, with a Run button on the project's board and its own schedule. Each check gets its own minute, so they don't all start at once, and a time missed while the computer sleeps runs when it wakes. With Claude Code or Codex the checks read the apps you are signed in to in your Chrome (Using your browser); with the other agents they read the web and APIs only. A computer that is offline installs them when it is back.

Prefer another app? Only the skill files gives one command that puts every skill where Claude Code, Codex, Cursor and the other coding agents look for skills; they then run when you ask, or on a schedule you set up in that app.

Widgets on the board

Widgets are tiles in the numbers strip at the top of a board: a clock, prices, the weather, your calendar, your sites. Open Add, Widget on a board, describe what you want or pick one of the gallery templates, then make it yours beside a live preview: its name, size, source or parts. Click a widget on the board to open it the same way. A widget gets its content one of three ways:

  • Fixed: the same content until you change it.
  • Live data: Briefkin reads a public source on its own, no agent needed.
  • Your agent: a routine on your computer fills it on a schedule (see Install from the board), or any agent or script posts to it.

Live sources, and how often each one is read again:

SourceRefreshes
Crypto pricesevery 10 minutes
Stock pricesevery 15 minutes
Weatherevery 30 minutes
Exchange rateevery 6 hours
Calendar (ICS link)every 15 minutes
RSS or Atom feedevery 30 minutes
A number from a JSON URLevery 15 minutes
Domain Rating (Ahrefs)once a day
Site health checkevery 5 minutes

Every tile says how often it refreshes and when it reads next, and when it last read. A read that failed is tried again within the hour, and the tile says what went wrong.

Site health. List up to 8 addresses (a home page, /api/health). Briefkin opens each one every 5 minutes from its own server and shows whether it answered and how fast, with an uptime strip. A failed check is tried once more before it counts. After two failed checks in a row, a site is down card lands in Needs you and Telegram pings you; the same card turns into back up, with how long it was down, when the site answers again. Switch that off with When a site goes down: Only the widget. Sites behind a login or bot protection may refuse the check: they show amber, not down, and never ping.

Domain Rating. Ahrefs' Domain Rating for up to 10 domains, read once a day, so the line grows a point a day from the day you add it. No Ahrefs account needed.

AI limits and AI spend come from the usage collector on your computer, not from a widget source.

Manual setup: scripts and cron

For anything the installer does not cover (a cron job, CI, n8n, a server), create a token on the dashboard under Connect your first agent, create a token by hand. The token (bk_…) is shown once; only a hash is stored. Put it in the environment and send a card:

bashexport BRIEFKIN_TOKEN=bk_your_token
# Optional. Defaults to https://briefkin.dev
export BRIEFKIN_URL=https://briefkin.dev
bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"v":1,"event_id":"first-card","item_key":"hello","project":"Briefkin","kind":"update","title":"Hello from my agent"}'

The response is 202 with the card id, and the card appears on the dashboard within seconds:

json{"accepted":true,"duplicate":false,"card_id":"5f0c…","stale":false}

Any agent can follow the skill at /skill.md as instructions; it reads BRIEFKIN_TOKEN and BRIEFKIN_URL from the environment, or from ~/.config/briefkin/env.

Hooks and Projects threads

The installer registers the hook for you. It keeps one card per session and keeps its status current: what the agent is working on while it runs, Waiting for permission or Waiting for your input in Needs you while the session is paused on you, and where things stand when the turn ends. A turn only lands in Needs you when the agent stopped part-way and cannot go on without you; a finished turn that offers more (“Want me to…?”) or is ready for review is done. Asks the hook made go quiet when nothing more is heard about them: after an hour for a permission prompt, after 12 hours for anything else. They fold into one line under Needs you, are archived three days later, and come back if the session reports again. Status lines are written, for every agent, by a coding agent you already have, on your own login and in the background so nothing waits: Claude Code's Haiku (claude -p) first, else Codex (codex exec), else OpenCode (opencode run). Briefkin never sees or pays for those calls. Set BRIEFKIN_SUMMARIZER to change the order, or to off. A turn that changed nothing leaves the card as it was. A Claude Code turn that ends while agents it started in the background are still at work stays in progress, waiting on them, and a report coming back puts the card back to work. When the agent keeps a task list, the card shows it as a checklist and the progress bar follows it: Claude Code's todos and tasks, a Projects thread's status checklist, Codex's plan and Cursor's todos. A turn that ends on a question, a permission prompt or an input dialog becomes a Needs you card and a Telegram ping. These are alerts: Claude Code only reads answers typed in the session, so the card has no answer box. It shows the question and a button that opens the session, and it clears when the session moves on. In a Claude Code Projects thread it also picks up the project name and links the card to the thread. To wire it by hand, download it and call it from the agent’s hook config with the agent’s name. It reads the token from the environment or ~/.config/briefkin/env, needs curl and jq or python3, and exits 0 whatever happens.

Nothing is lost on the way. Every update is written to ~/.config/briefkin/spool first and sent from there in the background, oldest first, so the agent never waits on the network. An update that could not be sent (no network, a timeout, a server error) stays in the spool, and the next hook run, of any session, sends it; resends are safe, since Briefkin ignores an event it has seen and an older report never overwrites a newer card. The hook's own guess at the status is spooled before the status line is asked for, so a session the app ends while that line is being written still gets its card. Every delivery and every failure is one line in ~/.config/briefkin/hook.log: when a session is missing from the board, that file says why. A scheduled task's run (the Claude app runs those in the background) is named after the task, with the task's name in its source.

bashcurl -fsSL https://briefkin.dev/hooks.sh -o ~/.config/briefkin/briefkin-hook.sh
chmod +x ~/.config/briefkin/briefkin-hook.sh
# Then call it from your agent's hook config with the agent's name:
#   briefkin-hook.sh claude | codex | cursor | gemini | copilot | windsurf <event>

For Claude Code Projects threads (cloud sessions), the cloud environment setup covers every repository. To wire one repository instead, commit the script to the repository as .claude/hooks/briefkin-hook.sh and the hooks to .claude/settings.json; put BRIEFKIN_TOKEN in the cloud environment’s secrets, not in the repo. Repo hooks run in cloud threads of single-repository projects. A permission prompt in a thread can only be answered inside that thread, so these cards (action.reply: false) have no reply box: they tell you which thread to open.

json{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/briefkin-hook.sh" }] }],
    "Notification": [{ "matcher": "permission_prompt|elicitation_dialog", "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/briefkin-hook.sh" }] }],
    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/briefkin-hook.sh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/briefkin-hook.sh" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/briefkin-hook.sh" }] }]
  }
}

What gets sent

In Settings, under What gets sent, choose which projects report (all, all but some, or only some) and what happens to chats outside a project, meaning a session with no repository and no Projects thread, like a Codex app chat: send them all, never send them, or send only what your rule allows. The hook fetches these rules once a minute and applies them on your computer before it sends anything, so what you keep off the board never leaves it. For a chat under a rule, the same model that writes your status lines reads the rule with each new task and holds back the tasks it keeps on your computer; nothing about a held task is sent, and a later task in the same chat is checked again. Without Claude Code, Codex or OpenCode installed there is no model to ask, so those chats are held. Hooks older than version 14 cannot check chats against your rule; Briefkin drops what the rest of the rules leave out when it arrives, and re-running the installer updates them.

BRIEFKIN_PROJECT
The project name on the card. Defaults to the folder name.
BRIEFKIN_SOURCE
The source label, so sessions are told apart. Defaults to <Agent> · <folder>.
BRIEFKIN_LINK
A URL to open the session, added to every card as a link.
BRIEFKIN_PRIVATE
Set to 1 to send states only, never prompt or message text. A chat under a rule is then held, since the rule cannot be checked without its text.
BRIEFKIN_DETAILS
Set to 1 to also send the agent's whole final message, shown when you open the card. Off by default: a card says where things stand, not everything the agent said.

Staying up to date

Briefkin puts three small programs on your computer. Here is how each one gets its updates:

  • The routines runner updates itself. It checks in with Briefkin about every half minute, and when a newer runner is out (now version 19) it downloads it between runs, never in the middle of one, and restarts. Nothing to do. A runner from before installs (version 2 or older) can't do this yet: the board says so, and running the install command once more fixes it for good.
  • The hook asks you once. The hook (now version 29) sends its version with every update. When a computer still sends an older one, the board shows Update your Briefkin hook with the one command to run there. Running it keeps the computer's token, so there is nothing to approve, and updates the hook for every agent on that computer. Open sessions pick it up on their next update, no restart, because agents run the hook afresh for every event. The notice clears by itself once that computer reports the new version; folders you haven't worked in since count as updated. Details lists every place a hook reported from, to find a stray copy the installer doesn't reach.
  • The usage collector is updated by the same install command.

Until a hook is updated, Briefkin still cleans up what an older one sends, so the board stays readable. Re-running the installer is always safe: it keeps your token and your settings and replaces only its own entries.

bashcurl -fsSL https://briefkin.dev/install | sh

Card types, with curl

Every example reads BRIEFKIN_TOKEN and optionally BRIEFKIN_URL from the environment. The same item_key always updates the same card; a new key makes a new card.

Each update replaces the card, so send the whole card every time: a title that states where things stand with its numbers, a summary of one to three lines, the full story in details, and at least one widget (steps, a row of stats, a breakdown). An update with only a title gets hints back in the response naming what is missing.

Update: finished work, with links

For results that need no action. The card goes to the Working grid.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-web/pr-128/merged",
  "item_key": "acme-web/checkout-redesign",
  "project": "acme-web",
  "kind": "update",
  "title": "Checkout redesign merged and deployed",
  "summary": "PR #128 merged. Production deploy finished and the smoke tests passed.",
  "details": "## Shipped\n- One-page checkout with saved cards\n- Address autocomplete\n\n## Checked\n- 14 smoke tests on production, all passed",
  "work_state": "done",
  "widget": [
    { "type": "Steps", "props": { "items": [
      { "label": "Merged PR #128", "state": "done" },
      { "label": "Deployed to production", "state": "done" },
      { "label": "Smoke tests, 14 of 14", "state": "done" }
    ] } }
  ],
  "links": [
    { "label": "PR #128", "url": "https://github.com/acme/web/pull/128" },
    { "label": "Deploy log", "url": "https://ci.example.com/acme/web/runs/981" }
  ]
}
JSON

Action: something only you can do

The card goes to Needs you and stays there until you resolve it, and Telegram pings you if it is connected. instructions is shown as preformatted text, so put commands there.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-api/migration-0042/needed",
  "item_key": "acme-api/migration-0042",
  "project": "acme-api",
  "kind": "action",
  "title": "Production migration needed before deploy",
  "summary": "The release is built and waiting at the migration step.",
  "work_state": "blocked",
  "action": {
    "request": "Run migration 0042 on production",
    "why": "The new release reads orders.status_v2, which the migration adds.",
    "instructions": "pnpm db:migrate:remote"
  },
  "links": [
    { "label": "Migration", "url": "https://github.com/acme/api/blob/main/migrations/0042_status_v2.sql" }
  ]
}
JSON

If the agent sees the work done before you resolve the card, it can send a newer update on the same item_key. The card leaves Needs you:

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-api/migration-0042/applied",
  "item_key": "acme-api/migration-0042",
  "project": "acme-api",
  "kind": "update",
  "title": "Migration 0042 applied, deploy finished",
  "work_state": "done"
}
JSON

Metric: a number for a period

The card shows the latest value, the change from the previous period, when it was last reported and a small chart of the history. Set better to higher or lower so the change is green when it is good news and red when it is not: visitors going down is bad, bounce rate going down is good. Without it, common labels (bounce, errors, latency, cost, visitors, revenue) decide and anything else stays neutral. unit is drawn smaller after the number (%, ms), prefix smaller before it ($), and a currency code as the unit becomes its symbol in front. Hovering the chart shows each point's value and period. Metrics never ping.

The tile names the window the number covers, from period_start and period_end: Last 7 days for a 7-day window that just ended, Today for a day from midnight UTC, This month for a month from the 1st, and the dates once the window is old or still running. Send period_label for another name ("This billing cycle", at most 24 characters), or "" for a count right now, like open bugs, so no period shows.

Any card can name its board: the project goes on that board (made if it does not exist), so business numbers can land on a Business board and home things on Home. It only places a project that is not on a board yet; once the owner moves it, it stays where they put it. Without a board, a project that reports for the first time goes on the board that fits it by name and by what is already there (a client's new repository on Clients), or stays on the first board when none plainly does. Its menu says why it is where it is.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-shop/signups/2026-W40",
  "item_key": "acme-shop/signups-weekly",
  "project": "acme-shop",
  "board": "Business",
  "kind": "metric",
  "title": "128 signups last week",
  "metric": {
    "label": "Signups",
    "value": 128,
    "better": "higher",
    "period_start": "2026-09-28T00:00:00Z",
    "period_end": "2026-10-05T00:00:00Z"
  }
}
JSON

Richer stat tiles: glance and size

A metric is a stat tile at the top of the board. Under its number the tile shows a glance: a short widget from the same catalog as widget, so a cost tile can carry its budget bar and a row of sub-stats, a test tile its pass and fail counts, a deploy tile its environments as badges. Send it as glance (at most 12 elements). Without one, the tile shows a cut of widget that fits it: the progress bar, the first stats, the first rows of a table, with a note of how many more the opened card has. Text, logs and links stay in the opened card.

size suggests how much room the tile takes: sm one tile (room for one widget), md two tiles wide (three widgets), lg three wide with the number beside its glance (six widgets). A metric with a glance or widget takes md on its own. The owner can pick another size on the tile or in the opened card, and that choice is kept per card.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "vercel/usage/2026-10-16",
  "item_key": "vercel/usage",
  "project": "Vercel",
  "kind": "metric",
  "title": "$10.46 of $20 credit used; 23 days left",
  "size": "lg",
  "metric": {
    "label": "Infrastructure usage", "value": 10.46, "unit": "USD", "better": "lower",
    "period_label": "This billing cycle",
    "period_start": "2026-10-09T07:00:00Z", "period_end": "2026-11-09T08:00:00Z"
  },
  "glance": [
    { "type": "Progress", "props": { "label": "Included credit used", "value": 52.3, "text": "$10.46 / $20" } },
    { "type": "Grid", "props": { "columns": 3 }, "children": [
      { "type": "Stat", "props": { "label": "Remaining", "value": 9.54, "unit": "USD" } },
      { "type": "Stat", "props": { "label": "Days left", "value": 23 } },
      { "type": "Stat", "props": { "label": "On-demand", "value": 0, "unit": "USD" } }
    ] }
  ],
  "widget": [
    { "type": "Progress", "props": { "label": "Included credit used", "value": 52.3, "text": "$10.46 / $20.00" } },
    { "type": "Grid", "props": { "columns": 3 }, "children": [
      { "type": "Stat", "props": { "label": "Credit remaining", "value": 9.54, "unit": "USD" } },
      { "type": "Stat", "props": { "label": "Days left", "value": 23 } },
      { "type": "Stat", "props": { "label": "On-demand", "value": 0, "unit": "USD" } }
    ] },
    { "type": "Table", "props": { "columns": ["Product", "Charge"], "align": ["left", "right"], "rows": [
      ["Snapshot Storage", "$2.11"], ["Build CPU Minutes", "$1.67"], ["Fluid Active CPU", "$1.24"],
      ["Fast Origin Transfer", "$0.89"], ["Web Analytics Events", "$0.85"], ["Edge Middleware", "$0.65"]
    ] } }
  ]
}
JSON

Status, progress and widgets

The dashboard is built around what each agent is doing right now. Send "work_state": "in_progress" with progress (0 to 100) and waiting_on (“CI on PR #131”, “you”) and the agent’s tile at the top of the board shows it, live. Update the same item_key as the work moves; finish with done. The bar and the “waiting on” line go away once the card is done or you resolve it.

widget decides what the card shows below the title. It is a json-render spec built from the catalog below: one element, a list of elements (stacked), or a full spec with root and elements. Each element is { "type", "props", "children" }. It shows under summary; on the full-screen wall it takes the summary's place.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-web/search-facets/step-4",
  "item_key": "acme-web/search-facets",
  "project": "acme-web",
  "kind": "update",
  "title": "Search filters: implementing facets",
  "work_state": "in_progress",
  "progress": 60,
  "waiting_on": "CI on PR #131",
  "widget": {
    "type": "Steps",
    "props": { "items": [
      { "label": "Facet schema in the search index", "state": "done" },
      { "label": "Category and brand facets", "state": "done", "note": "merged in #131" },
      { "label": "Rating facet", "state": "active", "note": "writing the aggregation query" },
      { "label": "Availability facet and draft PR", "state": "pending" }
    ] }
  }
}
JSON

Several widgets on one card, with a row of stats:

json"widget": [
  { "type": "Callout", "props": { "text": "Build passed. Waiting for the e2e job.", "tone": "info" } },
  { "type": "Grid", "props": { "columns": 3 }, "children": [
    { "type": "Stat", "props": { "label": "Tests", "value": 1284, "delta": 2.1, "tone": "ok" } },
    { "type": "Stat", "props": { "label": "Coverage", "value": 91, "unit": "%" } },
    { "type": "Stat", "props": { "label": "p95", "value": 212, "unit": "ms", "delta": -14, "better": "lower" } }
  ] },
  { "type": "KeyValue", "props": { "items": [
    { "key": "Branch", "value": "feat/checkout" }, { "key": "Commit", "value": "a81f2c0" }
  ] } }
]

Widget catalog

The same catalog, with JSON Schema for every component, is at GET /v1/catalog (no token needed). Invalid widgets are rejected with 400 and the failing element named.

Stackcontainer
Container that stacks its children. Use as the root when a card shows several widgets. Props: direction?: string, gap?: string.
Gridcontainer
Container that places its children in equal columns. Good for a row of Stats. Props: columns?: integer.
Stat
One big number with a label. The most common widget. Props: label: string, value: number | string, unit?: string, prefix?: string, delta?: number, better?: string, tone?: string.
Progress
A horizontal progress bar. Props: label?: string, value: number, text?: string, tone?: string.
Limits
One agent's plan limits: its logo and a bar per usage window (5-hour, weekly, billing cycle). Props: agent: string, plan?: string, as_of?: string, windows: array.
Steps
A vertical checklist or timeline of steps with a state each. Shows the plan and where the agent is in it. Props: items: array.
Table
A compact table. Keep it to a few columns and at most 20 rows. Props: columns: array, rows: array, align?: array.
KeyValue
Rows of label and value, for example Branch: main, Commit: abc123. Props: items: array.
Badges
A row of small coloured labels, for tags, environments or statuses. Props: items: array.
Log
Terminal-style lines, newest last. For recent output, test results or a short activity log. Props: lines: array.
Bars
Horizontal bar chart comparing a few values, scaled to the largest one. Props: items: array, unit?: string, tone?: string.
Sparkline
A small line chart of a series over time, with the latest value shown large. Props: values: array, label?: string, unit?: string, prefix?: string, delta?: number, better?: string.
Text
A paragraph. mono renders as code, heading as a small section title. Props: text: string, variant?: string.
Callout
A highlighted one-liner, for example "Waiting on CI since 14:02" or a warning. Props: text: string, tone?: string.
Links
Buttons that open URLs: PRs, deploys, reports. Props: items: array.
Clock
A live clock, drawn by the viewer's browser. Several in a Grid make world clocks. Props: zone?: string, label?: string, style?: string, seconds?: boolean.
Countdown
Days, hours and minutes left until a date, live. Props: to: string, label: string, done?: string.
Ring
A ring that fills toward a maximum, with the number in the middle: a budget, a quota, a goal. Props: label: string, value: number, max?: number, unit?: string, prefix?: string, text?: string, warnAt?: number, badAt?: number, tone?: string.
Watchlist
Rows of symbol, price, change and a small line: crypto, stocks, currencies. Props: items: array.
Scores
Scores on a fixed scale with their change in points and a line: Domain Rating, Lighthouse, NPS. One item draws large. Props: items: array, max?: number, better?: string, credit?: object.
Uptime
Sites or services with a status dot, response time, uptime and a strip of recent checks: a status page. Props: items: array, period?: string.
Events
Upcoming events, soonest first, grouped by day: an agenda. Props: items: array, empty?: string.
Headlines
A list of items, each with an emoji, a title, a line of detail and a label; titles with a url open it. An inbox digest, a reading list, alerts. Props: items: array.
Weather
Current weather for a place, with the next few days. Props: place: string, temp: number, unit?: string, code: integer, high?: number, low?: number, days?: array.

Answers back to the agent

An action card is a question. Give it options and the card (and the Telegram alert) shows them as buttons; there is always a free-text reply too. Set wait: true when the agent will block on the answer, so the card says so.

bashcurl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "acme-api/release-2.4/approval",
  "item_key": "acme-api/release-2.4",
  "project": "acme-api",
  "kind": "action",
  "title": "v2.4.0 is staged and waiting for a production deploy",
  "action": {
    "request": "Approve the production deploy",
    "why": "Staging passed the full suite. Rollback plan is in the PR.",
    "options": ["Deploy", "Hold"],
    "wait": true
  },
  "links": [{ "label": "Release PR", "url": "https://github.com/acme/api/pull/412" }]
}
JSON

Your answer, from the dashboard or a Telegram tap or reply, resolves the card and is stored on it. There are three ways for the agent to get it, in the order most agents should prefer:

  1. Read it later. GET /v1/cards/:item_key returns the card with answered and response. An agent that cannot stay running (a Projects thread, a cron job) sends the ask, finishes, and reads the answer when it next runs.
  2. Wait for it. GET /v1/cards/:item_key/wait?timeout=25 blocks up to 25 seconds and returns as soon as there is an answer. Agents wait in chunks of a few minutes so one shell call never outlives the tool’s timeout, and stop after about 30 minutes:
bash# One chunk of about 8 minutes: 20 long polls of 25 s. Exits 0 with the answer, 1 when still open.
KEY="acme-api%2Frelease-2.4"
for i in $(seq 1 20); do
  out=$(curl -sS -m 40 "${BRIEFKIN_URL:-https://briefkin.dev}/v1/cards/$KEY/wait?timeout=25"     -H "authorization: Bearer $BRIEFKIN_TOKEN") || { sleep 5; continue; }
  [ "$(echo "$out" | jq -r .answered)" = true ] && { echo "$out" | jq -r .response.text; exit 0; }
  [ "$(echo "$out" | jq -r .resolved_at)" != null ] && { echo "resolved"; exit 0; }
done
exit 1
json{
  "id": "0b6e…",
  "item_key": "acme-api/release-2.4",
  "kind": "action",
  "attention": "needs_you",
  "resolved_at": 1791480600000,
  "answered": true,
  "response": { "text": "Deploy", "via": "telegram", "at": 1791480600000 }
}
  1. Get called back. If the agent can receive HTTP, it adds action.callback_url (https) to the ask and Briefkin POSTs the answer there once, retrying with backoff for about an hour on errors:
json"action": {
  "request": "Approve the production deploy",
  "options": ["Deploy", "Hold"],
  "callback_url": "https://hooks.example.com/briefkin/release-2.4"
}
httpPOST https://hooks.example.com/briefkin/release-2.4
content-type: application/json
x-briefkin-event: card.answered
x-briefkin-delivery: 6c1d…        # unique per attempt series; ignore repeats
x-briefkin-signature: sha256=9f2a…  # HMAC-SHA256(key = sha256 hex of your token, body)

{
  "type": "card.answered",
  "delivery_id": "6c1d…",
  "card": { "id": "0b6e…", "item_key": "acme-api/release-2.4", "title": "v2.4.0 is staged…", "project": "acme-api", "work_state": "done" },
  "response": { "text": "Deploy", "via": "telegram", "at": 1791480600000 },
  "sent_at": 1791480601000
}

Verify the signature before trusting the body. The key is the SHA-256 hex digest of the token, so no other secret is exchanged:

bashkey=$(printf %s "$BRIEFKIN_TOKEN" | sha256sum | cut -d' ' -f1)
expected="sha256=$(printf %s "$raw_body" | openssl dgst -sha256 -hmac "$key" | sed 's/^.* //')"
[ "$expected" = "$signature_header" ] || exit 1
  • answered is true once you replied; response.text is the option you tapped or what you typed. Resolving without a reply sets resolved_at and leaves response null.
  • One answer per ask. A newer action event on the same key asks again and clears the old answer.
  • Answer rules. Under an ask’s buttons, Always answer this way remembers the button you tap. The next time the same agent asks the same thing in the same project (case, spacing and numbers aside), Briefkin answers it with that button the moment it arrives, sends no alert, and the card says so. The agent sees response.via: "rule". You can undo it until the agent reads the answer, and stop a rule in Settings > Answer rules. Rules only use buttons the agent offered, and never answer a permission prompt in a session.
  • Deliveries are at least once: a callback may arrive twice with the same delivery_id. Treat a repeat as already handled.
  • Cards you are done with can be archived from the dashboard (Archive finished clears every resolved ask and done update at once). An archived card comes back on its own when the agent reports on it again.

Daily metric from cron

This script posts “example.com had N visitors yesterday” once a day. Save it as /usr/local/bin/briefkin-visitors.sh, make it executable, and replace visitors_on with your real query.

bash#!/usr/bin/env bash
# Posts yesterday's visitor count to Briefkin. Run it once a day from cron.
set -euo pipefail

SITE="example.com"
DAY=$(date -u -d yesterday +%F 2>/dev/null || date -u -v-1d +%F)  # GNU date, then BSD/macOS
TODAY=$(date -u +%F)

# Replace with your analytics query (Plausible, GA4, SQL...). It must print one number.
visitors_on() { echo 456; }
VISITORS=$(visitors_on "$DAY")

curl -sS --fail-with-body --retry 3 -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "v": 1,
  "event_id": "$SITE/visitors/$DAY",
  "item_key": "$SITE/visitors",
  "project": "$SITE",
  "kind": "metric",
  "title": "$SITE had $VISITORS visitors yesterday",
  "occurred_at": "${TODAY}T00:00:00Z",
  "metric": {
    "label": "Visitors",
    "value": $VISITORS,
    "period_start": "${DAY}T00:00:00Z",
    "period_end": "${TODAY}T00:00:00Z"
  }
}
JSON

Then add it to your crontab (here, every day at 06:15):

crontabBRIEFKIN_TOKEN=bk_your_token
15 6 * * * /usr/local/bin/briefkin-visitors.sh
  • item_key is the same every day, so the site has one card that updates daily and keeps the history as a chart.
  • event_id includes the date, so a retry or a second run for the same day changes nothing. That is what makes --retry 3 safe.
  • occurred_at is the end of the period. If you re-run an older day later, its point lands on the chart but it does not replace a newer day’s card.
  • --fail-with-body makes the script exit non-zero on an error, so cron reports it.
  • Metrics stay quiet. If a number needs you (a site at zero visitors, a failed backup), send an action card instead.

Telegram alerts

Connect Telegram in Settings with Connect Telegram, then press Start in the bot chat. An alert has the project, the title, the request and a link to the card. Only action cards ping:

Pings

  • A new action card.
  • An action card you resolved, when the agent sends a newer action for it (it reopens).
  • An existing update or metric card that turns into an action.
  • An open action that is raised to "urgency": "high".

Does not ping

  • Update and metric cards, including blocked and failed updates. Those an agent sends go to Needs you quietly; those the hook sends stay on the board.
  • Further updates to an action that is still open, unless they raise it to urgent.
  • An ask from the hook that is answered or replaced within a minute: its ping waits that long, so a permission prompt you answer at the keyboard never reaches your phone. An ask the hook sends again unchanged does not ping or reopen either.
  • An ask you have already opened in Briefkin before its ping is due.
  • Duplicate event ids and stale revisions.
  • Anything you do in the dashboard, such as reopening a card.

Failed sends are retried with backoff and logged.

API reference (v1)

Base URL https://briefkin.dev. Every request needs authorization: Bearer <token>. A token belongs to one workspace and can only see that workspace’s cards.

POST /v1/events

The body is one JSON event with content-type: application/json.

v 1required
Contract version. Always 1.
event_id stringrequired
Unique per update from one token. Sending the same event_id again changes nothing, so retries are safe. Derive it from what happened (for example site/visitors/2026-10-07) or use a UUID. max 128 characters.
item_key stringrequired
Stable key for the task or metric, for example repo/feature-name. Every update with the same item_key replaces the same card. max 200 characters.
project stringrequired
Project name shown on the card, for example the repository. max 100 characters.
board string
The board this project belongs on, by name, for example "Home" or "Clients". The board is made if it does not exist yet. Only places a project that is not on a board yet: once it is on one (by an earlier event or because the owner moved it), it stays there. Left out, new projects land on the first board. max 40 characters.
source string
Where this work runs, for example "Claude Code · thread: Search facets", "cron on homelab" or "ChatGPT task". Shown on the card and in the overview so you can tell threads apart. Omitting it keeps the last value. max 120 characters.
kind "update" | "action" | "metric"required
update: finished work or news. action: the user must do something. metric: a number for a period.
title stringrequired
The outcome in one short line, for example "Rendered all four reels, no clipping". No status prefix like "Done:" (the card shows the state) and no project name (the card shows it). max 200 characters.
summary string
One to three short lines under the title, in Markdown: the result and anything the user should notice. Long cards are cut to a few lines; put the rest in details. max 2000 characters.
details string
The full story in Markdown (what you did, numbers, commits, next steps), shown when the user opens the card. Send it on every update: a later update replaces the whole card. max 8000 characters.
work_state "in_progress" | "done" | "blocked" | "failed"
blocked and failed put the card in Needs you even when it is not an action. default "done".
urgency "low" | "normal" | "high"
high makes an action card urgent (red) and pings again if it was not urgent before. default "normal".
revision integer
Ordering for updates to one item_key. A card only changes when the revision is higher than the stored one. Defaults to occurred_at in milliseconds. 0 or more.
occurred_at ISO 8601 date-time
When it happened, ISO 8601 with a timezone, for example 2026-10-08T09:30:00Z. Defaults to when Briefkin received it.
waiting_on string
What the agent is waiting on right now, for example "CI on PR #44" or "you". Shown only while work_state is in_progress or blocked and the card is not resolved. max 200 characters.
progress integer
Percent complete for work in progress. Shown as a bar only while work_state is in_progress or blocked and the card is not resolved. 0 or more.
widget any
What the card shows, as widgets from the catalog (see Widgets below): one element, a list of elements, or a full json-render spec. Shown under the summary; on the full-screen wall it replaces the summary.
glance any
What the stat tile on the board shows under the number, from the same catalog as widget and kept short (at most 12 elements, 4000 bytes): a progress bar, a row of Stats, a few Badges. For kind metric. Left out, the tile shows a cut of widget that fits its size: the progress bar, the first stats, the first rows of a table.
size "sm" | "md" | "lg"
How much room the card takes on the board: sm one tile, md two tiles wide, lg three (the number beside its glance). A suggestion: the owner can pick another size per card, and that choice is kept. Left out, a metric with a glance or widget takes md, the rest sm. On the card board md and lg take two columns.
action object
Required when kind is action.
action.request stringrequired
What the user should do, as an instruction. max 500 characters.
action.why string
Why it matters or what it unblocks. max 1000 characters.
action.instructions string
Commands or steps, shown as preformatted text. max 4000 characters.
action.options array of string
Quick replies shown as buttons on the card and in the Telegram alert, for example ["Approve", "Reject"]. max 6 items.
action.wait boolean
True when the agent will wait for the answer (poll GET /v1/cards/{item_key}/wait). Shown on the card so the user knows the agent is blocked on them. default false.
action.reply boolean
False when an answer on the card cannot reach the agent, for example a permission prompt that must be answered in the session. The card then offers Resolve instead of a reply box. default true.
action.callback_url URL
An https URL that receives the answer as a POST (see Answers back to the agent), signed with HMAC-SHA256 in the x-briefkin-signature header. Retried for a day. max 500 characters.
metric object
Required when kind is metric.
metric.label stringrequired
What is measured, for example Visitors. max 100 characters.
metric.value numberrequired
The number for the period.
metric.unit string
Shown smaller after the value, for example %, ms or visitors. A currency code (USD, EUR, GBP) shows as its symbol in front. Left out, a label with "rate" in it reads as a percent; send "" for no unit. max 20 characters.
metric.prefix string
Shown smaller before the value, for example $. max 8 characters.
metric.period_start ISO 8601 date-timerequired
Start of the period, ISO 8601.
metric.period_end ISO 8601 date-timerequired
End of the period, ISO 8601. The chart keeps one point per period_end; a new event for the same period replaces it.
metric.period_label string
How the tile names the period, for example "Last 7 days", "This month" or "Since launch". Left out, it is named from period_start and period_end: "Last 7 days" for a 7-day window that just ended, "Today" for a day from midnight UTC, "This month" for a month from the 1st, dates once the window is old. Send "" for a count right now (open bugs, MRR) so no period shows. max 24 characters.
metric.better "higher" | "lower"
Which way is good, so the change from the previous period is coloured green or red: higher for visitors or revenue, lower for bounce rate, errors, latency or cost. Left out, common labels decide and unknown ones stay neutral.
links array of objects
Evidence: PRs, deploys, reports. max 10 items, default [].
links[].label stringrequired
Link text, for example "Review PR". max 80 characters.
links[].url URLrequired
An http or https URL, or a claude://, codex://, cursor:// or opencode:// link that opens that desktop app.

Responses

202 {"accepted": true, "duplicate": false, "card_id": "…", "stale": false}
Stored. stale is true when the card already has a higher revision: the event is kept in the history, the card is unchanged.
200 {"accepted": true, "duplicate": true, "card_id": "…", "stale": false}
This token already sent this event_id. Nothing changed.
400 {"error": "invalid_event", "issues": {…}}
The body is not valid JSON or does not match the contract. issues lists the failing fields. Fix it and send again; retrying unchanged will fail again.
401 {"error": "unauthorized"}
Missing, wrong or revoked token.
5xx or a network error
Retry with the same event_id. If the first attempt was stored, the retry returns 200 with duplicate: true.

A 400 looks like this (here, an empty title):

json{"error":"invalid_event","issues":{"errors":[],"properties":{"title":{"errors":["Too small: expected string to have >=1 characters"]}}}}

Idempotency

event_id is unique per token. The first event with a given id is stored; any later event with the same id from the same token is ignored and answered with 200 and "duplicate": true, even if its body differs. Retrying a request is always safe.

Revisions and the stale rule

Each item_key has one card. An event changes the card only if its revision is higher than the card’s current one; otherwise it is stored but answered with "stale": true, so an older event can never overwrite a newer card.

  • revision defaults to occurred_at in milliseconds, and occurred_at defaults to the time Briefkin received the event. Events sent in order just work.
  • When events can arrive out of order (parallel workers, backfills), set occurred_at or an explicit, increasing revision.
  • Pick one scheme per item_key. A small explicit revision such as 3 is always lower than a default, timestamp-based one.
  • Metric history points are saved even when the event is stale, so backfills fill in the chart.
  • A newer action, blocked or failed event reopens a card you resolved. Agents cannot resolve cards; you do that in the dashboard.

POST /v1/usage

What the usage collector sends: daily totals per agent, project and model for one computer, replacing that computer's earlier rows for the days listed. Any script can send the same shape; cost_usd is the agent's own count, or null to have Briefkin price the tokens.

json{
  "v": 1,
  "today": "2026-10-17",
  "days": ["2026-10-16", "2026-10-17"],
  "rows": [
    { "harness": "claude", "day": "2026-10-17", "project": "acme-web", "model": "claude-opus-5-5",
      "input": 485, "output": 43604, "cache_read": 4471532, "cache_write": 293345, "cost_usd": 5.78 },
    { "harness": "codex", "day": "2026-10-17", "project": "acme-web", "model": "gpt-5.2-codex",
      "input": 700, "output": 250, "cache_read": 900, "cache_write": 0, "cost_usd": null }
  ],
  "sessions": [
    { "harness": "claude", "day": "2026-10-17", "project": "acme-web", "sessions": 3 },
    { "harness": "codex", "day": "2026-10-17", "project": "acme-web", "sessions": 1 }
  ],
  "limits": [
    { "harness": "claude", "measured_at": 1760687400000, "windows": [
      { "id": "5h", "label": "5-hour", "used": 68, "resets_at": 1760698800000 },
      { "id": "week", "label": "Weekly", "used": 79, "resets_at": 1761040800000 } ] },
    { "harness": "codex", "measured_at": 1760686000000, "plan": "plus", "windows": [
      { "id": "5h", "label": "5-hour", "used": 0, "resets_at": null },
      { "id": "week", "label": "Weekly", "used": 40, "resets_at": 1760954400000 } ] }
  ]
}

Answers 202 with {"accepted": true, "rows": 2, "changed": true}; changed is false when the tiles already showed these numbers.

GET /v1/cards/:item_key

Returns the current state of one card in the token’s workspace, or 404 {"error": "not_found"}. URL-encode the key (/ becomes %2F). Agents use it to check whether you have handled an action: resolved_at is a timestamp in milliseconds once you resolve it, and null before; response carries your answer (see Answers back to the agent).

bashcurl -sS "${BRIEFKIN_URL:-https://briefkin.dev}/v1/cards/acme-api%2Fmigration-0042" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN"
json{
  "id": "0b6e…",
  "item_key": "acme-api/migration-0042",
  "kind": "action",
  "title": "Production migration needed before deploy",
  "work_state": "blocked",
  "attention": "needs_you",
  "revision": 1791480000000,
  "resolved_at": null,
  "archived_at": null,
  "updated_at": 1791480000000,
  "answered": false,
  "response": null
}

attention is none, needs_you or urgent. Times are milliseconds since the Unix epoch.