Docs
Open Babbit

Guides

Create a project

A project is one product. You can start one from code you already have, or from a sentence. Either way, Babbit drafts the spec and you approve it.

Before you begin

  • Connect your agent account. Babbit asks for one before you can create a project.
  • You must be an owner of the GitHub organization that holds your code, or will hold it. Babbit refuses a project from someone who isn't, and says so beside the button.

Connect existing repositories

  1. Click New project.
  2. If no organization of yours has Babbit's GitHub app, click Install on GitHub. GitHub opens in a new tab.
    1. Choose the organization.
    2. Choose all repositories, or only the ones that make up your product.
    3. Click Install, then return to the Babbit tab. Babbit reads the list again when you come back.
  3. Select the repositories for this product. A web app, its API and its mobile app are one product, so they belong in one project.
  4. Click Connect repositories.

What the GitHub app can do

Babbit readsBabbit writes
Your code.Branches under change/ and newdev/ only.
Pushes, so it can read drift.Pull requests, and merges of the ones you approved.
Pull request events.Check runs on pull request heads.

The app never writes your default branch directly and doesn't ask for the workflows permission. See GitHub, branches and check runs.

Watch Babbit read the code

Reading starts as soon as you connect. The Product agent works through three steps:

StepWhat happens
FetchBabbit copies the repositories into a workspace.
IndexBabbit lists every way into the code: each HTTP route and the function that answers it, each program's entry point, every table, every test and every screen.
InvestigateThe Product agent follows behavior through the code and saves each capability it finds, with its goals, its scenarios and the source lines that show them. It also saves an architecture map.

Features appear on the onboarding map as the agent saves them. Select one to see its goals, children and scenarios beside the map.

The agent's access to your source is read-only. It reads and searches; it doesn't run your application, build it or run its tests, and reading the source never counts as a passing test. You can close the tab at any time. The work continues, and Babbit records it so you can replay it later.

Review and approve the tree

When reading finishes, Babbit shows the drafted feature tree: each feature with its children and how many goals and scenarios it has.

  1. Click a feature to open it in place. Its goals are numbered, each over its scenarios. Each scenario shows how strongly the code supports it, with the citation on hover.
  2. Look for features marked with a doubt, such as child? 0.52. Babbit drafted them anyway and says what it doubted.
  3. Open the line above the tree that counts what was read but isn't in any feature: routes, screens, tables or tests. Each one says why it was left out.
  4. Click Approve tree.

While Babbit writes the first spec commit, the screen names the repository and counts the seconds. It opens a pull request with the spec and merges it. Then Build opens on your project, with a message linking the merged pull request and its commit.

The spec isn't committed until you approve. Approve tree opens the spec pull request and merges it, so review the doubts and the left-out list first. After that, every correction is a change you review.

Start from a sentence

If you don't have code yet, Babbit can start a project from one sentence.

  1. Click New project, then Describe a new app.
  2. Write one sentence about what you're building, and give the project a Name.
  3. Click Create project.

Babbit creates a repository with that name in your organization, puts an empty spec on its newdev/spec branch, and opens the first change with your sentence. From there it's an ordinary change: review the proposed lines and approve them. The repository must belong to an organization; Babbit refuses a personal account.

Refresh a project from its latest code

When a saved draft is out of date, an owner can read it again:

  1. Open the project's draft.
  2. Click Read latest code.

Babbit starts a new reading at the current heads of your repositories. Earlier recordings are kept, and the committed spec stays unchanged until you approve the new tree.

Replay a reading

Babbit records every reading as it happens, even with your browser closed. To replay one, for a demo or to see what the agent did:

  1. Open Recordings from the live reading or from Project settings.
  2. Choose a run.
  3. Use the controls to play, pause, seek, change speed or shorten quiet gaps.

A replay uses the recorded data, not a screen recording. It can't approve a tree. Download saves the original recording as JSON.

Delete a project

Only an owner of the project's organization can delete a project.

  1. Open Project settings.
  2. At the end of the page, type the project's name to turn on Delete project.
  3. Click Delete project.

Babbit refuses while a change, release or reading is in flight. Deleting ends the project's workspaces and removes its data from Babbit. Your repositories stay on GitHub. Usage records and the audit log keep their rows.