Your first hour

What to do after signing in, in order — connect GitHub, choose the repositories, create a workspace, connect your editor, run the first supervised session, and where to look while it runs.

Madebook installs above the editors and agents you already use. Nothing here replaces them; the hour below is spent telling Madebook where the code is and letting the editor report into it. Six steps, and the first three are done once per organization.

1. Connect the code host

Organization → Connections → Repositories. This connects who owns the code, not a repository. Pick one of the two options:

  • Option A · Connect a GitHub organization — press Install the App, choose the GitHub organization and the repositories the App may see on GitHub, press Install there. You are sent back here. This is the one for a company: nothing expires when somebody leaves, and pull requests, checks and approvals arrive on their own.
  • Option B · Connect a GitHub account with a personal access token — a person's account, for one person or a small team. Where do I get a token? opens GitHub with the right scopes ticked.

Both are described field by field in Connections. GitLab and Azure DevOps connect later, from the workspace.

2. Choose what the organization offers

Optional. Once GitHub is connected, Repositories offered to the organization appears under the options. Leave it on Everything the connections can see, or tick only the repositories engineers here should be able to pick, and Save.

3. Create a workspace

Organization → Workspaces → Start from a repository is the 60-second path: pick a repository and Madebook creates the workspace, indexes the code, reads the stack, the context and the decisions out of it, and builds review capsules for the last five merged pull requests. The workspace stays hidden until that finishes — about a minute — then opens itself.

The organization's Home also lists every workspace as a card, with a Create a workspace card at the end; see Home and Overview.

Then, inside the workspace, Repositories is where you pick which of the organization's repositories it reads — one picker, the source shown beside each.

New workspace is the walkthrough instead: name and mission, which policies and skills apply, then the repository. Use it when the mission paragraph matters from day one. Either way, tick Also create it in CodeBook or OpenBook if the same workspace should exist in the other products. See Creating a workspace.

If you skipped the organization's recommended setup, do Governance now: a provider, a model and your editor must be on the allow-list or nothing can run. See Governance overview.

4. Connect your editor

Organization → MCP tokens, or Connections → MCP tokens & editor.

  1. Create MCP token. Leave Who is this token for? on Me, scope it to the workspace if you only ever work in one, and Create token. Copy it — it is shown once, and it is already filled into the block below.
  2. Copy the MCP configuration and paste it where your editor reads it: .mcp.json at the repository root for Claude Code, the equivalent for Cursor, Codex, Copilot or VS Code. Set MADEBOOK_CLIENT to your editor's name.
  3. Restart the editor, or reload its MCP servers. It now has seven madebook_* tools.

Every engineer does this step for themselves; one token each is the point. Details in Connecting a coding agent.

5. Run the first supervised session

In the editor, ask the agent to start a Madebook session before it touches code. It calls madebook_session_start and gets the brief back — the policies, the architecture rules, the decisions already made, the skills, and what other sessions are touching right now. If the token reaches more than one workspace it lists them and asks which; it never guesses.

For work that has a contract to be held to, create a Mission in the workspace first (Workspace → Missions), approve its contract, and name it when the session opens. A session without a mission is fine for exploratory work. See Missions and Work sessions.

As the agent works it reports changes and evidence through the same tools. When it opens a pull request, Madebook mirrors it.

6. Where to look while it runs

  • Workspace → Attention — what needs a person, worst first. It is at the top of the workspace sidebar because the queue is the product. For the whole organization, Overview summarizes it and Attention lists it.
  • Workspace → Changes — every change an agent reported, sorted by risk, each with its review capsule.
  • Workspace → Work sessions — who is working, and what they were told.
  • Workspace → Repositories — switch Require supervision on a repository once you want every pull request judged, then make the madebook/supervised status required in branch protection. See The pull request check.
  • Workspace → Compliance — when you want the exact commit judged against the organization's rules, set the repository to monitor first, then enforce, and require madebook/compliance from the App. See The compliance check.

After the first hour

The setup wizard ends with a Next block that opens the governance journey: seven ordered steps from "set up" to "governed, with evidence for an auditor" — coverage, rules, compliance on, enforcement verified on the host, a pull request reviewed independently, a signed evidence package. Each is computed from what is actually stored, so it cannot be ticked, only done.

← PreviousSigning inNext →Organizations