Per-tab Claude Code session resume in agterm

[ssgreg]

Per-tab Claude Code session resume in agterm

Keep several Claude Code sessions open at once? With this, after the terminal
restarts each tab resumes its own conversation instead of a shared
"most recent" one.

What it's good at

• Solves a concrete pain: multiple parallel Claude Code sessions survive a
  restart, each reopening exactly its own conversation.
• Zero state: the conversation id is the tab's uuid (AGTERM_SESSION_ID).
  No mapping file to keep in sync or let go stale.
• Idempotent: the first launch pins the conversation to the tab
  (--session-id); later launches continue it (--resume) - it flips
  automatically.
• Stays out of the way: claude mcp, -p, an explicit
  claude --resume <other-id>, and any launch outside agterm pass through
  untouched.
• Small, dependency-free, pure zsh; options are function-local (emulate -L),
  so nothing leaks into your interactive shell.

Limitations

• agterm-specific. It needs a stable per-tab identifier and relies on agterm
  feeding the restored command back through the login shell (that is how the
  function intercepts it). It won't work as-is in another terminal - you'd adapt
  it to that terminal's equivalent.
• Rests on restore behavior that is verified empirically, not documented -
  it could change between agterm versions.
• One conversation per tab. Since conversation id = tab id, two live
  claude processes in the same tab (a split/scratch pane shares one
  AGTERM_SESSION_ID) collide with "Session ID ... is already in use".
• It shadows the claude command with a shell function. Passthrough is
  handled, but the list of subcommands/flags that must not be touched has to be
  kept current if the CLI grows new ones.
• It knows Claude Code's on-disk layout (~/.claude/projects/*/<id>.jsonl).
  If that storage location changes, the "does this conversation exist" check
  breaks (it would always create, then hit "already in use" on restart). A
  one-line fix, but worth knowing.
• zsh only (${:l}, the (N) glob qualifier, emulate). Bash needs a
  rewrite.
• Existing conversations aren't bound to tabs. After you install this, the
  first launch in a tab starts a new conversation pinned to that tab - it does
  not adopt an arbitrary earlier one.

How it works (plain)

agterm can remember the command running in a tab and re-run it on restart. The
catch: it re-runs the command verbatim, and claude with no arguments is a
new conversation, not a continuation.

The trick rests on two facts. Every agterm tab has a stable identifier
(AGTERM_SESSION_ID) that survives a restart. And Claude Code lets you supply a
session id from the outside (--session-id). So you can use the tab's id as the
conversation id - and the tab permanently "owns" one conversation.

The function then wraps claude: on the first launch in a tab it pins the
conversation to the tab id (--session-id); if that conversation's file already
exists on disk it continues it (--resume). The whole decision is one check: is
<tab-id>.jsonl present under ~/.claude/projects/?

On restart agterm replays the remembered command, the function recognizes "its
own" id, sees the conversation already exists, and reopens exactly that one.
Each tab, its own.

The function

