logbook is a file-system kanban board for autonomous AI agents. It tracks epics, stories, tasks, and context entries across a structured lifecycle so agents and humans share a single source of truth without context bloat.

→ new here? see quickstart.md to get running in 5 minutes.

why logbook

autonomous agents work in parallel, forget context across sessions, and have no shared task state. logbook solves three problems:

human visibility — agents record every task they touch in a file the whole team can read and diff
agent coordination — task.current resolves FIFO per-session, so multiple agents can't claim the same task
context budget — structured JSONL with a DuckDB optional query layer lets agents find relevant records without loading the whole store

v2 adds: epics → stories → tasks hierarchy, reusable context entries (knowledge that survives across tasks), and Linear two-way sync as a first-class plugin.

quickstart

npm install -g @bosun-sh/logbook     # install the CLI
logbook init                         # scaffold .logbook/, configure MCP, optionally set up Linear
logbook task:create \
  --title "Implement login endpoint" \
  --description "JWT auth, see docs/auth.md" \
  --definition-of-done "Tests pass and endpoint is documented" \
  --project myapp --milestone v1
logbook task:list --status "*"

see quickstart.md for the full walkthrough including Linear sync.

for one-off local use, run commands through your package manager, for example npx @bosun-sh/logbook --help or bunx @bosun-sh/logbook --help.

workspace layout

logbook init creates the following structure through workspace.init:

.logbook/
├── config.json           # workspace config (Linear credentials, hook overrides)
├── workspace.json        # workspace metadata
├── hooks/
│   ├── review-spawn/     # spawns a reviewer agent on pending_review
│   │   ├── config.json
│   │   └── script.mjs
│   └── need-info-notify/ # notifies user when a task needs info
│       ├── config.json
│       └── script.mjs
└── storage/
    ├── epics.jsonl
    ├── stories.jsonl
    ├── tasks.jsonl
    ├── context-entries.jsonl
    ├── external-links.jsonl
    ├── sync-events.jsonl
    └── sync-conflicts.jsonl

add .logbook/storage/ to .gitignore to keep runtime data out of version control:

.logbook/storage/

mcp tools by plugin

connect logbook mcp as an MCP server and call any of the 38 tools below.

task plugin

Tool ID	Purpose
`task.create`	Create a task in backlog
`task.get`	Load one task by id
`task.list`	List tasks (default status: `in_progress`)
`task.current`	Claim and return the highest-priority in-progress task for this session
`task.update`	Transition task status, add comments, reply to need_info
`task.edit`	Edit mutable fields without status change
`task.assign.session`	Assign a session to a task
`task.assign.model`	Assign a model to a task
`task.assign.phase-model`	Set a per-phase model override
`task.estimate`	Compute or re-compute a Fibonacci estimation

task.current priority chain: session-owned in_progress → unassigned in_progress → orphaned in_progress (dead session) → highest-priority todo (auto-transitions) → no_current_task error.

epic plugin

Tool ID	Purpose
`epic.create`	Create an epic
`epic.get`	Load one epic
`epic.list`	List epics
`epic.update`	Update an epic
`epic.delete`	Tombstone an epic

story plugin

Tool ID	Purpose
`story.create`	Create a story within an epic
`story.get`	Load one story
`story.list`	List stories
`story.update`	Update a story
`story.delete`	Tombstone a story

context plugin

Tool ID	Purpose
`context.create`	Create a reusable context entry
`context.get`	Load one context entry
`context.list`	List context entries
`context.update`	Update a context entry
`context.delete`	Tombstone a context entry
`context.attach`	Attach a context entry to an epic, story, or task
`context.detach`	Remove an attachment
`context.search`	Full-text search over context entries

sync plugin (Linear)

Tool ID	Purpose
`sync.linear.pull`	Pull issues from Linear into logbook (since-cursor pagination)
`sync.linear.push`	Push logbook tasks to Linear
`sync.linear.setup`	Configure Linear sync from a team URL or explicit ids
`sync.linear.status`	Check Linear configuration and connectivity
`sync.conflicts.list`	List unresolved sync conflicts
`sync.conflicts.resolve`	Resolve a conflict (`use_local`, `use_remote`, or `manual`)

workspace plugin

Tool ID	Purpose
`workspace.init`	Initialize or re-scaffold the `.logbook/` workspace
`workspace.status`	Report workspace health and provider status

hook plugin

Tool ID	Purpose
`hook.list`	List registered hooks
`hook.run`	Run a hook manually

plugin plugin

Tool ID	Purpose
`plugin.list`	List all registered plugins and their tool IDs

cli

every tool is available as logbook <tool-id-with-colons>:

# preferred onboarding
logbook init
logbook init --mcp-client claude --no-linear

# workspace
logbook workspace:init
logbook workspace:status

# tasks
logbook task:create --title "x" --description "y" --definition-of-done "z" --project p --milestone m
logbook task:list --status "*"
logbook task:list --status in_progress
logbook task:current
logbook task:update --id <uuid> --new-status pending_review
logbook task:edit --id <uuid> --title "New title"

# epics and stories
logbook epic:create --title "Auth" --description "Login and session management" --outcome "Users can log in"
logbook story:create --epic-id <uuid> --title "JWT login" --description "..." --user-value "Users can authenticate"

