@bosun-sh/logbook 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bosun.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# logbook: kanban for ai agents
+
+logbook is a kanban board implementation for autonomous agentic development, focusing on autonomous development and context window management.
+
+→ **new here?** see [quickstart.md](quickstart.md) to get running in 2 minutes.
+
+## problem
+
+ai agents changed the way software teams worked, and with specification-driven development we encounter a rift: **agents don't manage their tasks as we do**.
+
+### what's the issue with this?
+
+- hard for humans to track autonomous work properly: **"do you know what specific tasks your agent did?"**
+- hard for agents to track tasks in-progress and done: **not a centralized way to track tasks so each instance haves to figure this out**
+- existing tools add too much overload and are human-centered: **if an agent is going to use it, then it should be tailored for agents**
+
+## solution
+
+logbook is a file-system based kanban board that uses jsonl files to enter one task per line in a structured and clean approach and gives the agent the right tools to use it:
+
+### tools
+
+- the agent can call `list_tasks(status)` and receive a list of the tasks in that status _(in_progress by default)_
+- the agent can call `current_task()` and receive the highest-priority in_progress task for the current session, resolved via this priority chain:
+
+  | priority | condition | action |
+  |----------|-----------|--------|
+  | 1 | task already assigned to this session | return highest priority (tie-break: oldest) |
+  | 2 | unassigned `in_progress` task | claim highest priority, return |
+  | 3 | `in_progress` task with a dead-session assignee | claim highest priority, return |
+  | 4 | `todo` task | auto-transition highest priority to `in_progress`, claim, return |
+  | 5 | nothing available | fail with `no_current_task` |
+- the agent can call `update_task(id, new_status, comment)` to transition a task, add a comment, or reply to a `need_info` blocking comment
+- the agent can call `create_task(input)` to open a new task in `backlog`, passing `predictedKTokens` so the server derives a Fibonacci estimation automatically
+- the agent can call `edit_task(id, updates)` to change mutable fields without altering status
+
+each one of these tools has the sole purpose of removing overload from the agent context, handling the _"heavy load"_ programmatically on the MCP server.
+
+## walkthrough
+
+a complete agent session from start to done:
+
+**1. agent starts — get current task**
+
+```
+current_task()
+→ { id: "abc-123", title: "implement login endpoint", status: "in_progress", ... }
+```
+
+**2. agent needs clarification — blocks on a question**
+
+```
+update_task("abc-123", "need_info", {
+  title: "which auth provider?",
+  content: "should i use jwt or session-based auth? the spec doesn't say.",
+  kind: "need_info"
+})
+→ hook fires: user is notified with the comment
+```
+
+**3. user replies — task unblocked**
+
+```
+update_task("abc-123", "in_progress", {
+  id: "<comment-id>",
+  reply: "use jwt, see the auth spec in docs/auth.md",
+  title: "jwt confirmed",
+  content: "jwt confirmed",
+  kind: "need_info"
+})
+→ task returns to in_progress
+```
+
+**4. agent finishes — submits for review**
+
+```
+update_task("abc-123", "pending_review", {
+  title: "implementation complete",
+  content: "jwt login endpoint implemented, tests passing",
+  kind: "regular"
+})
+→ review-spawn hook fires: review task created, reviewer agent spawned
+```
+
+**5. reviewer approves — task closed**
+
+```
+# reviewer agent calls:
+current_task()  → gets the review task
+update_task("<review-task-id>", "done")
+→ original task abc-123 → done automatically
+```
+
+### how the agent knows logbook exists
+
+add the logbook MCP server to your AI client config (see [configuration](#configuration)), then include these instructions in your agent's system prompt or `CLAUDE.md`:
+
+```
+You are connected to the logbook MCP server. Call current_task() immediately at session start.
+```
+
+the full system prompt is injected automatically when the MCP server connects.
+
+## architecture
+
+- **runtime**: Bun / TypeScript
+- **effect system**: Effect.ts — all async operations and errors are modeled as `Effect<A, E, R>`
+- **architecture**: hexagonal (ports & adapters), organized by vertical slices per domain concept (task, hook)
+- **validation**: Zod at every system boundary (MCP input, filesystem reads)
+- **persistence**: JSONL — one task per line, append-only writes, full file scan for reads
+
+JSONL was chosen for simplicity and agent-friendliness: a single line = a single task makes partial reads and diffs readable without tooling.
+
+### hooks
+
+besides the tools that the agent call manually, each action performed in the kanban can have automatic _hooks_ executed right before or after.
+the default hooks include:
+
+- after moving a task to `need_info`, the user receives a notification with the comment left to be able to answer the question.
+- after moving a task to `pending_review`, a reviewer sub-agent spawns and a review task is automatically generated for it.
+- when a second task is moved to `in_progress`, a built-in hook fires and requires a comment justifying the overlap before proceeding.
+
+but hooks can also be defined by the user as scripts in any language as long as it's installed in the system, under the "hooks/" directory, following this structure:
+
+```
+hooks/
+└── example_hook/
+    ├── config.yml
+    └── script.ts
+```
+
+a minimal `config.yml` looks like:
+
+```yaml
+# config.yml
+event: task.status_changed   # lifecycle event that triggers the hook
+condition: "new_status == 'need_info'"  # optional; JS-like expression
+timeout_ms: 5000             # optional; default 5000
+```
+
+you can base your config.yml in the default hooks-which have complete configuration files.
+
+> note: as mentioned, you can change .ts for any language, but the .yml / .yaml is required for configuration.
+
+#### review flow
+
+when a task is moved to `pending_review`, the built-in `review-spawn` hook automatically creates a review task and spawns a reviewer sub-agent. the reviewer classifies every finding before acting:
+
+```mermaid
+flowchart TD
+    PR[task: pending_review]
+    PR -->|review-spawn hook| SPAWN[review task created\nreviewer agent spawned]
+    SPAWN --> CL{classify findings}
+
+    CL -->|nice-to-have findings| TD["[tech debt] tasks created\nin backlog — silently"]
+
+    CL -->|must-fix found| MF[original → in_progress\nneed_info: must fix before re-submitting]
+    CL -->|consider only| CO[original → in_progress\nneed_info: implementer decides\nfix now or backlog]
+    CL -->|clean| DONE[original → done]
+
+    MF --> RD[review task → done]
+    CO --> RD
+    DONE --> RD
+
+    TD -.->|accompanies any outcome| RD
+```
+
+| finding severity | original task | review task | side effect |
+|-----------------|---------------|-------------|-------------|
+| **must-fix** | `→ in_progress` + `need_info` | `→ done` | — |
+| **consider** | `→ in_progress` + `need_info` | `→ done` | implementer replies: fix now or backlog |
+| **nice-to-have** | unchanged | — | `[tech debt]` backlog task created |
+| **clean** | `→ done` | `→ done` | — |
+
+nice-to-have findings are always handled silently — they never block progress or ping the implementer.
+
+#### why hooks?
+
+hooks don't need to store information from one execution to the other, so the main principle here is: **"execute and forget"**, this way we can focus on the kanban and actual tasks.
+
+## contracts
+
+the core types the server operates on:
+
+```ts
+type Agent = {
+  id: string,       // session_id assigned by the server on connection
+  title: string,
+  description: string
+}
+
+type Status = 'backlog' | 'todo' | 'need_info' | 'blocked' | 'in_progress' | 'pending_review' | 'done'
+
+type Comment = {
+  id: string,
+  timestamp: Date,
+  title: string,
+  content: string,
+  reply: string,  // user's reply, populated when responding to a need_info comment
+  kind: 'need_info' | 'regular'  // drives the reply cycle — only need_info comments accept replies
+}
+
+type Task = {
+  project: string,
+  milestone: string,
+  id: string,
+  title: string,
+  definition_of_done: string,
+  description: string,
+  estimation: number,      // fibonacci number derived from predictedKTokens at creation time
+  comments: Comment[],
+  assignee: Agent,
+  status: Status,
+  in_progress_since?: Date // set when task enters in_progress; used as tie-breaker in current_task
+  priority: number         // integer ≥ 0; higher = more urgent; defaults to 0
+}
+
+// status defaults to 'in_progress'; results ordered by priority DESC
+// project and milestone are optional; all provided filters compose (AND semantics)
+type ListTasks = (options: { status: Status | '*', project?: string, milestone?: string }) => Task[]
+
+// returns the highest-priority task for the current session using a priority chain:
+// 1. own in_progress → 2. unassigned in_progress → 3. orphaned in_progress
+// (dead-session assignee) → 4. highest-priority todo (auto-transitioned) → 5. no_current_task error.
+// within each step, tasks are ordered by priority DESC, tie-broken by in_progress_since ASC.
+// if a second task is moved to in_progress, a built-in hook fires and
+// requires a comment justifying the overlap.
+type GetCurrentTask = () => Task
+
+// transitions a task to a new status; sessionId is injected server-side.
+// to reply to a need_info comment, pass a comment with the existing comment's id and a reply string.
+type UpdateTask = (id: string, new_status: Status, comment: CommentInput | null, sessionId: string) => void
+
+type CommentInput = {
+  id?: string,     // existing comment id — only when replying to a need_info comment
+  title: string,
+  content: string,
+  reply?: string,  // reply text — only meaningful when id refers to a need_info comment
+  kind: 'need_info' | 'regular'
+}
+
+// creates a new task in backlog assigned to the calling session.
+// predictedKTokens is mapped to a Fibonacci estimation by the server.
+type CreateTask = (input: CreateTaskInput, sessionId: string) => Task
+
+type CreateTaskInput = {
+  project: string,
+  milestone: string,
+  title: string,
+  definition_of_done: string,
+  description: string,
+  predictedKTokens: number,  // positive number; server maps this to a Fibonacci estimation (max 20)
+  priority?: number           // integer ≥ 0; defaults to 0
+}
+
+// edits mutable fields without changing status
+type EditTask = (id: string, updates: EditTaskInput) => Task
+
+type EditTaskInput = {
+  title?: string,
+  description?: string,
+  definition_of_done?: string,
+  predictedKTokens?: number,  // re-derives estimation if provided
+  priority?: number            // integer ≥ 0; re-assigns priority if provided
+}
+```
+
+each MCP session is treated as a distinct agent instance. the server assigns a `session_id` on connection and uses it to scope `GetCurrentTask` — no explicit agent ID needs to be passed by the caller.
+
+## install
+
+```bash
+npm install -g @bosun-sh/logbook
+```
+
+requires **bun ≥ 1.0.0** as the runtime ([install bun](https://bun.sh)).
+
+verify the installation:
+
+```bash
+logbook-mcp --version
+```
+
+for a full onboarding walkthrough see [quickstart.md](quickstart.md).
+
+## configuration
+
+### quick setup
+
+run `logbook-mcp init` in your project directory to scaffold `tasks.jsonl`, `hooks/`, and print the config snippets for your AI client.
+
+### environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOGBOOK_TASKS_FILE` | `./tasks.jsonl` | path to the JSONL task store |
+| `LOGBOOK_HOOKS_DIR` | `./hooks` | directory scanned for custom hook definitions |
+| `LOGBOOK_LOG_LEVEL` | `warn` | structured logger level: `debug`, `info`, `warn`, or `error` |
+
+### gitignore
+
+`tasks.jsonl` and `sessions.json` are runtime files generated by the MCP server — they should not be committed to version control:
+
+```gitignore
+tasks.jsonl
+sessions.json
+```
+
+> note: the logbook repo itself intentionally commits these files for dogfooding — that is the exception, not the rule.
+
+### client setup
+
+**Claude Code** — add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "logbook": {
+      "command": "logbook-mcp"
+    }
+  }
+}
+```
+
+**OpenCode** — add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "logbook": {
+      "type": "local",
+      "command": ["logbook-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## security
+
+### hook conditions are trusted code
+
+hook `config.yml` files support an optional `condition` field (e.g. `"new_status == 'pending_review'"`). these conditions are compiled and evaluated as live JavaScript at runtime — equivalent in trust level to a shell script.
+
+**what this means for you:**
+
+- **only add hooks from sources you trust.** a malicious `config.yml` condition can execute arbitrary code in the process that runs the MCP server.
+- **do not expose `LOGBOOK_HOOKS_DIR` to external write access.** if an untrusted process can write files under the hooks directory, it can inject conditions that execute as the MCP server's user.
+- the built-in hooks shipped with logbook are safe — they use simple equality checks (`new_status == 'need_info'`).
+- if a condition throws or is malformed, the hook is skipped silently and execution continues — it fails safe.
+
+the security model here is the same as running a `Makefile` or a `.husky/` script: filesystem-level trust. as long as you control what goes into your hooks directory, you are safe.
+
+## stability
+
+logbook follows semantic versioning. here is what is stable at v1.0.0:
+
+- **mcp api**: tool names and required parameters will not change within a major version. optional parameters may be added.
+- **jsonl format**: the serialized `Task` type in `tasks.jsonl` is stable. new optional fields may be added; existing fields will not be removed or renamed within a major version.
+- **hook config schema**: the `event`, `condition`, and `timeout_ms` keys in `config.yml` are stable. new optional keys may be added.
+- **breaking changes**: any breaking change will be preceded by a deprecation notice in the prior minor release and documented in `CHANGELOG.md`.

package/hooks/need-info-notify/config.yml

@@ -0,0 +1,3 @@
+event: task.status_changed
+condition: "new_status == 'need_info'"
+timeout_ms: 5000

package/hooks/need-info-notify/script.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises"
+
+const taskId = process.env.LOGBOOK_TASK_ID ?? ""
+const dataFile = process.env.LOGBOOK_TASKS_FILE ?? "./tasks.jsonl"
+
+if (taskId === "") process.exit(0)
+
+const readLines = async (filePath: string): Promise<readonly string[]> => {
+  const content = await readFile(filePath, "utf8").catch((e: unknown) => {
+    if (isEnoent(e)) return ""
+    throw e
+  })
+  return content.split("\n").filter((l) => l.trim() !== "")
+}
+
+interface RawComment {
+  id: string
+  timestamp: string
+  title: string
+  content: string
+  reply: string
+  kind: string
+}
+
+interface RawTask {
+  id: string
+  comments: RawComment[]
+}
+
+const parseTask = (line: string): RawTask | null => {
+  try {
+    return JSON.parse(line) as RawTask
+  } catch {
+    return null
+  }
+}
+
+const findBlockingComment = (task: RawTask): RawComment | null => {
+  // Find the most recent need_info comment with an empty reply
+  for (let i = task.comments.length - 1; i >= 0; i--) {
+    const comment = task.comments[i]
+    if (comment !== undefined && comment.kind === "need_info" && comment.reply === "") {
+      return comment
+    }
+  }
+  return null
+}
+
+const isEnoent = (e: unknown): boolean =>
+  typeof e === "object" && e !== null && (e as { code?: unknown }).code === "ENOENT"
+
+const lines = await readLines(dataFile)
+
+let found: RawTask | null = null
+for (const line of lines) {
+  const task = parseTask(line)
+  if (task !== null && task.id === taskId) {
+    found = task
+    break
+  }
+}
+
+if (found === null) process.exit(0)
+
+const comment = findBlockingComment(found)
+if (comment === null) process.exit(0)
+
+process.stdout.write(`[need_info] Task ${taskId}: ${comment.title}\n${comment.content}\n`)

package/hooks/review-spawn/config.yml

@@ -0,0 +1,3 @@
+event: task.status_changed
+condition: "new_status == 'pending_review'"
+timeout_ms: 30000

package/hooks/review-spawn/script.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+import { appendFile, readFile } from "node:fs/promises"
+
+const taskId = process.env.LOGBOOK_TASK_ID ?? ""
+const dataFile = process.env.LOGBOOK_TASKS_FILE ?? "./tasks.jsonl"
+
+if (taskId === "") process.exit(0)
+
+const readLines = async (filePath: string): Promise<readonly string[]> => {
+  const content = await readFile(filePath, "utf8").catch((e: unknown) => {
+    if (isEnoent(e)) return ""
+    throw e
+  })
+  return content.split("\n").filter((l) => l.trim() !== "")
+}
+
+interface RawAgent {
+  id: string
+  title: string
+  description: string
+}
+
+interface RawTask {
+  project: string
+  milestone: string
+  id: string
+  title: string
+  definition_of_done: string
+  description: string
+  estimation: number
+  comments: unknown[]
+  assignee: RawAgent
+  status: string
+  in_progress_since?: string
+}
+
+const parseTask = (line: string): RawTask | null => {
+  try {
+    return JSON.parse(line) as RawTask
+  } catch {
+    return null
+  }
+}
+
+const isEnoent = (e: unknown): boolean =>
+  typeof e === "object" && e !== null && (e as { code?: unknown }).code === "ENOENT"
+
+const lines = await readLines(dataFile)
+
+let original: RawTask | null = null
+for (const line of lines) {
+  const task = parseTask(line)
+  if (task !== null && task.id === taskId) {
+    original = task
+    break
+  }
+}
+
+if (original === null) process.exit(0)
+
+// Guard: don't create a review-of-a-review (circular flow)
+if (original.id.startsWith("review-")) process.exit(0)
+
+const reviewId = `review-${original.id}`
+
+// Idempotency check: skip if a task with the review id already exists
+const alreadyExists = lines.some((line) => {
+  const task = parseTask(line)
+  return task !== null && task.id === reviewId
+})
+
+if (alreadyExists) process.exit(0)
+
+const reviewTask: RawTask = {
+  project: original.project,
+  milestone: original.milestone,
+  id: reviewId,
+  title: `Review: ${original.title}`,
+  definition_of_done: "Review approved",
+  description: `Review task for ${original.id}`,
+  estimation: 1,
+  comments: [],
+  assignee: original.assignee,
+  status: "todo",
+}
+
+await appendFile(dataFile, `${JSON.stringify(reviewTask)}\n`, "utf8")
+
+const { execSync } = await import("node:child_process")
+const path = await import("node:path")
+const projectRoot = path.dirname(process.env.LOGBOOK_TASKS_FILE ?? "./tasks.jsonl")
+const mcpConfig = path.join(projectRoot, ".claude/mcp-config.json")
+execSync(
+  `claude --model claude-haiku-4-5-20251001 --mcp-config ${mcpConfig} --agent reviewer -p "review task ${reviewId}"`,
+  { stdio: "inherit", env: { ...process.env, LOGBOOK_TASKS_FILE: dataFile } }
+)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bosun-sh/logbook",
+  "version": "1.0.0",
+  "description": "File-system kanban board MCP server for AI agents",
+  "type": "module",
+  "bin": {
+    "logbook-mcp": "src/mcp/server.ts"
+  },
+  "files": [
+    "src/",
+    "hooks/",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "start": "bun src/mcp/server.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:unit": "bun test tests/unit/",
+    "test:e2e": "bun test tests/e2e/",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "biome format --write .",
+    "check": "biome check .",
+    "prepare": "husky",
+    "prepublishOnly": "bun run typecheck",
+    "publish": "bun run typecheck && npm pack --dry-run && npm publish --ignore-scripts",
+    "publish:dev": "bun link ."
+  },
+  "dependencies": {
+    "effect": "^3.12.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/bun": "latest",
+    "husky": "^9.0.0",
+    "typescript": "^5.7.3"
+  }
+}

package/src/cli/init.ts

@@ -0,0 +1,90 @@
+import { access, mkdir, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+// ---------------------------------------------------------------------------
+// Config snippet constants (pure — no side effects)
+// ---------------------------------------------------------------------------
+
+const CLAUDE_CODE_SNIPPET = `Claude Code — add to .claude/settings.json:
+{
+  "mcpServers": {
+    "logbook": {
+      "command": "logbook-mcp"
+    }
+  }
+}`
+
+const OPENCODE_SNIPPET = `OpenCode — add to opencode.json:
+{
+  "mcp": {
+    "logbook": {
+      "type": "local",
+      "command": ["logbook-mcp"],
+      "enabled": true
+    }
+  }
+}`
+
+const GITIGNORE_SNIPPET = `.gitignore — add these runtime files:
+tasks.jsonl
+sessions.json`
+
+const NEXT_STEPS = `Next steps:
+  1. Add the config snippet for your AI client
+  2. Run: LOGBOOK_TASKS_FILE=./tasks.jsonl logbook-mcp
+  3. In your AI client, call current_task() to verify — expected: no_current_task
+  4. See quickstart.md for the full walkthrough`
+
+// ---------------------------------------------------------------------------
+// Side-effecting helpers (file I/O at boundary)
+// ---------------------------------------------------------------------------
+
+const fileExists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const scaffoldTasksFile = async (cwd: string): Promise<void> => {
+  const path = join(cwd, "tasks.jsonl")
+  if (await fileExists(path)) {
+    console.log("✓ tasks.jsonl already exists, skipping")
+    return
+  }
+  await writeFile(path, "", "utf8")
+  console.log("✓ tasks.jsonl created")
+}
+
+const scaffoldHooksDir = async (cwd: string): Promise<void> => {
+  const path = join(cwd, "hooks")
+  if (await fileExists(path)) {
+    console.log("✓ hooks/ already exists, skipping")
+    return
+  }
+  await mkdir(path, { recursive: false })
+  console.log("✓ hooks/ created")
+}
+
+const printSnippets = (): void => {
+  console.log("")
+  console.log(CLAUDE_CODE_SNIPPET)
+  console.log("")
+  console.log(OPENCODE_SNIPPET)
+  console.log("")
+  console.log(GITIGNORE_SNIPPET)
+  console.log("")
+  console.log(NEXT_STEPS)
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export const runInit = async (cwd: string = process.cwd()): Promise<void> => {
+  await scaffoldTasksFile(cwd)
+  await scaffoldHooksDir(cwd)
+  printSnippets()
+}