> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture commands

> init, doctor, daemon and hooks: installing the capture hooks and keeping them healthy.

## 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`.

```bash theme={"system"}
outerlayer init [--local] [--factory <org>/<factory>] [--user | --project] [--org] [--remove]
                [--gitignore] [--template default] [--no-wrap-hooks] [--no-statusline] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--local` | off | Install the hooks only: no connect step, no agent setup, no network call. |
| `--factory <org>/<factory>` | none | Passed to [`connect`](/reference/cli-cloud#outerlayer-connect): the factory to connect this repository to. |
| `--user` | on | Write the hooks to `~/.claude/settings.json`. |
| `--project` | off | Write the hooks to `./.claude/settings.json` instead. |
| `--org` | off | Print a `managed-settings.json` snippet for MDM or GPO rollout. Writes nothing. |
| `--remove` | off | Remove the hooks, and restore wrapped hooks and the original status line. |
| `--gitignore` | off | Also add `.outerlayer/` to `.gitignore`. Project scope only. |
| `--template default` | none | Install the starter skills and a policy file into `.outerlayer/`. `default` is the only template. |
| `--no-wrap-hooks` | wrap | Leave existing `PreToolUse` and `PostToolUse` hooks unwrapped. |
| `--statusline` / `--no-statusline` | `--statusline` | Install the status-line segment, or leave the `statusLine` slot untouched. |
| `--json` | off | Print one document with the outcome of the `connect`, `hooks`, `agent-setup` and `doctor` steps: `done`, `skipped` or `failed`, with a reason. `agent-setup` lists every path it wrote, and under `kept`, each hand-written file it did not replace. It never holds a credential. With `--local` or `--remove`, it prints the hooks result alone. |

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`](/reference/cli-cloud#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`](/reference/cli-context#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](/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.

```bash theme={"system"}
outerlayer init
outerlayer init --local --template default
```

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](/quickstart), [Agent context](/agent-context).

## outerlayer doctor

Check the installation. Every failing check names its fix.

```bash theme={"system"}
outerlayer doctor [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--json` | off | Print the checks and a summary as one JSON document. |

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](/reference/cli-runner#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](/github-app-and-build-tokens#protect-the-default-branch).

On a fresh machine right after `init`, these warn, and that is expected:

| Check | Clears when |
| - | - |
| Hooks firing | An agent session has run. |
| Transcripts | An agent session has run. |
| Spool writable | The first hook has fired. |
| Cloud sync | `login` has saved credentials. |
| Daemon running | `outerlayer daemon` is running. |

```bash theme={"system"}
outerlayer doctor
```

Exit codes: 0 when no check fails (warnings allowed), 1 when any check fails.

See also: [Troubleshooting](/troubleshooting).

## outerlayer daemon

Run the copy-out daemon in the foreground. Claude Code deletes transcripts after about 30 days. The daemon copies them first.

```bash theme={"system"}
outerlayer daemon [--once]
```

| Flag | Default | What it does |
| - | - | - |
| `--once` | off | Do one mirror sweep and exit. Makes no network calls. |

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.

```bash theme={"system"}
outerlayer daemon
```

See also: [What leaves your machine](/what-leaves-your-machine).

## outerlayer hooks status

List hook entries in user and project settings, marking the wrapped ones.

```bash theme={"system"}
outerlayer hooks status [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--json` | off | Print each settings file with its entries and a `wrapped` flag. |

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`.

```bash theme={"system"}
outerlayer hooks wrap [--project] [--event <name>] [--all] [--no-input] [--capture-output]
```

| Flag | Default | What it does |
| - | - | - |
| `--project` | user settings | Work on `./.claude/settings.json`. |
| `--event <name>` | every event | Only consider hooks registered for this event. |
| `--all` | ask per hook | Wrap every candidate without asking. |
| `--no-input` | off | Never ask. Requires `--all`. |
| `--capture-output` | off | Also keep a bounded tail of stdout and stderr. Adds overhead. |

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.

```bash theme={"system"}
outerlayer hooks wrap --all --event PreToolUse
```

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.

```bash theme={"system"}
outerlayer hooks unwrap [--project]
```

| Flag | Default | What it does |
| - | - | - |
| `--project` | user settings | Work on `./.claude/settings.json`. |

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.

```bash theme={"system"}
outerlayer hooks install-git [--print]
```

| Flag | Default | What it does |
| - | - | - |
| `--print` | off | Print the hook scripts instead of installing them. |

```bash theme={"system"}
outerlayer hooks install-git --print
```

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](/share-instructions-across-repositories).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.