shedix

Guide for agents

Fork this session to a machine

Fork this Claude Code or Codex conversation to a shedix machine, so a branch of it runs there with its own session ID while the conversation here carries on untouched. Agents read the same text at /agents/fork.md.

For "Fork this session to a shedix machine". A fork keeps this conversation going here, and a copy of it, with the project as it is now, carries on separately on the machine: its own session ID, its own entry in the Claude app named with "(fork)", its own git branch. To move the work instead (so the person can close the laptop), follow the handoff file for your agent (agents.md, "Which job").

  • Claude Code: sections 1 to 5 below.
  • Codex: section 1, then "Codex" at the end (codex fork).
  • Cursor and other agents can't fork a conversation to another computer: say so, and offer the handoff, which writes what you know into HANDOFF.md for an agent on the machine while you carry on here (https://shedix.dev/agents/handoff-other.md).

Done when: the fork is running on the machine in tmux, the conversation here is unchanged, and the person knows the machine's name, the fork's name and where to find it. About 5 minutes.

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 agent signed in there (signed claude, or signed codex for Codex), and the person's answer about private files.

1. Copy the project as it is, without touching it here

The work here goes on, so don't commit, switch branches or stash here. Copy the working tree with its .git (uncommitted changes arrive as uncommitted changes), leaving out the private files the person kept back, then give the fork its own branch on the machine:

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 && b=$(git branch --show-current) && git switch -c "${b:-work}-fork" && git status --short | head'

Name the folder after the project instead of app. In a git worktree (.git is a file), add --exclude=.git, then git init and commit on the machine, or push a branch and clone it there (https://shedix.dev/agents/github.md). Tell the person which private files were sent, and which stayed behind.

2. Copy the conversation (Claude Code)

This conversation's id is in $CLAUDE_CODE_SESSION_ID (if it's empty: the newest .jsonl in this project's folder under ~/.claude/projects). Copy it without bridgeSessionId, the link to its claude.ai session: a copy that keeps it would take over the laptop's entry in the Claude app. Only this computer's file is read; nothing here changes.

ID=$CLAUDE_CODE_SESSION_ID
SRC=$(find ~/.claude/projects -maxdepth 2 -name "$ID.jsonl" | head -n 1); echo "$SRC"
DIR=$(ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME 'd=$(echo ~/work/app | sed "s/[^a-zA-Z0-9]/-/g"); mkdir -p ~/.claude/projects/$d; echo $d')
python3 -c 'import json, sys; [print(json.dumps({k: v for k, v in json.loads(l).items() if k != "bridgeSessionId"}, ensure_ascii=False)) for l in sys.stdin if l.strip()]' \
  < "$SRC" | ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME "cat > ~/.claude/projects/$DIR/$ID.jsonl"
ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME "grep -c bridgeSessionId ~/.claude/projects/$DIR/$ID.jsonl"   # 0

3. Start the fork

--fork-session makes Claude Code start a new session from the conversation instead of continuing it, and --session-id gives that new session an ID chosen here, so you know it. Name it after the work, ending in "(fork)": that's the name the Claude app shows (Remote Control's name), beside the original. --fork-session doesn't add "(fork)" by itself, so the name must carry it. If the person said what the fork should work on, add it in quotes at the end as its first message; otherwise it waits at its prompt for them.

FORK=$(python3 -c 'import uuid; print(uuid.uuid4())'); echo "$FORK"
ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME "tmux new -d -s claude-fork -c ~/work/app 'claude --resume $ID --fork-session --session-id $FORK --remote-control \"signup form (fork)\"'"

For a second fork of the same conversation, use another tmux name (claude-fork-2) and a new FORK. The first time Claude Code runs in this folder it may ask a colour theme and whether to trust the folder: don't answer the trust question yourself; the person answers at https://shedix.dev/m/$NAME/claude?t=claude-fork.

4. Check it's running

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

You should see the conversation and Claude Code's prompt, or the questions above waiting for the person. If there's no session claude-fork, Claude Code exited at once: run step 3 again with ; sleep 300 after the claude … command, inside its quotes, and look again to read the error. If an older Claude Code refuses --session-id with --fork-session, run step 3 without --session-id $FORK: the fork then picks its own ID (the newest file in ~/.claude/projects/$DIR/).

5. Tell the person

  • The machine's name, and that the fork runs there as its own session: in the Claude app under the name above (with "(fork)"), separate from this one, or from any browser at https://shedix.dev/m/$NAME/claude?t=claude-fork.
  • That this conversation is untouched and carries on here, on its own files; the fork works on the branch <branch>-fork on the machine (to bring its work back, push that branch from the machine once it's connected to GitHub, or fetch it over SSH).
  • Which private files were sent, and which stayed behind.
  • That the machine sleeps after an hour unused, and keeps everything.

Codex

Codex forks too: codex fork <id> starts a new conversation, with its own id, from an existing one (/fork does the same inside Codex). The fork's file holds only a pointer into the original's history, so the original's files must stay on the machine, and the fork works in the folder it's started in (~/work/app, not the laptop's path). After section 1:

  1. Copy the conversation's files to the machine exactly as https://shedix.dev/agents/handoff-codex.md, step 2, says (ID=$CODEX_THREAD_ID), and let Codex trust the folder as its step 3. Only this computer's files are read.

  2. Start the fork in tmux, inside Codex's background service when the ChatGPT app is set up for this machine. If the person said what the fork should work on, add it in quotes after $ID:

    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-fork -c \$HOME/work/app \"codex fork \$R -C \$HOME/work/app $ID\""
sleep 5; ssh -F ~/.config/shedix/ssh/$NAME.conf $NAME 'tmux capture-pane -p -t codex-fork | grep -v "^\s*$" | tail -n 8'

    What you see, and what to do if it's a trust screen, a sign-in or nothing, is as in handoff-codex.md, step 5.

  3. Tell the person the machine's name; that the fork is a new conversation, at https://shedix.dev/m/$NAME/codex?t=codex-fork from any browser (whether and under what name it shows in the ChatGPT app isn't confirmed yet: don't promise it); that this conversation carries on here untouched; and which private files were sent.