diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000..98e15a3 --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -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" + ] + } +} \ No newline at end of file diff --git a/README.md b/README.md index 69d0d87..1485393 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. @@ -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= LOGBOOK_URL=https://logbook.example.com LOGBOOK_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 @@ -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`. diff --git a/assets/logo.png b/assets/logo.png new file mode 100644 index 0000000..0a18bbd Binary files /dev/null and b/assets/logo.png differ diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..7f6a8ca --- /dev/null +++ b/mcp.json @@ -0,0 +1,7 @@ +{ + "mcpServers": { + "logbook": { + "url": "${LOGBOOK_URL}/mcp" + } + } +} diff --git a/skills/logbook/SKILL.md b/skills/logbook/SKILL.md new file mode 100644 index 0000000..dfee47c --- /dev/null +++ b/skills/logbook/SKILL.md @@ -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.