Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/content/workspaces/ai-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att

- **Use a workspace only for the runner.** The runner rewrites `~/.gitconfig` and `~/.config/git` before every session. It can't be turned on together with remote control.
- **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them (see [Who can use the runner](#who-can-use-the-runner)).
- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone (`git stash list`). Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them.
- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-<n>`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone. The runner clears the stash list between sessions, so each rescue also gets a ref: list them with `git for-each-ref refs/runner-rescue` and restore one with `git stash apply <ref>`. Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them.
- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise your Coder key. Add your fork as an SSH remote, such as `git@github.com:<you>/<repo>`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. The runner adds GitHub's host keys to `~/.ssh/known_hosts`. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github).

### Who acts on GitHub
Expand Down
6 changes: 4 additions & 2 deletions freeform/modules/claude-self-hosted-runner/files/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,10 @@ directory. The workspace rewrites this README on every start.
`/tmp/claude-runner-<n>.log`.
- Live sessions, their checkouts and unpushed commits: `claude-sessions`.
- Checkouts: `~/workspace/runner-<n>/<owner>/<repo>`.
- Work a session left uncommitted: `git stash list | grep runner-rescue` in
the checkout. Extra clones with unpushed commits are moved to
- Work a session left uncommitted: `git for-each-ref refs/runner-rescue` in
the checkout, and `git stash apply <ref>` to restore one. The runner
clears the stash list between sessions, so `git stash list` doesn't show
them. Extra clones with unpushed commits are moved to
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
Both are kept for 30 days.

Expand Down
10 changes: 6 additions & 4 deletions freeform/modules/claude-self-hosted-runner/files/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ since another session can start at any time.
branches or git state under another runner's directory.
- A runner keeps its checkouts from one session to the next. After every
session, `claude-runner-sweep` cleans them: it stashes uncommitted changes
as `runner-rescue` stashes, removes worktrees, and moves other clones to
`~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean"
below.
and keeps each stash under `refs/runner-rescue/` (list them with
`git for-each-ref refs/runner-rescue`), removes worktrees, and moves other
clones to `~/.local/state/claude-runner-rescue/`. See "Leave the checkout
clean" below.
- Work in the checkout the runner gave you. Do not make a new clone, and
never make a worktree or clone to get around files an earlier session
left behind. If a task needs a second checkout, ask the user first.
Expand All @@ -44,7 +45,8 @@ change what it generates, such as DDEV's image tags.

- If the hook reports leftovers, they are not yours. Save them, then carry
on in the same checkout:
`git stash push --include-untracked -m "leftovers from an earlier session"`.
`git stash push --include-untracked -m "leftovers from an earlier session" && git update-ref "refs/runner-rescue/$(date -u +%Y%m%d-%H%M%S)-leftovers" refs/stash`.
The ref keeps the stash after the runner clears the stash list.
Do not commit, delete or restore them.
- The runner can end your session without warning once the user has sent
nothing for 30 minutes. Before you finish a turn and wait for the user,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null)
if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then
echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:"
grep -F -- "$sid" "$rescue_root/log" | tail -10
echo "Stashes are in the checkout named there (find them with: git -C <checkout> stash list | grep runner-rescue). Before restoring one, tell the user what it holds."
echo "Stashes are in the checkout named there (find them with: git -C <checkout> for-each-ref refs/runner-rescue, and restore one with git stash apply <ref>). Before restoring one, tell the user what it holds."
fi
status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0
[ -n "$status" ] || exit 0
count=$(printf '%s\n' "$status" | wc -l)
echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)."
echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\". Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill."
echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\" && git update-ref refs/runner-rescue/\$(date -u +%Y%m%d-%H%M%S)-leftovers refs/stash. Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill."
printf '%s\n' "$status" | head -20
[ "$count" -le 20 ] || echo "... and $((count - 20)) more"
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,17 @@
# Runs as the runner's post-session hook and before every runner start, so
# never while a session uses the directory (each runner has --capacity 1).
# Nothing a session left is deleted unless a commit or remote already holds it:
# - Leftover changes in the runner's clones go into a "runner-rescue" stash.
# - Leftover changes in the runner's clones go into a "runner-rescue" stash,
# kept by a ref under refs/runner-rescue/. The runner clears the stash
# reflog between sessions, so `git stash list` no longer shows the stash;
# list rescues with `git for-each-ref refs/runner-rescue`.
# - Worktrees are removed, after stashing their changes the same way.
# - Other clones, and broken worktrees, are deleted if they hold nothing
# unpushed, and otherwise moved to the rescue directory,
# ~/.local/state/claude-runner-rescue/<runner>/<time>/.
# Every action is logged in the rescue directory's "log". Rescue stashes and
# Every action is logged in the rescue directory's "log". Rescue refs and
# directories older than CLAUDE_RUNNER_RESCUE_DAYS (default 30) are removed.
# Portable to macOS: bash 3.2 and BSD date, find and sed.
set -u
runner_dir="${1:?usage: claude-runner-sweep <runner dir>}"
runner_dir="${runner_dir%/}"
Expand All @@ -28,7 +32,7 @@ export GIT_AUTHOR_NAME="${GIT_AUTHOR_NAME:-Claude runner}" GIT_AUTHOR_EMAIL="${G
export GIT_COMMITTER_NAME="${GIT_COMMITTER_NAME:-Claude runner}" GIT_COMMITTER_EMAIL="${GIT_COMMITTER_EMAIL:-noreply@anthropic.com}"

