logbook-mcp 0.2.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,141 @@
+# logbook: kanban for ai agents
+
+logbook is a kanban board implementation for autonomous agentic development, focusing on autonomous development and context window management.
+
+## 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 current task _(only task in_progress)_
+- the agent can call `update_task(id, new_status, new_comment)` and update the tasks to the new status adding a comment to justify it
+
+each one of this tools-and more to add-have the sole purpose of removing overload from the agent context, handling the _"heavy load"_ programatically on the mcp server.
+
+## 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.
+
+#### 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 scale
+  comments: Comment[],
+  assignee: Agent,
+  status: Status,
+  in_progress_since?: Date // set when task enters in_progress; drives FIFO ordering in current_task
+}
+
+// status defaults to 'in_progress'
+type ListTasks = (status: Status | '*') => Task[]
+
+// returns the highest-priority in_progress task for the current session.
+// 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
+type UpdateTask = (id: string, new_status: Status, comment: Comment | null, sessionId: string) => void
+
+// creates a new task in backlog assigned to the calling session
+type CreateTask = (input: CreateTaskInput, sessionId: string) => Task
+
+// edits mutable fields without changing status
+type EditTask = (id: string, updates: EditTaskInput) => Task
+```
+
+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.
+
+## 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.

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,93 @@
+#!/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)
+
+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 --task "review task ${reviewId}"`,
+  { stdio: "inherit", env: { ...process.env, LOGBOOK_TASKS_FILE: dataFile } }
+)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "logbook-mcp",
+  "version": "0.2.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"
+  },
+  "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/domain/fibonacci.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect"
+import type { TaskError } from "./types.js"
+
+/**
+ * Validates that n is a positive Fibonacci number.
+ * Returns Effect.succeed(void) when valid,
+ * Effect.fail({ _tag: 'validation_error', message: 'estimation must be a Fibonacci number' }) otherwise.
+ *
+ * Algorithm: n is Fibonacci iff one of 5n²+4 or 5n²-4 is a perfect square.
+ */
+export const validateFibonacci = (n: number): Effect.Effect<void, TaskError> => {
+  // Must be a positive integer
+  if (!Number.isInteger(n) || n <= 0) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "estimation must be a Fibonacci number",
+    })
+  }
+
+  // Check if a number is a perfect square
+  const isPerfectSquare = (num: number): boolean => {
+    if (num < 0) return false
+    const sqrt = Math.sqrt(num)
+    return sqrt === Math.floor(sqrt)
+  }
+
+  // n is Fibonacci iff 5n²+4 or 5n²-4 is a perfect square
+  const fiveSqPlusFour = 5 * n * n + 4
+  const fiveSqMinusFour = 5 * n * n - 4
+
+  if (isPerfectSquare(fiveSqPlusFour) || isPerfectSquare(fiveSqMinusFour)) {
+    return Effect.succeed(void 0)
+  }
+
+  return Effect.fail({
+    _tag: "validation_error",
+    message: "estimation must be a Fibonacci number",
+  })
+}

package/src/domain/kTokens.ts

@@ -0,0 +1,65 @@
+import { Effect } from "effect"
+import type { TaskError } from "./types.js"
+
+export interface KTokensConfig {
+  anchorPoint: number // Fibonacci number to anchor against
+  kTokensAtAnchor: number // how many kTokens map to anchorPoint
+  maxKTokens: number // cap (inclusive)
+}
+
+export const defaultConfig: KTokensConfig = {
+  anchorPoint: 8,
+  kTokensAtAnchor: 20,
+  maxKTokens: 20,
+}
+
+// Fibonacci sequence for lookup
+const FIBONACCI = [1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144]
+
+export const estimateFromKTokens = (
+  kTokens: number,
+  config: KTokensConfig = defaultConfig
+): Effect.Effect<number, TaskError> => {
+  // Fail if kTokens <= 0
+  if (kTokens <= 0) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "predicted kilotokens must be positive",
+    })
+  }
+
+  // Fail if kTokens > config.maxKTokens
+  if (kTokens > config.maxKTokens) {
+    return Effect.fail({
+      _tag: "validation_error",
+      message: "predicted kilotokens exceed maximum allowed",
+    })
+  }
+
+  // Calculate ratio: kTokensAtAnchor / anchorPoint
+  const ratio = config.kTokensAtAnchor / config.anchorPoint
+
+  // Scale kTokens to estimate space
+  const scaled = kTokens / ratio
+
+  // Find nearest Fibonacci number, rounding UP on tie
+  let nearestFib: number = FIBONACCI[0] ?? 1
+  let minDistance = Math.abs(nearestFib - scaled)
+
+  for (const fib of FIBONACCI) {
+    const distance = Math.abs(fib - scaled)
+
+    // On exact match, return immediately
+    if (distance === 0) {
+      return Effect.succeed(fib)
+    }
+
+    // On tie, pick the larger value (UP)
+    if (distance < minDistance || (distance === minDistance && fib > nearestFib)) {
+      nearestFib = fib
+      minDistance = distance
+    }
+  }
+
+  return Effect.succeed(nearestFib)
+}

