devlog

Automated development journal for AI-assisted coding. Tracks Claude Code sessions and git history, generates structured development reports.

Prerequisites

• Node.js >= 18
• Claude Code (for session capture)
• Notion MCP server (optional, for syncing reports to Notion)

Install

npm install -g devlog

Quick Start

cd your-project
devlog init

That's it. devlog init does three things:

1. Creates .devlog/ directory with config
2. Adds .devlog/events/ and .devlog/state.json to .gitignore
3. Configures Claude Code hooks in .claude/settings.json for auto-capture

From now on, every Claude Code session is automatically captured when it ends.

Daily Workflow

You don't need to do anything. Hooks handle capture automatically.

When you want a report:

/devlog-report

This reads all captured events and generates a structured development report in .devlog/narrative.md, covering:

• What happened (chronological)
• Key decisions and why
• Turning points and failures
• Testing and verification
• Outcome and next steps

To sync the report to Notion:

/sync-devlog

Notion Sync (Optional)

1. Set up Notion MCP server

If you haven't already, configure the Notion MCP server in your Claude Code settings. You need:

• A Notion integration (create at https://www.notion.so/my-integrations)
• The integration's API token
• A Notion MCP server configured in Claude Code

2. Create a Notion database

Create a database in Notion with any structure you like (devlog will create Status, Type, and Tags fields if needed). Share the database with your Notion integration.

3. Configure sync

Add to .devlog/config.json:

"sync": {
  "notion": {
    "enabled": true,
    "database_id": "your-database-id",
    "data_source_id": "your-data-source-id"
  }
}

You can find these IDs by opening the database in Notion and checking the URL, or by querying the Notion API.

4. Sync

/sync-devlog

Each project gets its own page in the database. Running it again updates the existing page.

Using with Multiple Projects

cd ~/project-a
devlog init

cd ~/project-b
devlog init

Each project has its own .devlog/ directory, hooks, and events. They can share the same Notion database — each project is a separate entry.

Important: devlog init as early as possible. Sessions before init cannot be captured retroactively (git history can).

Manual Commands

| Command | Description | |---------|-------------| | devlog init | Initialize devlog + configure hooks | | devlog capture | Capture sessions and commits (usually auto) | | devlog capture --source git | Capture git commits only | | devlog capture --source claude-code | Capture Claude Code sessions only | | devlog notify | Check for pending events | | devlog status | Show event counts and report status | | devlog mcp | Start as MCP server (stdio) |

MCP Server

For AI tools to query and update the project report directly:

{
  "mcpServers": {
    "devlog": {
      "command": "devlog",
      "args": ["mcp"]
    }
  }
}

| Tool | Description | |------|-------------| | get_project_timeline | Chronological list of sessions and commits | | get_project_narrative | Current report | | get_pending_events | Events not yet in the report | | update_narrative | Save an updated report | | get_devlog_status | Overview stats |

How It Works

Claude Code session ends
    → Hook triggers devlog capture
    → Reads session transcript (messages, AI responses, tool errors, conversation flow)
    → Redacts sensitive data (API keys, tokens, passwords, JWTs, etc.)
    → Writes immutable event file to .devlog/events/

/devlog-report
    → AI reads all events
    → Generates structured report with decisions, turning points, testing
    → Saves to .devlog/narrative.md

/sync-devlog
    → Reads report + config
    → Creates/updates Notion page

Two-layer architecture:

• Events (.devlog/events/) — Immutable JSON, one per session or commit. Never modified.
• Report (.devlog/narrative.md) — AI-generated, regenerable from events at any time.

Security: All data stays local. 14 redaction patterns cover API keys, tokens, JWTs, private keys, connection strings, and more. Custom patterns configurable in .devlog/config.json.

License

MIT