note() {
printf '%s %s %s %s %s\n' "$(date -Is)" "$runner" "$session" "${uuid:--}" "$*" >>"$rescue_root/log"
printf '%s %s %s %s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$runner" "$session" "${uuid:--}" "$*" >>"$rescue_root/log"
echo "claude-runner-sweep: $*"
}

Expand All @@ -54,7 +58,17 @@ rescue_stash() {
return 1
fi
fi
note "stashed changes in $dir as \"$msg\""
# The stash reflog doesn't survive to the next session; a ref does.
local ref slug
slug=$(printf '%s' "$session-$what" | tr -c 'A-Za-z0-9._-' '-')
ref="refs/runner-rescue/$stamp-$slug"
local n=1
while git -C "$dir" show-ref -q --verify "$ref"; do
n=$((n + 1))
ref="refs/runner-rescue/$stamp-$slug-$n"
done
git -C "$dir" update-ref "$ref" refs/stash 2>/dev/null || ref="refs/stash"
note "stashed changes in $dir as \"$msg\" ($ref)"
}

# True when deleting this checkout loses nothing: no changes, no stashes and
Expand Down Expand Up @@ -90,10 +104,20 @@ for dir in "$runner_dir"/*/*/; do
done

# Runner clones first, so their worktrees are gone before the second pass.
for dir in "${candidates[@]}"; do
for dir in ${candidates[@]+"${candidates[@]}"}; do
is_runner_clone "$dir" || continue
# Older sweeps kept rescues only as stashes. When refs/stash is one that no
# rescue ref holds, give it a ref before another stash replaces it.
old=$(git -C "$dir" rev-parse -q --verify refs/stash 2>/dev/null)
if [ -n "$old" ] && git -C "$dir" log -1 --format=%s "$old" 2>/dev/null | grep -q runner-rescue &&
! git -C "$dir" for-each-ref --format='%(objectname)' refs/runner-rescue/ 2>/dev/null | grep -qx "$old"; then
ref="refs/runner-rescue/$(git -C "$dir" log -1 --format=%ct "$old")-earlier-sweep"
git -C "$dir" update-ref "$ref" "$old" && note "kept the earlier rescue stash in $dir as $ref"
fi
# git prints worktree paths with symlinks resolved, as with macOS /var.
real=$(cd "$dir" && pwd -P)
while read -r wt; do
[ "$wt" = "$dir" ] && continue
[ "$wt" = "$dir" ] || [ "$wt" = "$real" ] && continue
if [ -d "$wt" ]; then
rescue_stash "$wt" "worktree $(basename "$wt")" || continue
if git -C "$dir" worktree remove --force "$wt" 2>/dev/null; then
Expand All @@ -103,17 +127,14 @@ for dir in "${candidates[@]}"; do
done < <(git -C "$dir" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
git -C "$dir" worktree prune 2>/dev/null
rescue_stash "$dir" "checkout"
# Drop expired rescue stashes, highest index (oldest) first, so the lower
# indexes stay valid.
cutoff=$(($(date +%s) - keep_days * 86400))
git -C "$dir" stash list --format='%gd %ct %gs' 2>/dev/null | sort -t'{' -k2 -rn |
while read -r ref ct subject; do
case "$subject" in *runner-rescue*) ;; *) continue ;; esac
[ "$ct" -lt "$cutoff" ] && git -C "$dir" stash drop --quiet "$ref" 2>/dev/null
git -C "$dir" for-each-ref --format='%(refname) %(committerdate:unix)' refs/runner-rescue/ 2>/dev/null |
while read -r ref ct; do
[ "$ct" -lt "$cutoff" ] && git -C "$dir" update-ref -d "$ref" 2>/dev/null
done
done

