Skip to main content

​
outerlayer init

Connect a repository to a factory, install the capture hooks, set up Claude Code with skills and an MCP server, and run doctor.
A full init installs the starter skills already, so --template matters with --local, where it is the only way to get them. It cannot be combined with --remove or --org. init asks nothing and never signs in. It runs four steps in order:
  1. Connect. Runs outerlayer connect. With no saved credential, or no git remote, this step is skipped. init then says to run outerlayer login and outerlayer init again.
  2. Hooks. Installs the capture hooks into Claude Code, the only agent with a session-start hook.
  3. Agent setup. Installs the starter skills and the outerlayer skill into .outerlayer/skills/. Writes .outerlayer/config.json for Claude Code when there is none. Runs outerlayer context emit so the skills appear in .claude/skills/. Adds the OuterLayer MCP server. A hand-written file the emit would replace, such as a root CLAUDE.md, is kept and listed. Files are left uncommitted. Skipped outside a git repository and when the repository’s context comes from a control plane. See Agent context.
  4. Check. Runs doctor and prints its summary.
Where the agent setup step puts the MCP server entry, which runs outerlayer mcp serve:
  • With no .outerlayer/mcp.json, the outerlayer entry goes into .mcp.json, beside any servers already there.
  • With .outerlayer/mcp.json, the entry goes into that file instead, because outerlayer context emit copies it over .mcp.json.
  • If .mcp.json then holds servers that .outerlayer/mcp.json lacks, .mcp.json is kept and has no outerlayer entry. init says so. Add the entry to .mcp.json by hand, or move your servers into .outerlayer/mcp.json and run outerlayer context emit.
  • An outerlayer entry already in the file is left as it is.
What the hooks step writes:
  • SessionStart, SessionEnd and Stop hooks. The settings file is backed up first.
  • Wrappers around existing PreToolUse and PostToolUse hooks, so a hang or a kill leaves evidence. Undo with outerlayer hooks unwrap.
  • A status-line segment. An existing statusLine command is wrapped, not replaced: its output prints first.
  • A pre-commit guard that refuses a commit of context materialized from a control plane. A hook file OuterLayer did not write, such as husky’s, is never touched.
It writes nothing when the CLI binary the hooks would point at does not exist. It never starts a background process. When every step passed and the repository is linked, init ends with “Add an issue on the Work page and press Build.” If agent setup wrote files or found its own already in place, init also prints a line to commit and push .outerlayer/, before the “Add an issue” line. It prints that line even when the connect or doctor step failed, or the repository is not linked yet. The factory reads the policy from the default branch, so no check runs on pull requests until it is there. If the repository still has to be linked, init prints the link to follow, then the commit line, and the “Add an issue” line waits.
Exit codes: 0 when every step was done or skipped, including a second run that changes nothing. 1 when a step failed, a doctor check failed, or a flag was refused. A failed step does not stop later ones, but doctor is skipped when the hooks could not be installed. See also: Quickstart, Agent context.

​
outerlayer doctor

Check the installation. Every failing check names its fix.
Checks, in order: Claude Code home, Transcripts, Hooks installed, Hooks firing, Wrapped hooks, Git hooks directory, Spool writable, Cloud sync, Daemon running, Retention (cleanupPeriodDays), Disk headroom, Claude Code version, Settings JSON valid, Status line, Claude Code installs, Context source. Three appear only when they apply: Context source degradation, Context exclude block, and Installed CLI, which needs a copy at ~/.outerlayer/cli. On a runner host, the checks change. A runner host is a machine whose ~/.outerlayer/config.json has a runner block. Its checks for the Claude Code home, transcripts, hooks, spool, daemon and status line become one skipped Laptop checks line. Doctor then adds the runner’s own checks. See Host checks. Three more checks read the gateway. They change nothing.
  • Login or Factory key, named for the credential a command would send. A factory key from OUTERLAYER_API_KEY or the config file always wins over a login. Fails when the gateway refuses the credential: run outerlayer login for a login, or get a fresh key for a factory key. Warns when the gateway does not answer.
  • Factory fails when the credential cannot read its factory. For a login, that is the factory outerlayer connect chose for the repository; the fix is outerlayer connect. For a factory key, it is the factory the key is bound to.
  • Repository warns when this repository is not linked to that factory. Fix it in the factory’s setup panel, or run outerlayer connect --factory <org>/<factory> when another factory of yours has it linked.
What each credential needs for these checks to pass:
  • A login needs a factory chosen for the repository with outerlayer connect.
  • A factory key needs the factory it is bound to to be readable, and git.read to read its linked repositories.
  • With no login and no factory key, all three are skipped and doctor makes no network call.
  • Outside a git repository, a login with no OUTERLAYER_APP_ID skips Factory and Repository.
Doctor adds a GitHub App: owner/name check per connected repository. The GitHub App check runs only when the credential check passes. It warns when the installation has not accepted a permission builds need, naming each one and the installation’s settings page. It warns when the default branch does not require a pull request; see Protect the default branch. On a fresh machine right after init, these warn, and that is expected:
Exit codes: 0 when no check fails (warnings allowed), 1 when any check fails. See also: Troubleshooting.

​
outerlayer daemon

Run the copy-out daemon in the foreground. Claude Code deletes transcripts after about 30 days. The daemon copies them first.
It keeps the status-line state fresh. With cloud credentials, it also streams the new turns of a session launched with OUTERLAYER_WORK, so its page follows along before sync runs. init does not start it: run it in a terminal you keep open, or under a login agent. outerlayer watch is the former name and still works, with a warning.
See also: What leaves your machine.

​
outerlayer hooks status

List hook entries in user and project settings, marking the wrapped ones.
A settings file that is not valid JSON is reported, and the other is still listed. Exits 0.

​
outerlayer hooks wrap

Wrap hook commands so a hang or a kill leaves evidence. init already wraps PreToolUse and PostToolUse hooks. Run this for other events, for hooks added later, or after init --no-wrap-hooks.
Each wrapped hook adds one Node start and one spawn every time it fires. Like init, hooks wrap first copies the CLI to ~/.outerlayer/cli, and the wrappers run that copy.
Exit codes: 0 when it wrapped hooks or found none to wrap. 1 when --no-input comes without --all, the CLI cannot be copied to ~/.outerlayer/cli, the settings file is not valid JSON, or the CLI path the wrapper would use does not exist (reinstall, then rerun).

​
outerlayer hooks unwrap

Restore wrapped hooks to their original commands. Use it too if a wrapper misbehaves.
Exit codes: 0, or 1 when the settings file is not valid JSON.

​
outerlayer hooks install-git

Install the commit guard that refuses a commit of materialized context. init runs the same install.
Exit codes: 0 when the guard is installed, current, or already added by hand. 1 outside a git repository. 1 when a pre-commit hook OuterLayer did not write exists, or the repository sets core.hooksPath: nothing is written. Add the output of --print to your hook manager, before any early exit in the existing hook. See also: Share instructions across repositories.