diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 4339aa7..27aa09e 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -107,10 +107,9 @@ Claude runs in the `tmux` session named after the workspace, starting in your ho One-time setup: 1. On claude.ai, create a self-hosted environment and copy its environment secret. -2. In the workspace, save it: +2. In the workspace, save it in `~/.claude-runner`, which the workspace creates when the setting is on. The `README.md` there has these steps, and says where the runner keeps its logs, checkouts and rescued work. ```bash - mkdir -p ~/.claude-runner # paste the secret, press Enter, then Ctrl-D cat > ~/.claude-runner/environment-secret chmod 600 ~/.claude-runner/environment-secret @@ -122,5 +121,5 @@ 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. -- **Checkouts carry over between sessions.** A runner keeps its clones under `~/workspace/runner-`, so a new session can find what an earlier one left behind. A hook in `/etc/claude-code/managed-settings.d/coder-runner.json` lists those leftover changes at the start of the session, and the skill tells Claude how to clean them up safely. +- **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-`. 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. - **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 the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md new file mode 100644 index 0000000..7169646 --- /dev/null +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -0,0 +1,43 @@ +# Claude Code self-hosted runner + +The workspace's "Run a Claude Code self-hosted runner" setting created this +directory. The workspace rewrites this README on every start. + +## Start the runner + +1. On claude.ai, create a self-hosted environment and copy its environment + secret. +2. Save the secret here: + + ```bash + # paste the secret, press Enter, then Ctrl-D + cat > ~/.claude-runner/environment-secret + chmod 600 ~/.claude-runner/environment-secret + ``` + +3. Restart the workspace. The runner starts only when + `environment-secret` exists and is not empty. + +## What is here + +- `environment-secret`: the secret you saved. Keep it mode 600. +- `hooks/runner-/post-session`: the hook that cleans runner ``'s + checkouts after each session. The workspace creates it, so do not edit it. + +## Find things + +- Runners: `tmux attach -t claude-runner`, logs in + `/tmp/claude-runner-.log`. +- Live sessions, their checkouts and unpushed commits: `claude-sessions`. +- Checkouts: `~/workspace/runner-//`. +- Work a session left uncommitted: `git stash list | grep runner-rescue` in + the checkout. 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. + +## Stop the runner + +Turn the setting off and restart the workspace. To stop it until the next +start, run `tmux kill-session -t claude-runner`. + +More: diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index c4aa0d3..2686984 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -26,13 +26,14 @@ since another session can start at any time. - Each runner clones into its own directory, `~/workspace/runner-/`, so no other session uses your checkout while you work. Never change files, branches or git state under another runner's directory. -- A runner keeps its checkouts from one session to the next, so yours can - hold what an earlier session left behind. See "Leave the checkout clean" +- 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. -- If you need a second checkout of your own repository, use a worktree - next to it, not a new clone: - `git worktree add ../- -b `. - Remove it with `git worktree remove` when you are done. +- 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. - Put scratch files in `~/tmp//`, not directly in `~/tmp`. ## Leave the checkout clean @@ -41,12 +42,17 @@ When a session starts in a checkout that is not clean, a hook prints the changed paths. Untracked files left by another branch can break a build or change what it generates, such as DDEV's image tags. -- At the start, run `git status`. Do not commit changes you did not make. -- Before deleting an untracked file, check that a commit holds the same - content: `git log --all --oneline -1 --find-object=$(git hash-object )`. - Delete only the files this finds. Ask the user about the rest. -- Restore a tracked file only when the change is generated output, or when - the user agrees. +- 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"`. + 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, + commit your work, and push it if the task includes pushing. What you + leave uncommitted is stashed when the session ends, and a resumed session + may run on another runner, in a checkout without it. +- If the hook says this session was released earlier and its changes were + saved, tell the user what was saved before restoring any of it. - At the end, delete the branches, worktrees and stashes you created, and leave `git status` clean. diff --git a/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check b/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check index 88826ed..d621f33 100755 --- a/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check +++ b/freeform/modules/claude-self-hosted-runner/files/claude-checkout-check @@ -1,20 +1,31 @@ #!/usr/bin/env bash # Claude Code SessionStart hook, installed by the claude-self-hosted-runner -# module. A runner keeps its checkouts from one session to the next, so tell -# a new session when an earlier one left changes behind. Usage: +# module. A runner keeps its checkouts from one session to the next, and +# claude-runner-sweep cleans them after each session. Tell a new session when +# that did not happen, and tell a resumed one where the sweep put its work. +# Usage: # claude-checkout-check # Prints nothing for a clean checkout or one outside the base dir, such as a # project you run claude in by hand. base="${1:?usage: claude-checkout-check }" +rescue_root="${CLAUDE_RUNNER_RESCUE_DIR:-$HOME/.local/state/claude-runner-rescue}" dir="${CLAUDE_PROJECT_DIR:-$PWD}" case "$dir/" in "${base%/}"/*) ;; *) exit 0 ;; esac +# The hook's input names this session; the sweep logs the runner's ids for it. +input=$(cat 2>/dev/null) +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 stash list | grep runner-rescue). 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, and they can break a build. Before you build, test or commit, follow \"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\". 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" diff --git a/freeform/modules/claude-self-hosted-runner/files/claude-runner-loop.sh.tftpl b/freeform/modules/claude-self-hosted-runner/files/claude-runner-loop.sh.tftpl index acaed8d..daa7387 100644 --- a/freeform/modules/claude-self-hosted-runner/files/claude-runner-loop.sh.tftpl +++ b/freeform/modules/claude-self-hosted-runner/files/claude-runner-loop.sh.tftpl @@ -13,11 +13,21 @@ export GIT_CONFIG_GLOBAL="$base/.gitconfig" # forwarded agent when one is connected, otherwise the Coder workspace key. # Without it, sessions can't push to an SSH remote such as a fork. export SSH_AUTH_SOCK="$HOME/.ssh-agent-relay/agent.sock" +# The runner keeps its checkouts between sessions. Its post-session hook cleans +# them (claude-runner-sweep), and so does this loop before every start, for a +# runner that was killed before its hook ran, as when the workspace stops. +hooks="$HOME/.claude-runner/hooks/runner-$n" +mkdir -p "$hooks" +printf '#!/usr/bin/env bash\nexec "$HOME/.local/bin/claude-runner-sweep" %q\n' "$base" >"$hooks/post-session" +chmod +x "$hooks/post-session" while true; do + "$HOME/.local/bin/claude-runner-sweep" "$base" started=$(date +%s) /home/linuxbrew/.linuxbrew/bin/claude self-hosted-runner \ --environment-secret-file "${secret_file}" \ --base-dir "$base" \ + --hooks-dir "$hooks" \ + --post-session-hook-timeout-sec 120 \ --capacity 1 \ --client-label "$CODER_WORKSPACE_NAME-$n" \ --use-anthropic-git-proxy \ diff --git a/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep b/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep new file mode 100755 index 0000000..7ff74dd --- /dev/null +++ b/freeform/modules/claude-self-hosted-runner/files/claude-runner-sweep @@ -0,0 +1,131 @@ +#!/usr/bin/env bash +# Installed by the claude-self-hosted-runner module. Cleans one runner's +# checkouts after a session, so the next session starts clean. Usage: +# claude-runner-sweep +# 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. +# - 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//