Skip to content
falkoroPublic

About

An issue tracker you share with your agents. Runs on Cloudflare (Workers + D1 + R2) or self-hosted (Bun + SQLite).

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Logbook

An issue tracker you share with your agents.

Logbook: you and your agents share one issue tracker and one log. Agents connect over Linear-compatible MCP. It runs on Cloudflare's free tier or self-hosted with Bun and SQLite or Docker.

Your agents file issues, update them, link their pull requests, and ask you when something needs a human. They use the same MCP tools as Linear, so an agent that already works with Linear switches over by changing a URL and a token. Every write by anyone lands in one log. It runs on Cloudflare's free tier or as one Bun process with a SQLite file.

What it looks like

The board An issue An agent asks you
The issues of three apps, grouped by status An issue with the agent's comment, its pull request and the history of every change A question an agent asked over MCP with ask_decision, waiting in the inbox with its options and recommendation
Every open issue across your apps, grouped by status. The agent's comment, its pull request and every change in one place. A question an agent sent with ask_decision, waiting in your inbox.

An agent's question in the inbox, answered in one click, and the log of who did what

Try it in a minute

You need Bun.

git clone https://github.com/falkoro/logbook.git
cd logbook
bun install
bun run demo

Open http://localhost:8796. The demo fills ./data with a made-up coffee roaster: three apps, two agents and two questions waiting for you. It serves with DEV_AUTH=1, which signs in every request from your own machine as dev@localhost. To start empty instead, run DEV_AUTH=1 bun run serve.

Then give an agent a seat. In Settings, create a token, and add the server to Claude Code (or any MCP client that takes a header):

claude mcp add --transport http logbook http://localhost:8796/mcp --header "Authorization: Bearer <token>"

Ask it to list the open issues, or to ask you something with ask_decision. The question lands in your inbox.

What you get

  • A crew, not a seat count. Each agent has its own login and shows up by name everywhere it writes. No per-user pricing, no shared bot account.
  • A captain's inbox. An agent asks with ask_decision: a question, options, a recommendation. You answer, and the answer goes back on the issue as a comment. Only a human can answer.
  • One log. Every write by anyone, append-only, with a snapshot of the row as it was written.
  • Linear's MCP tools. list_issues, save_issue, save_comment, list_issue_statuses and the rest, with the same names and inputs. An importer brings your Linear workspace along, IDs included.
  • Releases close issues, merges don't. A PR links to its issue. The issue closes when the release it belongs to goes live, with a comment saying which release shipped it.
  • Your infrastructure. Cloudflare Workers, D1 and R2 on the free tier, or a Bun process with a SQLite file behind a Cloudflare Tunnel. Cloudflare Access handles the human login.

Run it on Cloudflare

  1. Create the database and the file bucket:

    bunx wrangler d1 create logbook
    bunx wrangler r2 bucket create logbook-files
  2. Edit wrangler.jsonc: your hostname under routes, the database_id from step 1, and your email in OWNER_EMAILS.

  3. In Cloudflare Zero Trust, add two self-hosted Access applications on that hostname:

    • One for the whole hostname that allows your email. Copy its audience tag into ACCESS_AUD, and your team domain into ACCESS_TEAM_DOMAIN.
    • One with a Bypass policy for /api, /mcp, /hooks, /files, /openapi.json, /healthz, /.well-known, /oauth/register and /oauth/token. Agents can't log in through Access; the Worker checks their tokens on those paths and refuses everything else. /oauth/authorize stays behind Access, because that is where you approve a connector.
  4. Deploy. This builds the UI, applies the migrations and uploads the Worker:

    bun run deploy

Open your hostname, log in through Access, and add your apps in Settings. Each app gets a key that prefixes its issues, like ENG-12.

To host it yourself instead, run bun run serve on a machine of your own. It keeps everything under LOGBOOK_DATA (default ./data) and listens on 127.0.0.1:8796. Put it behind a Cloudflare Tunnel with the same Access setup and pass the same variables as environment variables.

Run it with Docker

git clone https://github.com/falkoro/logbook.git
cd logbook
docker compose up -d

Open http://localhost:8796. Everything lives in the logbook-data volume, so it survives restarts and rebuilds; set LOGBOOK_PORT to use another port. Like the demo, it signs in every request as dev@localhost, so the port is published on 127.0.0.1 only. In Settings, create a token and add http://localhost:8796/mcp to your agent as shown under Connect an agent. docker compose down stops it and keeps the data; docker compose down -v deletes it too.

To reach it from anywhere but this machine, set LOGBOOK_DEV_AUTH=0, add the Access variables from above to the service's environment, and put it behind a Cloudflare Tunnel.

Connect an agent

Claude Code, or any MCP client that takes a header:

claude mcp add --transport http logbook https://logbook.example.com/mcp --header "Authorization: Bearer <token>"

claude.ai and Cowork: add a custom connector with the URL https://logbook.example.com/mcp. There is no client ID or secret. You approve it once, and it joins the crew as an agent named after the app.

Scripts: every MCP tool is also POST /api/<tool> with the same token, and /openapi.json lists them all. cli/logbook.ts wraps that for the shell:

LOGBOOK_URL=https://logbook.example.com LOGBOOK_TOKEN=<token> bun cli/logbook.ts list_issues --team ENG

Pull requests

A PR whose title, body or branch names an issue key (ENG-12) is linked to that issue. GitHub sends them through a webhook on /hooks/github: set GITHUB_WEBHOOK_SECRET with wrangler secret put and use the same secret on the webhook. Cursor Origin has no webhooks, so with ORIGIN_TOKEN and ORIGIN_REPOS set a cron polls each repo every five minutes.

A merged PR never closes its issue. Issues close when the release they belong to goes live, and each one gets a comment saying which release shipped it.

Move from Linear

Create a token of kind System job in Settings, then run the importer once per Linear workspace:

LINEAR_API_KEY=<key> LOGBOOK_URL=https://logbook.example.com LOGBOOK_TOKEN=<system token> bun import/linear.ts --dry-run

The dry run writes nothing and prints what would be imported and anything that doesn't map. Run it again without --dry-run to import. Issues keep their Linear IDs, so running it twice updates them in place instead of making copies, and you can rehearse before you switch over. The comments at the top of import/linear.ts list the other options.

How it works

docs/design.md covers the data model, the rules the core enforces, and how the same code runs on Workers and on Bun.

bun run check   # types
bun test        # tests

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md has the setup, the map of the code and the few rules that keep it small.

License

MIT. See LICENSE.

About

An issue tracker you share with your agents. Runs on Cloudflare (Workers + D1 + R2) or self-hosted (Bun + SQLite).

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages