buildlog

Log your builds. buildlog is the Workflow Recorder CLI for Claude Code + Codex Local.

It installs the local hook wiring, parses session transcripts into metadata-only payloads, uploads them to your Workflow Recorder profile, and can backfill historical sessions from disk.

Guided Setup

New users should start with the web wizard:

https://app.workflowrecorder.com/start

It walks through runtime choice, the installer command, GitHub device-code approval, doctor output, and the first tracked session. Codex app users can start at:

https://app.workflowrecorder.com/start?surface=codex-app&runtime=codex

If you do not have Codex Local yet, install and open it first:

npm install -g @openai/codex
codex app

Then copy this prompt into Codex if you want agent-assisted setup:

Set up Workflow Recorder for Codex Local in this repo. First confirm Codex Local is available on this machine. Then run `npx -y @workflowrecorder/buildlog@latest init --runtime codex`, guide me through the GitHub device-code approval shown by the installer, run `npx -y @workflowrecorder/buildlog@latest doctor --runtime codex`, then run `npx -y @workflowrecorder/buildlog@latest link --plain` and paste my session link. Remind me that prompts, code, file contents, and outputs are not uploaded.

The Workflow Recorder package installs through that npx command: npx downloads @workflowrecorder/buildlog@latest from npm and runs it on demand. The installer shows a short GitHub device code to approve in your browser. If npx is missing, install Node.js first, then rerun setup.

Manual Install

Claude Code

npx -y @workflowrecorder/buildlog@latest init --runtime claude
npx -y @workflowrecorder/buildlog@latest doctor --runtime claude

Old sessions are not imported by default. To see useful recent history after setup, run buildlog backfill --runtime claude --days 10, or pass --backfill during buildlog init. Backfill includes source sessions that started inside the selected window and skips sessions too short to be useful.

Codex Local

npx -y @workflowrecorder/buildlog@latest init --runtime codex
npx -y @workflowrecorder/buildlog@latest doctor --runtime codex

Optional Codex backfill:

npx -y @workflowrecorder/buildlog@latest backfill --runtime codex --days 10

Backfill imports metadata from existing local transcripts. It uses the source session start time and never uploads prompts, code, file contents, or outputs.

Both runtimes share the same local auth/config file at ~/.buildlog/config.json.

Get Your Current Session Link

The easiest path is to ask Codex:

show me my Workflow Recorder link

The Codex setup installs a small Workflow Recorder skill so Codex knows to run:

npx -y @workflowrecorder/buildlog@latest link --plain

Manual fallback:

npx -y @workflowrecorder/buildlog@latest link

The installer uses GitHub OAuth Device Flow. If the browser does not open automatically, copy the printed GitHub URL and enter the short code shown in the terminal.

Optional: if you already cloned this repo and use the Codex app, you can also install the repo-local workflow-recorder plugin from .agents/plugins/marketplace.json for Workflow Recorder vocabulary and local setup guidance. The plugin guides Codex; the CLI still installs tracking.

Commands

| Command | What it does | |---|---| | buildlog init --runtime claude|codex|all | Link this machine, then wire Claude, Codex, or both. Plain buildlog init keeps the old default and wires Claude only. | | buildlog capture | Claude-compatible Stop hook entrypoint. | | buildlog capture-codex | Codex Stop hook entrypoint. | | buildlog backfill --runtime claude|codex [--days N \| --all] | Upload historical Claude or Codex sessions from disk. | | buildlog doctor --runtime claude|codex|all | Check config, hook wiring, endpoint reachability, outbox status, and recent uploads. | | buildlog sync | Drain the offline queue in ~/.buildlog/outbox/. | | buildlog link [--runtime claude\|codex\|all] [--plain\|--json] | Print the current Workflow Recorder session URL. Codex uploads the current transcript first when available. | | buildlog upload-current --runtime codex | Lower-level recovery command for uploading the current/latest Codex transcript. | | buildlog parse [--runtime claude|codex] <path> | Dry-run parser output for a single transcript file. |

Runtime Storage

Claude Code

• Hook config: ~/.claude/settings.json
• Backfill root: ~/.claude/projects
• Hook command: buildlog capture

Codex Local

• Hook config: ~/.codex/config.toml and ~/.codex/hooks.json
• Backfill root: ~/.codex/sessions/YYYY/MM/DD
• Hook command: buildlog capture-codex
• V1 wiring: Stop hook only
• Skill: ~/.codex/skills/workflow-recorder/SKILL.md

Privacy

On the wire, buildlog sends metadata only:

• timestamps and durations
• token totals
• message / ask counts
• tool counts
• commit counts
• hashed project slug
• model, runtime, source, and device labels

It never sends prompts, responses, code, file contents, file paths, diffs, tool arguments, or shell output.

Test Helpers

For local tests and sandboxed runs, these env vars redirect on-disk locations:

• BUILDLOG_HOME
• BUILDLOG_CLAUDE_HOME
• BUILDLOG_CODEX_HOME

License

MIT