Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"name": "logbook",
"version": "0.1.0",
"description": "Logbook: an open-source issue tracker you share with your agents. Agents file and update issues, link pull requests, track releases and ask you when a decision needs a human. Every write lands in one log.",
"author": {
"name": "the Logbook contributors"
},
"homepage": "https://github.com/falkoro/logbook",
"repository": "https://github.com/falkoro/logbook",
"license": "MIT",
"keywords": [
"issue-tracker",
"mcp",
"agents",
"project-management",
"self-hosted",
"open-source",
"cloudflare"
],
"logo": "assets/logo.png",
"variables": {
"type": "object",
"properties": {
"LOGBOOK_URL": {
"type": "string",
"title": "Logbook URL",
"description": "Base URL of your Logbook instance, without trailing slash",
"default": "https://logbook.spotcloud.nl"
}
},
"required": [
"LOGBOOK_URL"
]
}
}
19 changes: 7 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

**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.](docs/hero.png)
![Logbook: you and your agents share one issue tracker and one log. Agents connect over MCP. It runs on Cloudflare's free tier or self-hosted with Bun and SQLite or Docker.](docs/hero.png)

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.
Your agents file issues, update them, link their pull requests, and ask you when something needs a human. 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

Expand Down Expand Up @@ -41,7 +41,7 @@ Ask it to list the open issues, or to ask you something with `ask_decision`. The
- **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.
- **MCP tools.** `list_issues`, `save_issue`, `save_comment`, `list_issue_statuses` and the rest; every tool is also a REST endpoint.
- **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.

Expand Down Expand Up @@ -104,15 +104,6 @@ A PR whose title, body or branch names an issue key (`ENG-12`) is linked to that

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:

```sh
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

Expand All @@ -130,3 +121,7 @@ Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the
## License

MIT. See [LICENSE](LICENSE).

## Cursor plugin

The `logbook` Cursor plugin lives in this repo (`.cursor-plugin/plugin.json`, `mcp.json`, `skills/logbook`). Install it from the Cursor Marketplace, set `LOGBOOK_URL`, and approve the OAuth prompt once. Manual setup: add `{ "mcpServers": { "logbook": { "url": "https://logbook.example.com/mcp" } } }` to `~/.cursor/mcp.json`.
Binary file added assets/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletions mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"mcpServers": {
"logbook": {
"url": "${LOGBOOK_URL}/mcp"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trailing slash breaks plugin MCP URL

Medium Severity

mcp.json builds the server URL as ${LOGBOOK_URL}/mcp. A LOGBOOK_URL that already ends in / becomes //mcp, which does not match the /mcp route, the Access bypass, or run_worker_first. The client then gets the SPA HTML instead of the OAuth challenge, so marketplace install fails. Copied instance URLs commonly include that slash; the CLI already strips it, but this template does not.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit a7268de. Configure here.

}
}
}
12 changes: 12 additions & 0 deletions skills/logbook/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
name: logbook
description: Track work in Logbook, the open-source issue tracker shared with agents. Use when filing, updating or searching issues, linking pull requests, or asking the human for a decision.
---

# Logbook

- Start with `overview` or `me` to see teams, statuses and your seat.
- Find work with `search` / `list_issues`; read with `get_issue` and `list_comments`.
- Create or update with `save_issue`; report progress with `save_comment`.
- Link PRs with `link_pr`.
- When a human must choose, use `ask_decision` instead of guessing; check `list_decisions` later.
Loading