Skip to main content
A session uploads only when you start it with OUTERLAYER_WORK set to its work item’s number. Every other session stays on 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 to see the launch command. Build instead asks a host to build it.
  • From a terminal, inside the repository’s checkout:
    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

An item added with Build locally, with Run it yourself open.

​
Start a session on the item

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 host or other session holds the item, your session also takes a claim on it. The claim stops a host from starting the item while you work. It is released when the session ends.

​
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. 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:
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.

​
Supported agents

Upload needs a session-start hook to record the launch, and only Claude Code has one.

​
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:
The launch is recorded against the same session, and the whole transcript uploads, including the turns from before you resumed.