> ## Documentation Index > Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Work on an item locally > Start a coding agent session on a work item, declare its pull request, and end its claim so review can open. To work on an item on your own machine, start a coding agent session on it. A session uploads only when you start it with `OUTERLAYER_WORK` set to its [work item](/concepts#where-work-lives)'s number. Every other session stays on your machine. [What leaves your machine](/what-leaves-your-machine) covers the rest. ## Create the work item first Launching never creates an item, so add the issue to the Work page first. Either way gives you the item's number: * **From the Work page.** Choose **Add work**, then **Build locally** beside the issue. The item's page opens. On its **Activity** tab, expand **Run it yourself**. It shows `OUTERLAYER_WORK=7 claude "/build"`, with the item's own number, ready to copy. **Build** instead queues it for a runner. * **From a terminal**, inside the repository's checkout: ```bash theme={"system"} npx @outerlayer/cli work build --issue 42 --local ``` It prints the item's number and the line that starts your session, such as `OUTERLAYER_WORK=7 claude`. The Activity tab of an item added with Build locally, with Run it yourself expanded to show OUTERLAYER_WORK=7 claude "/build" ## Start a session on the item ```bash theme={"system"} OUTERLAYER_WORK=7 claude "/build" ``` `7` is the work item's number, not the issue number. `/build` is the starter skill `outerlayer init` installs. It builds the issue into a pull request with its evidence. Leave it off to start an empty session and give your own instructions. The session appears on item 7's page and uploads whole, from its first turn to its end. If no runner or other session holds the item, your session also takes a [claim](/concepts#who-does-the-work) on it. The claim stops a runner from starting the item while you work. It is released when the session ends, or when you [end it yourself](#end-the-sessions-claim). ## Values `OUTERLAYER_WORK` accepts The value must be a bare positive integer. It names an item on the factory this repository is connected to, or the factory of a piped key. | Value | What happens | | - | - | | `7` | Links the session to item 7. | | `#42`, `github:owner/repo#42`, `linear:ENG-142` | Refused on your machine. These name an issue, not an item. The session stays on your machine. The message names `outerlayer work build --local`, which creates the item. | | A number no item has | The gateway refuses the link. Nothing is created. The session still uploads, attached to no item. | | The number of a withdrawn item | The gateway refuses the link. The message carries the withdrawal date. The session still uploads, attached to no item. | Every refusal reason is appended to `~/.outerlayer/spool/hook-errors.log`, and the next session start tells you so. A refused link still uploads because the hook records the launch on your machine before the gateway answers. Only a value that is not a bare integer keeps the session local. ## Check that a session was launched Run a dry run before uploading: ```bash theme={"system"} outerlayer sync --dry-run ``` A launched session appears as a row. If the summary line reads `N transcript(s) — not launched with OUTERLAYER_WORK`, those sessions were started without the variable and never upload. ## If you forgot the variable The variable is read only when the agent starts. Exporting it inside a running session does nothing. `outerlayer work link-session` shows the session on the Work page, but its transcript still cannot upload. End the session and resume it with the variable set: ```bash theme={"system"} OUTERLAYER_WORK=7 claude --resume ``` The launch is recorded against the same session, and the whole transcript uploads, including the turns from before you resumed. ## Open and declare the pull request A pull request joins a work item when a session on that item opens or declares it. The `/build` skill does both for you. A pull request the agent opened in the session is usually linked when the session syncs. Declare it yourself when it was not, or when you opened it outside the session. To open the pull request and declare it in one step, run this inside the session: ```bash theme={"system"} outerlayer work open-pr --title "Add the settings toggle" --body-file pr.md ``` It runs `gh` under your login, then declares the result. If a pull request is already open on the branch, it edits that one instead. Run it again after you change the title or description. In a runner's build, the gateway opens the pull request as the factory's GitHub App instead. See [`work open-pr`](/reference/cli-work#outerlayer-work-open-pr). To declare a pull request that is already open, run this inside the session, from the checkout where it was opened: ```bash theme={"system"} outerlayer work pr 418 ``` * To name a different repository, add `--repo `. Outside a checkout with a git remote, the command refuses with `no repository` unless you pass `--repo`. * To declare from another shell, where the CLI cannot detect the session, add `--session-id `. For Claude Code, it is the id `claude --resume` takes. The command sends only the session id, the repository, the pull request number and the `OUTERLAYER_WORK` item number. It declares onto that item or refuses. Declaring the same pull request twice does nothing. Each refusal and what to do about it, and how to withdraw a declaration made onto the wrong item, are in [`outerlayer work pr`](/reference/cli-work#outerlayer-work-pr). ## End the session's claim While your session holds the item's claim, the item reads **With agent**, and its **Review** button stays disabled. Review opens when the claim ends. The claim ends when the session ends, or when you release it: ```bash theme={"system"} outerlayer work release --item 7 ``` Run inside the session, it releases that session's own claim and no one else's. The session stays open. A later tool call in the same session takes the claim again. The `/build` skill runs this command as its last step, after the pull request is open and the evidence is emitted. See [`outerlayer work release`](/reference/cli-work#outerlayer-work-claim-renew-release). ## Supported agents | Agent | Captured from | Uploads as work | | - | - | - | | Claude Code | `~/.claude/projects` | Yes. Turns, tool input and output, thinking, images, subagents, cost. | | Codex CLI | `~/.codex/sessions` | No. Captured on your machine only. | | Cursor | `~/.cursor/chats` | No. Captured on your machine only. Needs Node 22.5 or later. | Upload needs a session-start hook to record the launch, and only Claude Code has one. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.