buildstory

Automatically capture the story of what you build. Buildstory installs a git post-commit hook that silently ships commit metadata to a server, which uses AI to turn raw commits into human-readable project updates. Review, approve, and publish a public timeline of your work from the web dashboard.

Installation

npm install -g buildstory

Quick start

# 1. Save your API key
buildstory auth

# 2. Initialize in a git repo
cd your-project
buildstory init

# 3. Code and commit as usual — Buildstory captures each commit automatically
git add . && git commit -m "add user profiles"

# 4. Review and approve updates on the dashboard

Commands

| Command | Description | |---|---| | buildstory auth | Save your API key (stored in ~/.buildstory/credentials.json) | | buildstory init | Initialize Buildstory in the current git repo | | buildstory --help | Show help | | buildstory --version | Show version |

buildstory init options

| Flag | Description | Default | |---|---|---| | -e, --endpoint <url> | API endpoint | https://buildstory-cli.vercel.app |

You can also set the endpoint via the BUILDSTORY_ENDPOINT environment variable.

What data gets sent

Each commit sends the following to the Buildstory server:

• Commit hash, message, timestamp, and author
• Diff stats (files changed, insertions, deletions)
• List of changed files with per-file stats
• A truncated diff summary (first 50 lines of git diff --stat)
• Detected environment (Cursor, VS Code, shell, OS)

Secret redaction: The hook automatically redacts API keys, tokens, private keys, AWS keys, and connection strings from diff summaries before sending.

Files matching patterns in .buildstoryignore are excluded from the payload entirely.

Configuration files

| File | Scope | Purpose | |---|---|---| | ~/.buildstory/credentials.json | Global | API key for authentication | | .buildstory/config.json | Per-repo | Project ID, endpoint, machine ID | | .buildstoryignore | Per-repo | Glob patterns for files to exclude from commit data |

The .buildstory/ directory is automatically added to .gitignore during init.

License

MIT