buildarc

Your build story, recovered.

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

npx buildarc

Alpha (v0.x) — The core pipeline works. Output quality is being tuned. Feedback welcome.

See what you get

Run npx buildarc --tweet on a project with 47 sessions. This is what comes back:

Generated tweet thread:

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. Forty sessions of building a tool
and I still couldn't say what it did in one sentence.

So I closed the editor and opened the transcripts. Read through
weeks of conversations — 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. Turns out
the copy writes itself when you know what actually happened.

# 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

The extraction finds the moments. Your Claude turns them into a story.

Quick start

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

Features

• One command — npx buildarc, auto-detects your project, no config
• Three formats — Tweet threads, LinkedIn posts, build journals
• Two layers — Instant heuristic extraction + AI storytelling via your claude CLI
• 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

What it does

You build things with Claude Code. Those sessions contain decisions, pivots, breakthroughs, and dead ends — a story. buildarc finds that story and helps you share it.

  buildarc v0.1.0

  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. Tweet thread
    2. LinkedIn post
    3. Build journal
    4. All of the above
    5. Just the summary

How it works

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.

Install

# Run directly (recommended)
npx buildarc

# Or install globally
npm install -g buildarc

Usage

# Auto-detect project from current directory
buildarc

# Generate a tweet thread (skip the menu)
buildarc --tweet

# Shitpost-style tweet
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/

Flags

--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/Twitter thread
--linkedin           Generate LinkedIn post
--journal            Generate build journal
--style <name>       Content style variant (e.g. 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.

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.

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.

What gets redacted

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.

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 tweet thread
• linkedin.md — Ready-to-paste LinkedIn post
• journal.md — Build journal entry

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

npx buildarc

Your build story, recovered.