# Claude Code: per-agterm-tab session resume.
# Binds each tab's Claude Code session id to the tab's own uuid (AGTERM_SESSION_ID),
# so restoring the terminal resumes that tab's own conversation instead of starting fresh.
# Requires: agterm (exports AGTERM_SESSION_ID, restores running commands) + zsh.
claude() {
  emulate -L zsh
  local sid=${AGTERM_SESSION_ID:l}
  [[ -z $sid ]] && { command claude "$@"; return; }             # not in an agterm tab -> passthrough

  if [[ "$1" == (--session-id|-r|--resume) && "${2:l}" == $sid ]]; then
    shift 2                                                      # restore replayed our own flag -> re-decide below
  else
    local a
    for a in "$@"; do                                           # user steering a session/subcommand/headless?
      case $a in
        -r|--resume|--session-id|--resume=*|--session-id=*|-r=*|-c|--continue|-p|--print|-v|--version|-h|--help|mcp|update|doctor|config|install|migrate-installer|setup-token)
          command claude "$@"; return ;;                        # -> hand off untouched
      esac
    done
  fi

  local -a f=(~/.claude/projects/*/$sid.jsonl(N))               # does this tab's session already exist?
  if (( $#f )); then command claude --resume "$sid" "$@"        # yes -> continue it
  else command claude --session-id "$sid" "$@"; fi              # no  -> create it with this fixed id
}

Where and how

• File: ~/.zshrc - the config your interactive login zsh reads. That
  matters: agterm feeds the restored command into that shell, so the function
  must be defined there (not in .zshenv / .zprofile).
• Requirements: zsh; agterm with "Restore running commands on restart"
  enabled (Settings); Claude Code sessions stored in the default
  ~/.claude/projects/.
• Activate: new tabs/shells pick it up automatically; in an already-open
  shell run source ~/.zshrc.
• Verify: open a tab, run claude, say a few words, restart the terminal -
  the tab should return to the same conversation. ps will show
  claude --resume <tab-id>.
• Remove: delete the function block from ~/.zshrc.

[brusnigin]

Per-tab Codex CLI session resume in agterm

Same idea as Claude Code: each tab reopens its own codex conversation after restart instead of the shared "most recent" one.

Key difference: codex won't accept a session id at launch, so instead of tab-id == session-id, the function maps tab-id → codex-session-id in ~/.codex/agterm/<tab-id> and resumes that. Everything else is identical: agterm-specific, zsh-only, passes through subcommands/exec/explicit resume untouched.

The function

codex() {
  emulate -L zsh
  setopt local_options null_glob
  local sid=${AGTERM_SESSION_ID:l}
  [[ -z $sid ]] && { command codex "$@"; return; }

  local a
  for a in "$@"; do
    case $a in
      -h|--help|-V|--version|--remote|--remote=*|\
      exec|e|review|login|logout|mcp|plugin|mcp-server|app-server|remote-control|app|completion|\
      update|doctor|sandbox|debug|apply|a|resume|archive|delete|unarchive|fork|cloud|exec-server|features|help)
        command codex "$@"; return ;;
    esac
  done

  local mapf=~/.codex/agterm/$sid
  local cid; [[ -f $mapf ]] && cid=$(<$mapf)
  local -a s=(~/.codex/sessions/**/rollout-*-$cid.jsonl(N))
  if [[ -n $cid && $#s ]]; then
    command codex resume "$cid" "$@"; return
  fi

  local before=$(mktemp)
  command codex "$@"; local rc=$?
  local -a new=(~/.codex/sessions/**/rollout-*.jsonl(N.om))
  if (( $#new )) && [[ $new[1] -nt $before ]]; then
    local uuid=${${new[1]:t:r}[-36,-1]}
    [[ $uuid == ????????-????-????-????-???????????? ]] && { mkdir -p ${mapf:h}; print -r -- $uuid > $mapf; }
  fi
  command rm -f $before
  return $rc
}

Where: ~/.zshrc
Activate: source ~/.zshrc
Verify: start codex, run a command, restart agterm—the tab resumes that session.

[denysshnurenko]

@ssgreg thank you very much. It's amazing!

[umputun]

both functions from this thread are now in the repo under cookbook/, a collection of installable agtermctl workflows: claude-session-resume and codex-session-resume. Each carries a byline crediting its author and linking back here, and the code is a verbatim port.

the READMEs reuse your own wording rather than a rewrite. The Claude one keeps all seven limitations as written, including that it rests on restore behavior verified by its author rather than documented, and that a split or scratch pane shares one AGTERM_SESSION_ID so two live claude processes in a tab collide. The Codex one keeps the mapping-file explanation; its "where / activate / verify" lines moved out of the code block into prose, since they were inside the fence here.

two things I noticed reading the codex function, neither changed in your code, both recorded under Limits as my observations: the mapping is written only after codex returns, so a restart while it is still running leaves that tab unmapped and it comes back fresh; and the capture takes the newest rollout in the whole sessions tree, so another tab writing in between can be recorded against the wrong tab.

if either of you would rather your function not be in the repo, or want the wording changed, say so and I will take it out or fix it.

[cherkale]

Per-tab opencode session resume in agterm

Same idea as the two above: each tab reopens its own opencode conversation after a restart instead of starting a fresh one.

Key difference from @brusnigin's codex function: opencode won't accept a session id at launch either, so this one also maps tab-id → session-id, in ~/.local/state/opencode/agterm/<tab-id>. But there is nothing to glob for. opencode keeps conversations in sqlite (~/.local/share/opencode/opencode.db), so the id comes from opencode session list --format json instead. That turned out to be the better surface anyway: it lists the current project's top-level sessions, and since --session is not scoped at all and takes any session that exists, everything the list offers is safe to resume — while a subagent's child session, which the list leaves out, can never be mapped by mistake.

Two things about opencode shaped the rest. --session is validated against existing sessions — an id that is not there makes opencode print an error and exit instead of starting — so the function never passes an id it has not just seen in the list, and a conversation deleted between runs gives you a fresh opencode rather than an error screen. And the session row appears only when the first message is sent, not when the TUI starts, so the id cannot be captured at launch; it is adopted after the run, from the ids that were not in the list before it.

Checked against opencode 1.18.10.

The functions

# opencode: per-agterm-tab session resume.
# Maps the tab's own uuid (AGTERM_SESSION_ID) to an opencode session id under
# ~/.local/state/opencode/agterm/, so restoring the terminal resumes that tab's own
# conversation instead of starting fresh.
# Requires: agterm (exports AGTERM_SESSION_ID, restores running commands) + zsh.

# Session ids of the current project, most recently updated first.
# opencode keeps sessions in sqlite, so the CLI is the only supported way to ask. The list is
# scoped to the project while --session is not scoped at all, so anything listed is resumable.
_agterm_opencode_sessions() {
  emulate -L zsh
  local line
  command opencode session list --format json 2>/dev/null | while read -r line; do
    [[ $line == '"id": "ses_'* ]] || continue      # one field per line, so a title cannot fake an id line
    line=${line#*: \"}
    print -r -- ${line%%\"*}
  done
}

opencode() {
  emulate -L zsh
  local sid=${AGTERM_SESSION_ID:l}
  [[ -z $sid ]] && { command opencode "$@"; return; }              # not in an agterm tab -> passthrough

  local mapf=${XDG_STATE_HOME:-$HOME/.local/state}/opencode/agterm/$sid
  local cid; [[ -f $mapf ]] && cid=$(<$mapf)

  if [[ $1 == (-s|--session) && -n $cid && $2 == $cid ]]; then
    shift 2                                                        # restore replayed our own flag -> re-decide below
  else
    local a
    for a in "$@"; do                                              # user steering a session/subcommand?
      case $a in
        -s|--session|--session=*|-c|--continue|--fork|-h|--help|-v|--version|\
        run|attach|serve|web|acp|mcp|models|stats|export|import|session|plugin|plug|db|\
        debug|agent|providers|auth|github|pr|upgrade|uninstall|completion)
          command opencode "$@"; return ;;                         # -> hand off untouched
      esac
    done
  fi

  local -a before=( ${(f)"$(_agterm_opencode_sessions)"} )         # what existed before this run
  if [[ -n $cid ]] && (( ${before[(Ie)$cid]} )); then
    command opencode --session $cid "$@"                           # this tab's session is still there -> continue it
    return
  fi

  command opencode "$@"                                            # nothing to resume -> plain run, then adopt what it made
  local rc=$? id
  for id in ${(f)"$(_agterm_opencode_sessions)"}; do
    [[ -n $id ]] || continue
    (( ${before[(Ie)$id]} )) && continue                           # was already there -> not this run's
    command mkdir -p ${mapf:h} && print -r -- $id > $mapf
    break
  done
  return $rc
}

Where: ~/.zshrc (both functions).
Activate: source ~/.zshrc.
Verify: start opencode, send at least one message, quit it, then start it again in the same tab — ps shows opencode --session ses_…. Restart agterm and the tab comes back to that conversation.

Limits worth knowing

• The mapping is written only after opencode exits, same as the codex function: a restart while it is still running leaves that tab unmapped and it comes back fresh. From the first clean exit onward the tab is covered twice, by the mapping file and by the replayed --session line.
• The session list is shared across every tab in the project, so if another tab starts a conversation while this one is running, this one can adopt that id on exit. Outside a git repository the project is global, spanning every non-repository directory on the machine, so there the neighbour can be a tab working somewhere else entirely.
• The tab keeps the conversation it first adopted; switching sessions inside the TUI does not move the mapping.
• The binding follows the project: the "does it still exist" check is project-scoped, so the same tab used in another repository starts a fresh conversation there and the mapping moves to it. A tab owns one conversation at a time, not one per project.
• It costs a session list call per launch, the better part of a second, so the TUI appears that much later.
• opencode <path> is not mapped: the list is taken in the shell's own directory, so a conversation started in another project is never seen there.
• It reads the shape of session list --format json (one field per line). If that ever becomes single-line JSON, no mapping is written and every tab starts fresh — it fails toward a new conversation rather than the wrong one.

I have this written up as a cookbook recipe as well — opencode-session-resume/ with the README in the six-heading template and the index row, following cookbook/CONTRIBUTING.md. Happy to send it as a PR, or leave the function here for you to port like the other two, whichever you prefer.

Edited 31 Jul: corrected the claim that session list and --session are scoped alike — they are not, the list is per project and --session takes any session that exists (the recipe only needs the list to be a subset of what a resume accepts, which it is); and added two Limits entries, on the global project and on the mapping moving when the tab is used in another repository.

[umputun]

the recipes now live in cookbook/, with the rules in CONTRIBUTING.md and the two neighbours to copy the shape from, claude-session-resume and codex-session-resume. Yours would sit next to them under your own name, if you feel like sending it there.

two details those two already settle: both functions go in one .zsh file committed without the executable bit, since the reader pastes them into ~/.zshrc instead of running them, and Requirements names the minimum agterm version as "X or later" - AGTERM_SESSION_ID plus restore-running-commands puts you at 0.3.1, same as the other two, with opencode 1.18.10 as the version you checked against.

your Limits section is worth keeping as written. The session list shape one and the adopt-another-tab's-id one are exactly what gets lost in a port.