project-logbook

Idea: Imagine returning from a week away to 50 tickets resolved by LLM agents. Instead of scanning endless diffs, a narrative timeline summarizes each change as a brief story, bringing you up to speed in minutes.

Project Logbook is an experimental CLI tool that automates documentation in agentic developer environments by generating a web-based timeline of recent changes. By establishing simple workflows and prompting guidelines for both humans and LLMs, it is currently best suited for smaller projects with a low-to-moderate volume of changes.

See CONTRIBUTING.md for the mandatory working protocol. (Or read this unauthorized, cynical review — also available in German — about how this project got dragged and saved.)

The Three-File Standard

Each entry in logbook/ consists of:

1. ticket.md: Requirements and specifications.
2. log.md: Technical chronological protocol (developer/AI scratchpad).
3. index.md: Polished narrative of the change (human-readable story).

Installation

npm i project-logbook -g

You can run the CLI using either logbook or the shortcut alias lb. For example, lb status works as a drop-in replacement for logbook status.

Commands

| Command | Description | |---|---| | logbook init | Initialize configuration and directory. | | logbook new <id> <slug> | Create a new entry folder with templates. Use -r or --research option to scaffold a Research Log with an auto-incrementing RES- ID. | | logbook start <id> | Mark a logbook entry as active (writes .logbook-active lockfile). The active entry is also auto-detected from the current Git branch — a branch named feat/LB-123-my-feature will automatically resolve to entry LB-123. | | logbook release | Release the active logbook entry (removes .logbook-active lockfile). | | logbook log <message> | Append a timestamped log entry to the active log.md. | | logbook list | List all logbook entries with their status. | | logbook status | Show current active logbook task, configuration settings, and statistics. | | logbook lint | Validate structure, frontmatter, and internal links. | | logbook build | Compile logbook entries into a static HTML site (default: public/). | | logbook preview | Build and open the logbook in your default browser. | | logbook upgrade | Synchronize core project files (like CONTRIBUTING.md) with latest templates. | | logbook steer | Output agentic protocol for AI assistants. |

Configuration

Running logbook init creates a .project-logbook configuration file in your project root. You can customize the following properties:

| Key | Type | Default | Description | |---|---|---|---| | projectName | string | "My Project" | Title shown on the generated static website. | | logbookDir | string | "logbook" | The directory where logbook entries are located. | | researchDir | string | "docs/research" | The directory where Research Logs are located. | | outputDir | string | "dist/logbook" | The output directory where the compiled website is built. | | adrDir | string | "docs/adr" | The directory where Architecture Decision Records (ADRs) are located. Set to null or omit to disable ADR integration. | | primaryColor | string | "#2563eb" | The theme's accent color (CSS variable --primary). Must be a hex code. | | jiraBaseUrl | string | undefined | Optional base URL of your Jira workspace (e.g. https://myorg.atlassian.net/browse/). Enables clickable Jira link buttons. | | jiraPrefix | string | undefined | Optional Jira project prefix (e.g. PROJ) used to validate IDs and auto-link issues. | | repositoryUrl | string | Auto-detected | Optional base web URL of your Git repository (e.g. https://github.com/org/repo). Automatically falls back to parsing your git remote URL if not specified. | | tags | object | See below | Optional configuration for categorization tags. |

Tags Configuration Example

{
  "projectName": "My API Gateway",
  "primaryColor": "#0f766e",
  "jiraBaseUrl": "https://mycompany.atlassian.net/browse/",
  "jiraPrefix": "GW",
  "tags": {
    "allowed": ["#bugfix", "#feature", "#refactor", "#security", "#performance"]
  }
}

Tests

The Demo App README must be compiled to html too!