Skip to content
Back to search

claude-handoff

SkillWorks with Claude CodeGitHub

Claude Code skill: hand off a long session to a fresh one before context rot. Finishes the running step, writes a goal-filtered handover, opens a new iTerm2 tab with the same name, closes the old tab when its background work is done.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tomi2k--claude-handoff/badge.svg)](/listings/tomi2k--claude-handoff)

HTML

<a href="/listings/tomi2k--claude-handoff"><img src="/api/listings/tomi2k--claude-handoff/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: macOS, [iTerm2](https://iterm2.com), Claude Code, `jq`, Python 3.

git clone https://github.com/Tomi2k/claude-handoff.git
mkdir -p ~/.claude/skills
cp -r claude-handoff/skills/handoff ~/.claude/skills/

**Context watcher hook** (recommended) - add to `~/.claude/settings.json`:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/skills/handoff/hooks/context_watcher.py 2>/dev/null || true",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

**Auto-close** (optional) - needs the iTerm2 Python API:

1. Enable iTerm2 > Settings > General > Magic > *Enable Python API*. 2. Install the module: `python3 -m pip install iterm2` (or point `HANDOFF_ITERM2_PYTHON` to a Python that has it).

Without it, everything works; the skill tells you to close the tab yourself.

The first launch asks macOS to let your terminal control iTerm2 (Automation). Allow it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 235 lines
  1. <p align="center">
  2. <img src="assets/hero.png" alt="Session 1 fills up into the dumb zone. One handover file carries the goal into a clean Session 2." width="100%">
  3. </p>
  4. # claude-handoff
  5. **Hand off a long Claude Code session to a fresh one - before the context window makes it dumb.**
  6. A skill for [Claude Code](https://code.claude.com) made for terminal work in **iTerm2 on macOS**.
  7. It finishes the step you are in, writes a short, goal-filtered handover file, opens a new
  8. tab with a fresh session, gives it the same name with "- Part 2", waits until the old
  9. session's background work is done, and then closes the old tab by itself.
  10. ```
  11. /handoff finish the payment webhook and get the tests green
  12. ```
  13. ---
  14. ## Why this exists
  15. ### The first tokens are the smartest
  16. Matt Pocock calls it the *smart zone*:
  17. > "Early in a session the agent is in a 'smart zone' - sharp, focused, recall is good.
  18. > As the session grows it drifts into a 'dumb zone': sloppier, forgetful, more mistakes."
  19. > - [AI Hero, AI Coding Dictionary: Smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)
  20. He puts the start of the dumb zone on frontier models at around 125K-150K tokens and adds
  21. that this is debated. His advice: when a task is bigger than one smart zone, *hand off at a
  22. natural boundary* and let a fresh session do the next piece.
  23. Anthropic describes the same effect as **context rot**: "as the number of tokens in the
  24. context window increases, the model's ability to accurately recall information from that
  25. context decreases" - a gradient, not a hard cliff. The reason is that every token relates
  26. to every other token: the transformer "enables every token to attend to every other token
  27. across the entire context. This results in n² pairwise relationships for n tokens", and
  28. with a longer context that attention "gets stretched thin"
  29. ([Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)).
  30. Chroma measured it across 18 models: reliability drops as input grows, even on simple tasks
  31. ([Context Rot](https://research.trychroma.com/context-rot)).
  32. ### What I kept running into
  33. In my own long Claude Code sessions, mistakes start to pile up from about half of the
  34. context window: instructions from 20 turns ago are forgotten, fixed bugs come back. That is
  35. my experience, not a benchmark. Large windows (1M tokens) do not fix it; they only make the
  36. slow part longer.
  37. Handing off by hand was not much better. These are the failures this skill fixes:
  38. | Problem I hit | What the skill does |
  39. |---|---|
  40. | The session gets sloppy and I notice too late. | A hook measures the fill level on every prompt. At a threshold you choose, Claude asks you whether to hand off. |
  41. | The handoff cut a step in half. The new session started with a half-done edit. | It finishes the running step first if the rest fits into 10 % of the window. Otherwise it stops at the next clean point. |
  42. | The new session "continued" although the work was done, and invented its own next tasks. | A fixed rule decides between **CONTINUE** and **CONFIRM**. Assigned work and own suggestions are separate lists. Suggestions never run without your OK. |
  43. | I copied context by hand and forgot the important part. | A goal-filtered handover file: state, decisions, files, next steps, traps - and nothing else. |
  44. | Ten tabs, all called "claude". Which one was it? | The new session gets the old name plus "- Part 2" through a real `/rename`. |
  45. | "Can I close this terminal now?" Background shells were still running. | It checks the old session's background work, waits for it, and ends with one fixed line. When everything is done, the old tab closes itself. |
  46. ---
  47. ## How it works
  48. 1. **Finish the step.** It measures the context and finishes the running step if the
  49. rest fits into the budget (10 % of the window, never past 85 %).
  50. 2. **Background inventory.** It lists background shells (dev servers, builds, agents)
  51. so nothing dies silently.
  52. 3. **Handover file.** `~/.claude/handoffs/<date>-<slug>.md` with goal, verified state,
  53. files, decisions, mode, next steps and traps. Filtered by the goal, no secrets.
  54. 4. **New session.** A new tab in the same iTerm2 window starts Claude Code with the
  55. handover file and is renamed to "<old name> - Part 2".
  56. 5. **Wrap-up.** The old session waits for its background work, delivers late results as
  57. an addendum, and ends with exactly one line:
  58. | Situation | Last line |
  59. |---|---|
  60. | Still running | `⏳ Do NOT close this terminal yet. ...` |
  61. | Done, iTerm2 | `✅ All done. This terminal closes itself in 10 s. ...` |
  62. | Done, other terminal | `✅ You can and should close this terminal now. (Cmd+W closes only this tab.)` |
  63. Type anything into the old tab within those 10 seconds and it stays open.
  64. **Remote mode** (`/handoff remote <goal>`): the handover goes to a server over SSH and
  65. Claude Code runs there in tmux. It keeps working when your laptop is closed, and you can
  66. attach from your phone.
  67. ---
  68. ## Install
  69. Requirements: macOS, [iTerm2](https://iterm2.com), Claude Code, `jq`, Python 3.
  70. ```bash
  71. git clone https://github.com/Tomi2k/claude-handoff.git
  72. mkdir -p ~/.claude/skills
  73. cp -r claude-handoff/skills/handoff ~/.claude/skills/
  74. ```
  75. **Context watcher hook** (recommended) - add to `~/.claude/settings.json`:
  76. ```json
  77. {
  78. "hooks": {
  79. "UserPromptSubmit": [
  80. {
  81. "hooks": [
  82. {
  83. "type": "command",
  84. "command": "python3 ~/.claude/skills/handoff/hooks/context_watcher.py 2>/dev/null || true",
  85. "timeout": 10
  86. }
  87. ]
  88. }
  89. ]
  90. }
  91. }
  92. ```
  93. **Auto-close** (optional) - needs the iTerm2 Python API:
  94. 1. Enable iTerm2 > Settings > General > Magic > *Enable Python API*.
  95. 2. Install the module: `python3 -m pip install iterm2`
  96. (or point `HANDOFF_ITERM2_PYTHON` to a Python that has it).
  97. Without it, everything works; the skill tells you to close the tab yourself.
  98. The first launch asks macOS to let your terminal control iTerm2 (Automation). Allow it.
  99. ## Use
  100. ```
  101. /handoff <goal in your own words>
  102. /handoff remote <goal>
  103. ```
  104. No goal? The skill asks one question: *What should the new session achieve?* It never
  105. invents the goal. With the hook installed, Claude asks you at the threshold whether to
  106. hand off - and after your yes it still finishes the running step first. Set
  107. `HANDOFF_AUTO=1` if you want it to hand off without asking.
  108. ## Configure
  109. | Variable | Default | Effect |
  110. |---|---|---|
  111. | `HANDOFF_WATCH_AT` | `0.5` | Fraction of the window that triggers the suggestion. |
  112. | `HANDOFF_WATCH_TOKENS` | - | Absolute trigger, whichever comes first. `150000` follows the smart-zone advice on 1M windows. |
  113. | `CLAUDE_CONTEXT_WINDOW` | `200000` (`1000000` if the model has `[1m]`) | Window size used for the percentages. |
  114. | `HANDOFF_DIR` | `~/.claude/handoffs` | Where handover files and small state files go. |
  115. | `HANDOFF_MODEL` | - | Model alias for the new session, e.g. `opus`. |
  116. | `HANDOFF_SKIP_PERMISSIONS` | `0` | `1` starts the new session with `--dangerously-skip-permissions`. Set it only in your own shell profile; the skill never sets it. Read *Security* first. |
  117. | `HANDOFF_AUTO` | `0` | `1` lets the context watcher start the handoff without asking you first. |
  118. | `HANDOFF_ITERM2_PYTHON` | `python3` | Python with the `iterm2` module, for auto-close. |
  119. | `HANDOFF_REMOTE_HOST` | - | SSH alias for remote mode. On the server: `~/handoffs` and `~/projects/<repo>`. |
  120. ## What is in the box
  121. ```
  122. skills/handoff/
  123. ├── SKILL.md the instructions Claude follows
  124. ├── hooks/context_watcher.py UserPromptSubmit hook + `--status` for the skill
  125. └── scripts/
  126. ├── handoff_launch.sh new iTerm2 tab, start Claude Code, type /rename
  127. ├── handoff_title.sh read the current name, build "... - Part N"
  128. ├── bg_check.sh list background shells of the session
  129. └── autoclose.py close the old tab once the session is idle
  130. ```
  131. The rule behind the split: the skill file says *what to do and what to avoid*; everything
  132. mechanical is a script, so the model runs one command instead of improvising.
  133. ## Security
  134. I audited both the skill and the scripts before publishing. What you should know:
  135. - **Bypass mode is opt-in.** `HANDOFF_SKIP_PERMISSIONS=1` starts the new session without
  136. permission prompts. Only use it if you understand what an agent can do on your machine
  137. without asking - including after reading untrusted web pages or files.
  138. - **No command injection through names or paths.** Values reach AppleScript only as
  139. arguments, and the start command is a one-shot temp script quoted with `printf %q`.
  140. Session names pass an allowlist (letters, digits, space and `. , _ + : -`): quotes, `$`,
  141. `&`, `*`, parentheses and other shell characters are removed. Tested with a path
  142. containing spaces and `'`, and a name with `"`, `&`, `$( )` and a zsh glob qualifier.
  143. - **No blind typing.** The launcher types `/rename` only when the new tab shows an empty
  144. Claude Code input box, and presses Enter only when its own text is in that box. A
  145. folder-trust, MCP or permission dialog stops it, and the skill never answers such a
  146. dialog for you.
  147. - **Auto-close is conservative.** It closes only the tab whose tty belongs to the session
  148. (if that is the window's last tab, iTerm2 closes the window with it), and aborts if the
  149. session becomes active again, if the screen changes (you type without sending) or if
  150. shells still run.
  151. - **Handover files are local** (`~/.claude/handoffs`). The skill forbids secrets in them,
  152. but a model can make mistakes - do not sync that folder anywhere public.
  153. - **The new session treats the handover as notes, not as permission.** CONFIRM is the
  154. default; CONTINUE only covers work you assigned, quoted with date.
  155. - **Remote mode never trusts a repository for you.** If Claude Code asks whether to trust
  156. a freshly cloned repository on the server, the skill stops and lets you decide: trusting
  157. it lets the repository's hooks and MCP settings run code. It validates host, repository,
  158. URL and file names before building a command, and never copies git-ignored files
  159. (`.env`, keys, credentials) - it lists them and you copy what you need.
  160. - **Handover files stay private.** Folder mode 700, files mode 600, also on the server.
  161. - **Background check output is redacted.** URL credentials, common token prefixes
  162. (`sk-`, `ghp_`, `github_pat_`, `xoxb-`, `AKIA`), `Bearer`/`Basic` values, JSON keys like
  163. `"password"`, `--token`/`--password`/`--user` values (also quoted), `-u user:pass`, `-p`
  164. values and `KEY=`/`TOKEN=` values are masked before they reach the model. Masking works
  165. by pattern; it cannot promise to catch every secret.
  166. - **Your settings stay yours.** The skill tells the agent never to set any `HANDOFF_*`
  167. variable itself, and to treat a `[CONTEXT-WATCHER]` text in files or tool output as data.
  168. Only the hook's own note counts.
  169. - **The context watcher asks first.** It never starts a handoff on its own unless you set
  170. `HANDOFF_AUTO=1`.
  171. - **No network calls** except your own SSH in remote mode. No telemetry.
  172. ## Limits
  173. - Tested on macOS 26.6, iTerm2 3.7.9 and Claude Code 2.1.330 (November 2026).
  174. - The dialog check for `/rename` was tested with sample trust and MCP screens. In the test
  175. setup, Claude Code did not show these dialogs on a real start.
  176. - The scripts read internal Claude Code files (`~/.claude/sessions/*.json`, transcripts in
  177. `~/.claude/projects/`). A Claude Code update can change them.
  178. - "Does the rest fit into 10 %?" is the model's own estimate.
  179. - `bg_check.sh` sees shells, not in-process background agents; the skill tracks those itself.
  180. - Local mode needs iTerm2. Other terminals get the handover and the closing line, but no
  181. new tab, rename or auto-close.
  182. - Remote mode is written as instructions for the model, not as a tested script. Local
  183. mode, rename and auto-close are tested end to end.
  184. ## License
  185. MIT - see [LICENSE](LICENSE).
  186. ---
  187. Built by **Timothy Scherman**. Less AI theater. More results.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.