package/src/domain/status-machine.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect"
+import type { Status, TaskError } from "./types.js"
+
+// Allowed state transitions: from → [to, to, ...]
+const allowedTransitions: Record<Status, Status[]> = {
+  backlog: ["todo"],
+  todo: ["backlog", "in_progress"],
+  in_progress: ["todo", "pending_review", "need_info", "blocked"],
+  blocked: ["in_progress"],
+  need_info: ["in_progress"],
+  pending_review: ["done", "in_progress"],
+  done: [],
+}
+
+/**
+ * Guards a status transition, returning Effect.succeed(void) when allowed
+ * and Effect.fail({ _tag: 'transition_not_allowed', from, to }) otherwise.
+ * A same→same transition is always a no-op success.
+ */
+export const guardTransition = (from: Status, to: Status): Effect.Effect<void, TaskError> => {
+  // Same→same is always a no-op success
+  if (from === to) {
+    return Effect.void
+  }
+
+  // Check if transition is in the allowed map
+  const allowed = allowedTransitions[from]
+  if (allowed.includes(to)) {
+    return Effect.void
+  }
+
+  // Transition not allowed
+  return Effect.fail({
+    _tag: "transition_not_allowed",
+    from,
+    to,
+  } as TaskError)
+}

package/src/domain/types.ts

@@ -0,0 +1,56 @@
+import { z } from "zod"
+
+export const StatusSchema = z.enum([
+  "backlog",
+  "todo",
+  "need_info",
+  "blocked",
+  "in_progress",
+  "pending_review",
+  "done",
+])
+export type Status = z.infer<typeof StatusSchema>
+
+export const CommentKindSchema = z.enum(["need_info", "regular"])
+export type CommentKind = z.infer<typeof CommentKindSchema>
+
+export const CommentSchema = z.object({
+  id: z.string().min(1),
+  timestamp: z.coerce.date(),
+  title: z.string().min(1),
+  content: z.string(),
+  reply: z.string(),
+  kind: CommentKindSchema,
+})
+export type Comment = z.infer<typeof CommentSchema>
+
+export const AgentSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+})
+export type Agent = z.infer<typeof AgentSchema>
+
+export const TaskSchema = z.object({
+  project: z.string().min(1),
+  milestone: z.string().min(1),
+  id: z.string().min(1),
+  title: z.string().min(1),
+  definition_of_done: z.string().min(1),
+  description: z.string().min(1),
+  estimation: z.number().int().positive(),
+  comments: z.array(CommentSchema),
+  assignee: AgentSchema,
+  status: StatusSchema,
+  in_progress_since: z.coerce.date().optional(),
+})
+export type Task = z.infer<typeof TaskSchema>
+
+// Error tags match Gherkin feature file error names
+export type TaskError =
+  | { readonly _tag: "not_found"; readonly taskId: string }
+  | { readonly _tag: "transition_not_allowed"; readonly from: Status; readonly to: Status }
+  | { readonly _tag: "validation_error"; readonly message: string }
+  | { readonly _tag: "missing_comment" }
+  | { readonly _tag: "conflict"; readonly taskId: string }
+  | { readonly _tag: "no_current_task" }

package/src/hook/hook-executor.ts

@@ -0,0 +1,70 @@
+import { Effect } from "effect"
+import type { HookEvent } from "./ports.js"
+
+export interface HookConfig {
+  event: string
+  condition?: string
+  timeout_ms?: number
+  script: string
+}
+
+const HOOK_EVENT_NAME = "task.status_changed"
+const DEFAULT_TIMEOUT_MS = 5000
+
+const evaluateCondition = (condition: string, event: HookEvent): boolean => {
+  try {
+    const fn = new Function(
+      "new_status",
+      "old_status",
+      "task_id",
+      "session_id",
+      `return (${condition})`
+    )
+    return Boolean(fn(event.new_status, event.old_status, event.task_id, event.session_id))
+  } catch {
+    return false
+  }
+}
+
+const runScript = (config: HookConfig, event: HookEvent): Promise<void> =>
+  new Promise((resolve) => {
+    const timeoutMs = config.timeout_ms ?? DEFAULT_TIMEOUT_MS
+
+    const cmd = config.script.endsWith(".ts") ? ["bun", config.script] : ["sh", "-c", config.script]
+
+    const child = Bun.spawn(cmd, {
+      env: {
+        ...process.env,
+        LOGBOOK_TASK_ID: event.task_id,
+        LOGBOOK_OLD_STATUS: event.old_status,
+        LOGBOOK_NEW_STATUS: event.new_status,
+        LOGBOOK_SESSION_ID: event.session_id,
+      },
+    })
+
+    const timer = setTimeout(() => {
+      child.kill()
+    }, timeoutMs)
+
+    void (async () => {
+      try {
+        await child.exited
+      } finally {
+        clearTimeout(timer)
+        resolve()
+      }
+    })()
+  })
+
+export const executeHooks = (
+  event: HookEvent,
+  configs: readonly HookConfig[]
+): Effect.Effect<void, never> =>
+  Effect.promise(async () => {
+    await Promise.all(
+      configs
+        .filter((c) => c.event === HOOK_EVENT_NAME)
+        .filter((c) => !c.condition || evaluateCondition(c.condition, event))
+        .map((c) => runScript(c, event))
+    )
+  })

package/src/hook/ports.ts

@@ -0,0 +1,16 @@
+import { Context, type Effect } from "effect"
+import type { Comment, Status } from "../domain/types.js"
+
+export interface HookEvent {
+  task_id: string
+  old_status: Status
+  new_status: Status
+  comment: Comment | null
+  session_id: string
+}
+
+export interface HookRunner {
+  run(event: HookEvent): Effect.Effect<void, never>
+}
+
+export const HookRunner = Context.GenericTag<HookRunner>("HookRunner")