Getting started

BuildGist was called RunStory before version 0.4. It now lives at buildgist.com, and existing accounts sign in the same way.

1. What you need

• A Mac with Apple silicon (M1 or later) for BuildGist for Mac, which needs no terminal. On Linux or an Intel Mac, the command-line setup below needs Python 3.9 or newer and pipx. Windows is not supported yet.
• Claude Code, Cursor or Codex, used in a Git project (git init is enough). BuildGist works from your working copy as you code: no commit, push, remote or GitHub repository is needed.
• For explanations: Claude Code (the claude command), signed in. BuildGist explains runs on your computer with it, under your own Claude account rather than BuildGist's, whichever agent made the run; Claude Code sends the run's changes and what you asked for to Anthropic to do it. Without it, BuildGist still captures runs.
• A GitHub account, to sign in. That is all GitHub is used for: BuildGist asks for no access to your repositories.

2. Sign in

Sign in with GitHub. Your account is created the first time.

On a Mac: the welcome page then offers BuildGist for Mac. Open it, choose Connect, then Set up my coding agents, and skip to step 6.

On Linux, an Intel Mac, or if you prefer a terminal, continue here.

Installed before 0.4? The runstory command still works.

3. Install

BuildGist runs on your computer (macOS or Linux, Python 3.9 or newer, with pipx). In a terminal:

pipx install "https://buildgist.com/downloads/runstory-0.4.0-py3-none-any.whl#sha256=25a2aeec73c6878d49d5d3305f42d9114ac1e8957eafcab96b841183268071aa"

Version 0.4.0 · build df4b61366a50 · SHA-256 25a2aeec73c6878d49d5d3305f42d9114ac1e8957eafcab96b841183268071aa. pip checks the hash before installing. Already installed? Add --force to upgrade.

4. Connect

In BuildGist Settings, choose Get a connection code, then:

buildgist connect ABCD-1234

It shows exactly what will be sent and asks before connecting.

5. Set up your coding agents, once

buildgist setup --global

This adds BuildGist's hook to each agent it finds, in the agent's own settings, so every project the agent works in is recorded. There is no per-project step. Claude Code picks the change up in a new conversation. Codex asks you to trust BuildGist's hooks once, in its own settings; buildgist setup --global lists the steps and buildgist doctor shows when it is done. (Prefer one project at a time? Run buildgist setup inside it instead.)

6. Code normally

Meaningful runs are explained on your computer and appear in your Inbox automatically, from uncommitted work too, including a brand-new project once it is a Git repository. Small changes stay quiet.

See what leaves, and check on it

buildgist what-leaves --details   # exactly what is sent
buildgist sync status             # what was sent, and when
buildgist doctor                  # everything checked in one place

Stop, or remove it

In BuildGist for Mac: Disconnect this Mac, or Uninstall…, which lists what it will remove first and never touches your projects. With the command line:

buildgist disconnect              # stop syncing; local BuildGist keeps working
buildgist uninstall --global      # remove BuildGist from your agents' settings
buildgist uninstall               # in a project set up on its own: remove its hooks
pipx uninstall runstory           # remove BuildGist

Delete your cloud data from Settings → Delete my account.

Known limitations

• Explanations need Claude Code on your computer.
• A project must be a Git repository (git init); a plain folder is not captured.
• Edits you make by hand between two agent turns are included in the next run. Attribution is per file: a file you and the agent both edited is described as the agent's work, and a turn in which the agent changed nothing can produce an explanation of your own edits.
• A repository BuildGist first saw with no commits is its own project; a clone of it (on another computer, or a fresh checkout) appears as a separate project.
• Coverage differs by agent; edits made by shell commands or sub-agents can be attributed less precisely.
• Secret masking is best-effort, and cited excerpts of changed code are sent (at most 12 lines each) unless you turn them off: buildgist config set egress.send_excerpts off.
• The Current task summary can occasionally misread an instruction.
• Windows is not supported yet.

Help

In BuildGist for Mac, the window shows whether each coding agent is set up. On the command line, buildgist doctor checks every step. Then kayvanandre@gmail.com.