shedix

Guide for agents

Hand off from Cursor or any other agent, so the person can close the laptop

Hand off work from Cursor or any agent whose conversation can't move: write HANDOFF.md, copy the project to a shedix machine, and start Claude Code or Codex there to continue from it. Agents read the same text at /agents/handoff-other.md.

For "Move this session to a shedix machine so I can close my laptop" from Cursor or another agent whose conversation can't move ("Fork this session" from such an agent works the same way: write HANDOFF.md, and keep working here too).

Done when: Claude Code or Codex is working on the machine from a written handoff, in tmux, and the person knows the machine's name and where to find it. About 5 minutes.

Your conversation can't move to another computer, so write down what it knows, and an agent on the machine continues from that. The machine has Claude Code and Codex: ask the person which one to use first (Claude Code if they don't mind), since the first step checks that one is signed in there.

Before this: the key, "Set up once" and the whole first step in https://shedix.dev/agents.md: the machine ready and connected as $NAME, the chosen agent signed in there (signed claude or signed codex), and the person's answer about private files.

1. Write HANDOFF.md in the project

Write it for an agent that has seen nothing of this conversation:

  • Goal: what the person wants, in their words.
  • Done so far: what's finished, and how you checked it.
  • Decisions: what was decided and why, and what was ruled out.
  • Next: the remaining steps, in order, and how to check each one.
  • Run and test: the commands, ports and test data.
  • Open questions for the person.

Commit it with the rest of the work (it's for the machine, so leave secrets out of it).

2. Move the work there, with its history

Commit and push first, so the machine starts from exactly this state: make a new branch (git switch -c <name>), add the changed and new files by name (never one from the private list in the first step: check git status --short before committing), commit, and push it when there's a remote. Then copy the project with its .git, which needs nothing else. The private files the person kept back stay behind (--exclude-from, the list from the first step):

rsync -azL --exclude-from="$HOME/.config/shedix/leave-out-$NAME.txt" \
  --exclude=node_modules --exclude=.venv --exclude=venv --exclude=__pycache__ --exclude=target \
  --exclude=dist --exclude=build --exclude=.next --exclude=.turbo --exclude=.cache --exclude=coverage \
  --exclude='*.log' -e "ssh -F $HOME/.config/shedix/ssh/$NAME.conf" ./ ${NAME}:work/app/
ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME 'cd ~/work/app && git log -1 --oneline && git status --short | head'

Name the folder after the project instead of app, and use that name in the steps below. Tell the person exactly which private files were sent (the first step's list, less those left out), and which stayed behind.

A git worktree's .git is only a file pointing at the main checkout, so for a worktree, push the branch and clone it into ~/work/app on the machine instead (a private repository needs the machine connected to GitHub: https://shedix.dev/agents/github.md), then send the private files the person approved, by name:

printf '%s\n' .env api/.env.local | rsync -azL --files-from=- -e "ssh -F $HOME/.config/shedix/ssh/$NAME.conf" ./ ${NAME}:work/app/

3. Start the agent there

Claude Code, in tmux, with Remote Control on so the person can follow it in the Claude app:

ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME "tmux new -d -s claude-handoff -c ~/work/app 'claude --remote-control \"app (from laptop)\" \"Read HANDOFF.md and continue from Next. Tell me what you are doing.\"'"

The first time Claude Code runs in this folder it may ask a colour theme and whether to trust the folder: the person answers them at https://shedix.dev/m/$NAME/claude?t=claude-handoff, which opens this session in their browser.

Codex. Let Codex trust the project folder, then start it in tmux, inside Codex's background service when the ChatGPT app is set up for this machine:

ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME 'D=$HOME/work/app; mkdir -p ~/.codex; grep -qF "[projects.\"$D\"]" ~/.codex/config.toml 2>/dev/null || printf "\n[projects.\"%s\"]\ntrust_level = \"trusted\"\n" "$D" >> ~/.codex/config.toml'
ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME "R=\$(pgrep -u \$USER -f '[c]odex app-server --remote-control' >/dev/null && echo '--remote unix://'); tmux new -d -s codex-app -c \$HOME/work/app \"codex \$R -C \$HOME/work/app 'Read HANDOFF.md and continue from Next. Tell me what you are doing.'\""

4. Check it's running

sleep 5; ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME 'tmux capture-pane -p -t claude-handoff | grep -v "^\s*$" | tail -n 8'   # or -t codex-app

You should see the agent reading HANDOFF.md or working on it, or Claude Code's first questions waiting for the person.

5. Tell the person

  • The machine's name, and where it is: https://shedix.dev/m/$NAME/claude?t=claude-handoff (or https://shedix.dev/m/$NAME/codex?t=codex-app) from any browser; or the Claude app (by the name above) or the ChatGPT app (Codex, then the machine), when they use those.
  • Which private files were sent, and which stayed behind.
  • That it's a new session that has read HANDOFF.md, not this conversation.
  • To stop the agent on the laptop, so the two don't work on the same thing.