Skip to the content
runstory

Set up a repository

Check your commits from the command line, your pushes with the GitHub App, or both.

Command line

Checks commits on your laptop

  1. Install

    It runs on macOS and Linux. The installer checks a signed manifest and needs no sudo.

    curl -fsSL https://runstory.vercel.app/install.sh | sh

  2. Sign in

    Approve the code in your browser.

    runstory login

  3. Set up the repository

    It shows the app and who pays, then installs the hooks.

    runstory init

  4. Commit as usual

    Each commit that changes the app gets a check. Results come back to your agent.

    runstory findings

GitHub App

Checks each push

  1. Connect GitHub

    Sign in, then connect the GitHub account that administers the repository. Open the GitHub App settings

  2. Install the App

    Choose repositories on GitHub. It reads contents and metadata, and writes checks.

  3. Choose the app and the limits

    Each provider runs its own agent, and each agent can spend up to $20.00 in a check.

    Under Environment variables, add each variable your app reads during a check, e.g. DATABASE_URL. Use test credentials.

  4. Push

    Each push to any branch gets one check after its CI passes. Read it from the Runstory Check in GitHub.

Results on your laptop

Run these once in each checkout. Each finished check of the branch you have checked out then arrives in it, whoever pushed it, and no new check is bought.

runstory login runstory init
A check of another branch

Name it by its number or its id to bring it into this checkout. Its findings are not applied there.

runstory show <check>
A personal check on an App repository

Your own account pays for it. Uncommitted edits are not included.

runstory run --personal
Check focus 7 lenses

A check explores your change as one kind of person would meet it. By default the service chooses 1 lens per commit.

LensPoint of view
First run first_runFirst use on a clean setup.
Wrong hands wrong_handsUnintended access or hostile input.
Changed mind changed_mindCancellation and interrupted work.
Claimed and not delivered claimed_not_deliveredPromises the app does not keep.
Somebody else's machine somebody_elses_machineDifferent machines or environments.
What leaves what_leavesOutput or changes left outside the app.
Underspecified underspecifiedGaps between conversation requests and behavior.
runstory run --focus <id,id,...|all>

What goes to TypeSafe when the service chooses

What source and evidence travel

The whole committed tree travels, including nested workspaces and committed conversation files. Choosing an app chooses what runs, not what is sent.

Checks screen source for secrets before upload, and screening can miss one. Do not commit credentials.

These services receive data during a check:

  • Vercel hosts the service.
  • Supabase stores the source and the evidence.
  • E2B runs the preparation and your app.
  • Clerk handles sign in.
  • The model providers you choose receive the source excerpts and app data their agents need. They are these:
    • Anthropic
    • OpenAI
    • DeepSeek
  • Package registries and the services your app calls receive its requests.

When this service chooses the focus automatically, a screened summary of the commit and any attributed coding requests go to TypeSafe in the United States. Checks started by a GitHub push send nothing to TypeSafe.

These are the limits on source:

  • A check holds at most 19 GiB of committed files, which is what fits on the check sandbox's disk beside the source archive and the dependencies.
  • A commit from the CLI may carry at most 512 MiB of compressed source, which is the most Runstory accepts for one check.
  • A push through the GitHub App may carry at most 512 MiB of compressed source, which is the most Runstory accepts for one check.
  • GitHub preparation fetches at most 4 GiB of Git objects, which is what the preparation sandbox's disk holds beside the archive and the written out files.
  • GitHub preparation runs in its own sandbox for at most 60 minutes, so no request to Runstory limits how long it takes.
  • The prepared push description may hold at most 1 MiB, and the full diff kept for comparison may hold at most 16 MiB.
  • GitHub delivers a push event of at most 4.2 MiB to Runstory, which is Vercel's limit on one request body. A larger delivery never reaches Runstory.
  • GitHub itself refuses one file over 100 MiB and one push over 1.8 GiB.

Data and storage says how long each kind of data stays.

Reading results

Read the coverage beside the result. An unconfirmed candidate is not a confirmed finding, and an incomplete run is not a clean result.

Set up a repository · Runstory