# context
logbook context:create --title "Auth spec" --body "Use JWT RS256. See docs/auth.md."
logbook context:attach --context-entry-id <uuid> --task-id <uuid>

# Linear sync
logbook sync:linear:setup --team-url https://linear.app/<workspace>/team/<team>
logbook sync:linear:pull
logbook sync:linear:push --dry-run
logbook sync:linear:status

# v1 aliases (still work, emit a compatibility warning)
logbook create-task --title "..." --definition-of-done "..." --predicted-k-tokens 3
logbook list-tasks --status in_progress

all commands write a single-line JSON envelope to stdout:

{"ok":true,"data":{"task":{...}}}
{"ok":false,"error":{"code":"not_found","message":"task abc was not found"}}

linear integration

setup

The preferred setup path is logbook init, which prompts for Linear sync setup. To configure Linear separately:

create a Linear API key at Linear → Settings → API → Personal API keys

add it to .env or export it in your shell:

echo "LINEAR_API_KEY=lin_api_..." >> .env

configure Logbook from your Linear team URL:

logbook sync:linear:setup --team-url https://linear.app/bosun/team/BOSUN

The setup command resolves the workspace and team ids and writes the public config to .logbook/config.json. It never writes the API key there. To let setup write .env for you, pass the token once:

logbook sync:linear:setup \
  --team-url https://linear.app/bosun/team/BOSUN \
  --api-token lin_api_... \
  --write-env

Manual setup is also supported:

logbook sync:linear:setup \
  --workspace-id <workspace-id> \
  --team-id <team-id>

This produces a linear block like:

{
  "linear": {
    "apiTokenEnv": "LINEAR_API_KEY",
    "workspaceId": "your-workspace-id",
    "defaultTeamId": "your-team-id"
  }
}

pull / push

when Logbook runs through MCP, task-facing tools automatically pull before the call and push successful task writes back to Linear. the explicit commands below are still available for manual refreshes, dry runs, and targeted syncs.

# pull issues from Linear since the last cursor
logbook sync:linear:pull

# pull with options
logbook sync:linear:pull --dry-run --team-id <id>

# push logbook tasks to Linear
logbook sync:linear:push

# push only specific tasks
logbook sync:linear:push --task-ids '["task_abc","task_xyz"]' --dry-run

# check status (connectivity + cursor position)
logbook sync:linear:status --check-provider

conflicts

when the same record is modified in both logbook and Linear, a conflict entry is written to sync-conflicts.jsonl:

logbook sync:conflicts:list
logbook sync:conflicts:resolve --id <conflict-uuid> --resolution use_local
# resolutions: use_local | use_remote | manual

conflict states: open → resolved or ignored.

external links

bidirectional linear:<id> mappings are stored in external-links.jsonl and updated automatically by pull/push.

hooks

hooks execute shell commands on task lifecycle events. configuration lives in .logbook/hooks/<id>/config.json:

{
  "id": "need-info-notify",
  "event": "task.status_changed",
  "condition": { "status": "need_info" },
  "command": ["node", ".logbook/hooks/need-info-notify/script.mjs"],
  "timeoutMs": 5000
}

two hooks are materialized by workspace.init:

need-info-notify — prints the blocking comment when a task moves to need_info
review-spawn — creates a review task and spawns a reviewer agent when a task moves to pending_review

hooks are stateless — execute and forget. the command field is an argv array; no shell expansion is performed.

environment variables

Variable	Default	Description
`LOGBOOK_WORKSPACE_ROOT`	`process.cwd()`	workspace root used by the compiled binaries
`LOGBOOK_LOG_LEVEL`	`warn`	log level: `debug`, `info`, `warn`, `error`
`LINEAR_API_KEY`	—	Linear API token (or the env var named in `linear.apiTokenEnv`)

optional duckdb index

logbook uses @duckdb/node-api to run ad-hoc SQL over the canonical JSONL files. the index is in-memory — no separate index file is written or maintained:

-- example: find all in_progress tasks for a specific project
SELECT id, title, status FROM read_json_auto('.logbook/storage/tasks.jsonl', format='newline_delimited')
WHERE status = 'in_progress' AND project = 'myapp'

the DuckDB path is opt-in via workspace.status and is non-canonical — the JSONL files remain the source of truth.

migrating from v1

if your project has a tasks.jsonl at the repository root, workspace.init detects it and migrates all records to .logbook/storage/tasks.jsonl automatically:

field names renamed from snake_case to camelCase
kind: "task" injected on every record
v1 comment shape converted to v2 shape

v1 CLI commands (create-task, list-tasks, current-task, update-task, edit-task, init) remain registered and emit a compatibility_mapping_applied warning. remove the deprecated commands from your scripts when ready.

see CHANGELOG.md for the full v2.0.0 breaking-change list.

stack

runtime: Node.js / TypeScript
effect system: Effect.ts — all async operations and errors modeled as Effect<A, E, R>
architecture: ohtools plugin registry, hexagonal adapters (CLI + MCP), vertical slices per entity
persistence: JSONL — append-only, one record per line, full-scan reads; DuckDB for optional ad-hoc queries
validation: Zod at every public boundary (MCP input, CLI flags, filesystem reads)

FAQs

What is @bosun-sh/logbook?

Is @bosun-sh/logbook well maintained?

Package last updated on 13 May 2026

@bosun-sh/logbook

logbook — kanban for ai agents