buildarc

Your build story, recovered.

buildarc reads your Claude Code conversation transcripts and turns them into shareable content — X threads, LinkedIn posts, build journals. One command, zero config.

npx buildarc

From 47 Claude Code sessions to an X thread

45 Claude Code sessions into one tool and I mass-deleted the
landing page three times before I realized the problem wasn't
the design — it was the pitch.

I'd been describing features nobody asked about to an audience
I hadn't defined. So I closed the editor and read my own
transcripts. The pivots, the dead ends, the moment I scrapped
the database and started over with flat files.

The story was right there. I just hadn't been reading it.
Shipped the landing page in one session after that.

That realization became buildarc — one command to recover
your build story from Claude Code sessions.

npx buildarc

That's real output. One command, from raw transcripts to a ready-to-post thread with a CTA.

Quick start

1. Build something with Claude Code (you probably already have)
2. Run npx buildarc in your project directory
3. Pick your format — X thread, LinkedIn, journal, or all three

Features

• One command — npx buildarc, auto-detects your project, no config
• Three formats — X threads, LinkedIn posts, build journals (with style variants)
• Two layers — Instant extraction + AI storytelling via your claude CLI
• Project-aware — Reads your package.json and git remote for CTAs and specifics
• Zero dependencies — Pure Node.js built-ins, installs in seconds
• Privacy-first — Everything runs locally, no data transmitted, no telemetry
• Secret scrubbing — API keys, tokens, and connection strings redacted automatically
• Retroactive — Works on sessions that already happened

Why buildarc

vs. doing nothing — This is the real alternative. You finish building, think "I should post about this," then don't. The activation energy is too high. buildarc makes it one command.

vs. pasting into ChatGPT — Works for one session. Try it with 50 sessions and hundreds of megabytes of .jsonl files. buildarc processes them all in seconds and outputs content formatted for the platform you're posting to.

vs. git log — Commit history shows what changed in code. It doesn't capture why you dropped the database, why you pivoted from a web app to a CLI, or the moment you almost quit. buildarc recovers the "why."

vs. manual journaling — You've told yourself you'll keep build notes after every session. How's that going? buildarc works retroactively — it recovers stories from sessions that already happened.

How it works

  buildarc v0.2.2

  Reading your Claude Code sessions...
  Found 14 sessions | 47 moments | 12 decisions, 3 pivots

  Build summary saved to .buildarc/BUILDARC.md

  What do you want to share?

    1. X thread
    2. LinkedIn post
    3. Build journal
    4. All of the above
    5. Just the summary

Two layers — extraction is instant, storytelling is AI:

1. Parse — Streams your .jsonl transcript files, filters to the meaningful messages
2. Extract — Classifies key moments: decisions, pivots, emotions, directives, questions
3. Scrub — Redacts API keys, tokens, and secrets before anything becomes shareable
4. Format — Writes a structured build summary (Markdown or JSON)
5. Story — Sends the summary to Claude to write your post in your voice
6. Ship — Saves the content to .buildarc/ — copy, paste, done

Zero runtime dependencies. Your data stays local. The AI step uses your existing Claude Code installation.

# BUILDARC.md

> Generated by buildarc on 2026-02-24
> Project: ~/.claude/projects/-Users-you-projects-my-app

## Summary

- **Sessions:** 47
- **Moments:** 183
- **Decisions:** 12 | **Pivots:** 3 | **Emotions:** 24
- **Directives:** 89 | **Questions:** 55
- **Date range:** 2026-01-08 → 2026-02-22
- **Top tools:** Write (341), Edit (289), Bash (187), Read (156)

## Key moments

> These are the highest-signal moments. The full timeline follows below.

- [DECISION] (you) Let's drop the database entirely — flat JSON files are fine for this
- [PIVOT] (you) Actually scratch the dashboard. This should be a CLI, not a web app
- [DECISION] (claude) Splitting the pipeline into two layers: instant extraction + AI storytelling
- [EMOTION] (you) This is actually working. The output is genuinely good
- [PIVOT] (you) The pricing page is wrong — this should be free and open source
- [DECISION] (you) Zero runtime dependencies. Node built-ins only. Non-negotiable
- [EMOTION] (you) I mass-deleted everything and started over. Third time this week

Install

# Run directly (recommended)
npx buildarc

# Or install globally
npm install -g buildarc

Usage

# Auto-detect project from current directory
buildarc

# Generate an X thread (skip the menu — thread is the default style)
buildarc --tweet

# Single literary post instead of a thread
buildarc --tweet --style narrative

# Shitpost-style X thread (absurdist daylog)
buildarc --tweet --style shitpost

# Generate everything at once
buildarc --tweet --linkedin --journal

# Extraction only, no AI
buildarc --no-ai

# Last 5 sessions, JSON output
buildarc --sessions 5 --format json

# Explicit project path
buildarc ~/.claude/projects/-Users-you-projects-my-app/

--format <md|json>   Output format (default: md)
--since <DATE>       Only sessions after this date (YYYY-MM-DD)
--sessions <N>       Last N sessions only
--output, -o <DIR>   Output directory (default: .buildarc/)
--no-ai              Extraction only, skip content generation
--tweet              Generate X thread
--linkedin           Generate LinkedIn post
--journal            Generate build journal
--style <name>       Content style variant (e.g. thread, narrative, shitpost)
-q, --quiet          Minimal output
-h, --help           Show help
-v, --version        Show version

Flags are combinable: buildarc --tweet --linkedin generates both without the interactive menu.

Origin story

buildarc was born from building ScoutAgent — a SaaS that didn't work out. 45+ Claude Code sessions of building, pivoting, and learning. When the project wound down, the story of that build almost disappeared into unread .jsonl files. buildarc exists because the content should have been easy to write but wasn't.

This README was informed by buildarc's own output. Dogfooding all the way down.

Requirements

• Node.js >= 18
• Claude Code — buildarc uses your existing Claude installation for the AI storytelling step. Without it, you still get the extraction summary. Install Claude Code

Output

Everything goes to .buildarc/ in your project root:

• BUILDARC.md — Structured build summary with all moments, grouped by date
• tweet.md — Ready-to-paste X thread
• linkedin.md — Ready-to-paste LinkedIn post
• journal.md — Build journal entry

buildarc automatically scrubs secrets from your extracted moments before they reach shareable content:

• API keys (OpenAI, GitHub, AWS, Stripe, Slack)
• Bearer tokens
• Connection strings (PostgreSQL, MongoDB, Redis, MySQL, AMQP)
• Environment variable secrets (DATABASE_URL=..., API_KEY=..., JWT_SECRET=..., etc.)
• Generic secret assignments (token=, password=, credentials=)

Matches are replaced with [REDACTED] — visible, not silent. See SECURITY.md for the full list and limitations.

Contributing

Contributions welcome. See CONTRIBUTING.md for setup, architecture, and code style.

Good first issues are labeled good first issue.

Links

• npm
• Changelog
• Contributing
• Security
• Roadmap
• License