for dir in "${candidates[@]}"; do
for dir in ${candidates[@]+"${candidates[@]}"}; do
[ -e "$dir" ] || continue
is_runner_clone "$dir" && continue
if disposable "$dir"; then
Expand Down
6 changes: 4 additions & 2 deletions modules/claude-self-hosted-runner/files/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,10 @@ directory. The workspace rewrites this README on every start.
`/tmp/claude-runner-<n>.log`.
- Live sessions, their checkouts and unpushed commits: `claude-sessions`.
- Checkouts: `~/workspace/runner-<n>/<owner>/<repo>`.
- Work a session left uncommitted: `git stash list | grep runner-rescue` in
the checkout. Extra clones with unpushed commits are moved to
- Work a session left uncommitted: `git for-each-ref refs/runner-rescue` in
the checkout, and `git stash apply <ref>` to restore one. The runner
clears the stash list between sessions, so `git stash list` doesn't show
them. Extra clones with unpushed commits are moved to
`~/.local/state/claude-runner-rescue/`, and its `log` lists every change.
Both are kept for 30 days.

Expand Down
10 changes: 6 additions & 4 deletions modules/claude-self-hosted-runner/files/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ since another session can start at any time.
branches or git state under another runner's directory.
- A runner keeps its checkouts from one session to the next. After every
session, `claude-runner-sweep` cleans them: it stashes uncommitted changes
as `runner-rescue` stashes, removes worktrees, and moves other clones to
`~/.local/state/claude-runner-rescue/`. See "Leave the checkout clean"
below.
and keeps each stash under `refs/runner-rescue/` (list them with
`git for-each-ref refs/runner-rescue`), removes worktrees, and moves other
clones to `~/.local/state/claude-runner-rescue/`. See "Leave the checkout
clean" below.
- Work in the checkout the runner gave you. Do not make a new clone, and
never make a worktree or clone to get around files an earlier session
left behind. If a task needs a second checkout, ask the user first.
Expand All @@ -44,7 +45,8 @@ change what it generates, such as DDEV's image tags.

- If the hook reports leftovers, they are not yours. Save them, then carry
on in the same checkout:
`git stash push --include-untracked -m "leftovers from an earlier session"`.
`git stash push --include-untracked -m "leftovers from an earlier session" && git update-ref "refs/runner-rescue/$(date -u +%Y%m%d-%H%M%S)-leftovers" refs/stash`.
The ref keeps the stash after the runner clears the stash list.
Do not commit, delete or restore them.
- The runner can end your session without warning once the user has sent
nothing for 30 minutes. Before you finish a turn and wait for the user,
Expand Down
4 changes: 2 additions & 2 deletions modules/claude-self-hosted-runner/files/claude-checkout-check
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ sid=$(jq -r '.session_id // empty' <<<"$input" 2>/dev/null)
if [ -n "$sid" ] && [ -f "$rescue_root/log" ] && grep -qF -- "$sid" "$rescue_root/log"; then
echo "This session was released earlier, and the runner saved what it had left uncommitted. Entries in $rescue_root/log:"
grep -F -- "$sid" "$rescue_root/log" | tail -10
echo "Stashes are in the checkout named there (find them with: git -C <checkout> stash list | grep runner-rescue). Before restoring one, tell the user what it holds."
echo "Stashes are in the checkout named there (find them with: git -C <checkout> for-each-ref refs/runner-rescue, and restore one with git stash apply <ref>). Before restoring one, tell the user what it holds."
fi
status=$(git -C "$dir" status --porcelain 2>/dev/null) || exit 0
[ -n "$status" ] || exit 0
count=$(printf '%s\n' "$status" | wc -l)
echo "The checkout $dir is not clean at the start of this session: an earlier session left $count changed or untracked path(s)."
echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\". Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill."
echo "They are not part of your task. Save them with: git stash push --include-untracked -m \"leftovers from an earlier session\" && git update-ref refs/runner-rescue/\$(date -u +%Y%m%d-%H%M%S)-leftovers refs/stash. Then continue in this checkout; do not make a worktree or a new clone to avoid them. See \"Leave the checkout clean\" in the coder-shared-workspace skill."
printf '%s\n' "$status" | head -20
[ "$count" -le 20 ] || echo "... and $((count - 20)) more"
Loading
Loading