How to Return to an AI Coding Agent Session
Keep the branch, conversation, and running process straight before you close a task.
To return to a coding task, reopen its worktree, confirm the branch and files, then inspect or resume its agent conversation. Saved history and a running process are separate things. A restored tab can help you find the task without proving that its previous command is still executing.
Use this guide when you switch between parallel tasks, return after restarting the app, or want a long terminal job to keep running after you detach. For creating separate task directories, start with Git worktrees; for scheduling and reviewing a batch, use the parallel coding workflow.
What needs to survive?#
| Layer | What it holds | What to check when returning |
|---|---|---|
| Worktree and branch | Files, index, commits, untracked work | Directory exists; branch and status match the task |
| Conversation history | Prompts, responses, supported provider session state | Correct provider, task, and latest completed turn |
| Live terminal process | Shell, agent CLI, foreground command | Process is still attached or can be reattached |
| Services | Preview server, database, external job | Server URL, service health, and writable data |
These layers can have different lifetimes. A Git commit survives an agent exit. A saved conversation does not keep a development server alive. A server can continue running while the agent waits for an answer.
Return to the worktree
|
+-- Live session present --> inspect output --> answer or continue
|
+-- Session ended -------> resume supported history --> verify context --> continue
|
+-- Persistent tmux -----> attach to named session --> inspect existing processReturn to the correct workspace first#
Select the task in the Agents navigator. A display name helps you find it, but the branch and directory determine where commands operate. In that worktree's terminal:
pwd
git branch --show-current
git status --shortConfirm these match the task before launching or resuming an agent. If the directory was removed, restoring a conversation alone cannot restore uncommitted files. Preserve work before deleting a checkout.
Switching workspaces does not have the same effect as closing a terminal. Agentastic caches terminal views when they leave the visible hierarchy. You can work elsewhere and return to inspect output while the app remains running. Closing terminals and quitting have separate cleanup paths; do not infer survival across app exit from successful workspace switching.
See agent organization and terminal behavior.
Resume through the terminal menu#
For a supported detected agent session, after its CLI has returned to the login shell:
- Return to its terminal tab.
- Open the terminal options menu or right-click the tab.
- Choose Resume for the detected agent.
- Inspect the resumed conversation or provider picker before submitting another task.
Shell integration records agent commands, including supported agents you started manually. Keep Settings > Terminal > Shell Integration enabled if detection is missing. Installation, authentication, and a valid working directory are still required.
The terminal menu requires an exact detected provider session binding, a visible terminal surface, and an idle login shell. It is disabled while the terminal is busy or the interface is switching. Return to Terminal mode first if you are viewing the terminal through Chat.
When no exact binding is available, use the provider's own session-history selection from the intended directory. Other Agentastic continuation paths can reconstruct a provider's configured resume command, which may mean “latest” or a picker; that fallback is different from this menu's exact-session action. If several sessions were started in the directory, verify the opening prompt and recent messages carefully before continuing. See terminal resume.
Check context before asking for more work#
Suppose an agent was updating catalog filters yesterday. Before sending “finish it,” inspect the files and the previous output, then make the next action concrete:
Continue the catalog filter task on this worktree.
First compare the current diff and branch with the previous summary.
The remaining requirement is preserving selected filters after refresh.
Rerun the focused catalog checks and report the command output.
Do not merge or publish.A resumed agent may have old assumptions about the base branch, dependencies, or local services. If another change landed meanwhile, update the branch through the team's normal Git workflow and rerun validation. Do not treat yesterday's test result as evidence for today's files.
For previews, restart or check the server and use its actual URL. The browser tab being restored does not start the application behind it. The environment setup guide covers explicit ports and browser profiles.
Keep a terminal task running with tmux#
When the requirement is to detach from an ongoing terminal job, use a persistent terminal host. tmux separates the server that owns terminal programs from the client displaying them. Install tmux on the machine where the job will execute. This section covers explicit detach and reattach; it does not promise that locally launched work survives Agentastic quitting, whose cleanup can terminate local child processes. For work that must outlive the desktop app, run on a persistent remote host and verify reattachment before leaving it.
From the intended worktree in an Agentastic terminal:
tmux -CC new-session -s catalog-taskRun the installed agent CLI in the tmux pane, for example claude, then give it the task. Agentastic recognizes tmux control mode and presents its windows and panes in a native tab. Choose Detach to leave the session running. To return from another terminal on the same host:
tmux list-sessions
tmux -CC attach-session -t catalog-taskUse a unique session name per task. An existing session's shell keeps its own working directory; attaching from a different checkout does not move it. Run pwd inside the pane before continuing.
Detach and Close Pane are different operations: closing a pane kills that pane. A tmux server can preserve a process across client disconnection, but it cannot execute while its host is asleep or survive a host shutdown. Provider failures, quotas, and requests for input can also stop progress. Use a remote machine that remains available when the laptop is not the right execution host; confirm its lifecycle before leaving work unattended.
Agentastic also has target-specific remote and container session mechanisms. Their host, container, and provider lifetimes differ; do not apply a local terminal assumption to every target. The terminal guide and cloud guide describe those workflows.
Troubleshooting a return to work#
| Symptom | Check | Next step |
|---|---|---|
| Resume is unavailable | Exact session binding, Terminal mode, and idle login shell | Wait for the CLI to exit; use the provider’s history picker if there is no exact binding |
| A continuation shortcut selects another task | Provider picker or recent-session fallback | Inspect provider history and choose the intended conversation |
| Restored tab has no running command | Process lifetime versus saved tab state | Resume history or attach to the named tmux session |
| tmux session is missing | Correct host and tmux server | Check that host's sessions; do not assume a new session contains old work |
| Agent appears inactive | Last response and permission/input request | Inspect the conversation and respond before launching a duplicate |
| Preview no longer loads | Server process and assigned port | Restart in the correct checkout, then reopen the printed URL |
Before removing a completed task, preserve its code, review the diff, and stop its services. Follow the review and integration workflow and the Git worktree cleanup reference.
Frequently asked questions#
Does resuming an agent session restore a running process?#
No. Resuming conversation history starts or reconnects an agent using provider-supported state. It does not recreate arbitrary shell processes, server memory, or unfinished command output.
Can I switch worktrees while an agent works?#
Agentastic caches terminal views when you switch workspaces, so switching away is different from closing a terminal or quitting the app. Return to the worktree to inspect the live session and any pending request.
Does the Resume menu always select the exact conversation?#
The terminal menu requires an exact supported provider session binding and an idle login shell. Without that binding the menu is disabled; use the provider’s own history picker to select an older conversation.
How can an agent keep running after I detach?#
Run the CLI inside a named tmux session on a host that stays available. Agentastic supports tmux control mode as native tabs. Detach leaves the tmux session running; host shutdown or loss of the tmux server still ends it.