From your invite to your first issue built into a pull request by a Claude Code session on your machine.
By the end of this page, one of your GitHub issues is built into a pull request by a Claude Code session on your machine. The dashboard shows the pull request, the session that wrote it, and the checks it passed.
Claude Code on your machine. OuterLayer records Claude Code sessions.
Node.js 22 or later, to run the OuterLayer CLI. Your repository does not need to use Node.
A GitHub repository with at least one open issue. You need to be allowed to install a GitHub App on it; Connect a repository says who can. The examples use issue 42.
Acceptance criteria in that issue, if you have them./build reads the issue’s criteria in any form you write them, such as a heading with a list, a checklist or a “done when” sentence, and records them as written. When the issue has none, the build drafts criteria from the issue’s description and records them. The item’s Criteria tab says they were drafted. You can replace them with your own list with outerlayer emit criteria. To write the criteria yourself first, add a criteria section to the issue, or write the issue with /spec, which init installs.
You do not need a host. A host is a machine where a runner builds issues unattended, and you can add one after your first build.This page installs the CLI once, with npm install -g @outerlayer/cli, and then runs it as outerlayer. The outerlayer MCP server that init adds for Claude Code runs npx -y @outerlayer/cli mcp serve, so it works without the install. A host needs the same install.
OuterLayer is invite-only for now. You’ll get an email invite from the OuterLayer team. If you don’t have one, join the waitlist from the login page.Because you were invited, your organization and a factory named Default already exist, so there is nothing to create. Key concepts says what a factory is.
Open the link in the invite email. It signs you in and opens a page where you set a password.
Instead of a password, choose Continue with GitHub or Continue with Google. Either one links to the account you were invited to.
You land on the Default factory’s Work page.
Rename the organization under Organization settings → General, from the account menu at the bottom left. Rename the factory under its Settings → General, in the Name section. The gear on its card in the Factories list opens that page.Your factory’s Work page opens on a setup panel, Build your first issue, with the same four steps as this page. Its Read the quickstart link opens this page.
1
Connect a repository
Where pull requests open, and where checks are read from. The panel shows this step’s two parts up front:
Install the OuterLayer GitHub App. Choose Connect GitHub repository. Grant only the repositories this factory should see. On a GitHub organization, only an owner can install it; other members can request it from an owner.
Link the repository. Back here, pick the repository and the branch your pull requests target. Policy and checks are read from that branch. Choose Link repository to pick them.
The panel on a new factory, with the first step active.
The step then shows Repository linked, with the repository and branch.The App reads issues, pull requests and CI results. It posts comments and checks on GitHub only when you turn them on in the factory’s settings. A runner build also uses the App to push its branch and open its pull request.
2
Install OuterLayer in your repository
Needs Node 22. Run these in your repository’s checkout. Approve the sign-in link when it opens.
/build and the other skills run the outerlayer command, so install it once per machine.The panel fills in <org>/<factory> for you. It is your organization’s and factory’s names from the dashboard’s address.login signs this machine in to your account. It prints a link and opens it in your browser; approve it there. You do this once per machine.init sets up the repository. On a terminal it asks one question, whether plain claude should start through outerlayer claude, and writes nothing to your shell until you say yes. It:
connects the repository to your factory
installs the hooks that record your Claude Code sessions
adds the starter skills, including /build, and two MCP servers for Claude Code
runs doctor, a health check that may warn on a fresh machine (which warnings)
It changes nothing you wrote by hand. The files it adds stay uncommitted until step 3.Or let your agent do it. Choose Copy a prompt for your agent instead, open Claude Code in your checkout, and paste it. This is the prompt. Claude runs the same commands and hands you each link to approve.
Set up OuterLayer in this repository.OuterLayer is an open-source software factory: an issue goes in, and a reviewedand verified pull request comes out, built by the coding agents this team alreadyruns, in this repository. Setup signs this machine in to my OuterLayer account,connects this repository to my team's factory, and installs the hooks and skillsthat let you build issues for it.1. Run `npm install -g @outerlayer/cli`, so the `outerlayer` command is on the PATH. The skills that setup installs run that command.2. Run `outerlayer login`. It prints a link and a code. When it does, give it to me and wait; I approve it in my browser. Then run its check as `outerlayer login --check <id>`, with the id it printed, until it stops exiting 75.3. Then run `outerlayer init --factory <org>/<factory>`. It connects the repository, installs the hooks and skills, and runs a health check. If it prints a link to link the repository, give it to me, wait for me to say done, then run `outerlayer connect --factory <org>/<factory>`.4. When `init` ends, tell me what it says to do next, including any line about committing and pushing `.outerlayer/`, and what `doctor` reported. Then stop. I add work from the Work page, not from here.Never print anything these commands call a token or a key.
If init prints a link.init connects the repository by running connect. With --factory, it uses the factory you name; without it, connect picks a factory by itself when only one fits. If the repository is not linked to the factory yet, connect prints the link to the factory’s Work page and exits 2. Finish step 1 there, then run connect again: outerlayer connect --factory <org>/<factory>.Nobody there to approve the link?login works on a machine with only a terminal: open its link on any other device. For a machine where nobody can approve a link, such as CI, choose No browser on that machine? under the commands. It makes a factory key, shown once, and shows commands with the key filled in to paste. Those commands run init --local, which installs the session hooks only. They do not connect the repository or add the starter skills.The step shows OuterLayer installed once step 3 is done.Every flag and exit code is in Capture commands and Cloud commands.
3
Commit and merge the setup
Merge the files init wrote into your base branch. Checks run only once they’re there. The panel names your base branch and shows these commands:
git push pushes the branch you are on. If that is not your base branch, open a pull request from it and merge it.init lists every path it wrote (which files):
AGENTS.md: your agent instructions.
.agents/skills/: the skills.
.claude/skills: a link to .agents/skills for Claude Code.
.outerlayer/: your policy and config, and two checks in .outerlayer/validators/ (code-review.yaml for the code review and acceptance-criteria.yaml for the criteria judge).
.mcp.json: the two MCP servers.
The session hooks are not among them. init writes the hooks to ~/.claude/settings.json, your own Claude Code settings, outside the repository. Each teammate runs init on their own machine to get them.Do this before you build anything. Until the setup is merged into your base branch, your pull requests get no checks. This step ticks itself once OuterLayer sees the files on your base branch. OuterLayer reads the branch each time it is pushed to, so the tick shows shortly after the merge, in every browser and for every teammate.
4
Add and build your first issue
Pick an issue, choose Build locally, then run the line under Run it yourself.
The setup panel with its first three steps done and Add and build your first issue active.
On the panel, choose Add your first issue. A dialog lists the repository’s open issues. Choose Build locally beside your issue.The issue is now a work item with a number of its own: issue 42 might become item 7. OuterLayer’s pages and commands use the item number, never the issue number. The item’s page opens, with that number in its heading.
In your checkout, switch to the base branch and pull, so the setup from step 3 is there.
On the item’s page, open the Activity tab and expand Run it yourself. Copy the line it shows. For item 7 it is:
OUTERLAYER_WORK=7 claude "/build"
Run it in your checkout. It starts Claude Code linked to item 7. /build reads the issue, writes the change, runs your repository’s checks, and opens the pull request.
Build, beside Build locally in the dialog, queues the item for a runner instead. Use it once you have one: see Set up your first host.The item’s Sessions list shows your session as it runs. Answer Claude’s permission prompts as they come.You are done when the item’s page shows the pull request and its evidence rows, one row per check, on its Checks tab. Open the session to read every turn, the tools it called and what it cost. Launch a session explains how a session is linked to an item.
Only sessions linked to a work item upload: sessions you start from Run it yourself, and a runner’s builds. Your other Claude Code sessions stay on your machine. Known credential formats, such as API keys, tokens and private keys, are replaced on your machine before anything leaves. A secret in an unusual format can get through. What leaves your machine has the full list.To see what would upload, run outerlayer sync --dry-run. It sends nothing.
Add each issue the same way, and review its pull request on the item’s page: approve it or send it back. See Review and merge.To have issues built without you, set up a host later, then choose Build in the add dialog. If no runner takes an item, see Troubleshoot builds.To take an item off the Work page: outerlayer work remove --item 7 --reason "opened by mistake".
