---
title: "Resume native agent conversations"
description: "con can keep a supported native agent conversation linked to its exact terminal surface, then resume that conversation after con or the machine restarts."
canonical: "https://con.nowledge.co/docs/native-agent-sessions/"
source: "https://github.com/nowledge-co/con-terminal/blob/main/docs/native-agent-sessions.md"
keywords: "terminal emulator, AI terminal, terminal-first AI agent, terminal agent, AI agent terminal, agentic terminal, agent-native workflows, open-source terminal, open-source AI terminal, Warp alternative, Warp terminal alternative, terminal for coding agents, CLI agent workflows, SSH AI terminal, tmux AI terminal, GPU terminal, Rust terminal, native terminal app, developer tools"
---

# Resume native agent conversations

con can keep a supported native agent conversation linked to its exact terminal
surface, then resume that conversation after con or the machine restarts.
This first implementation supports local macOS terminals. The native CLI and
its history must remain installed on the same machine.

## Start normally

On macOS, conversation recovery is on by default. With the default zsh shell, open a con terminal and run
`claude` or `codex` normally. Their native hooks apply only to that launch:
Claude loads a con-owned local plugin with `--plugin-dir`; Codex uses its
session-flags configuration layer and terminal-independent `--no-daemon` mode.
Native hook and workspace trust prompts remain native. No setup command is
required, and con does not edit their profiles, settings, authentication or
history, or your shell startup files.

con keeps its launchers and shell bridge in its own application data directory.
The bridge runs your ordinary zsh startup files and the installed
Ghostty shell integration, then exposes the launchers only in that con terminal.
It restores the user's effective zsh configuration directory after startup.
The beta.168 hotfix also restores the ordinary history path and automatically
merges commands that beta.167 saved in con's private bridge directory. Recovery
runs when a new zsh starts, after user history-path overrides, and retains both
source history and private pre-merge backups. Existing history is appended to,
never replaced. Concurrent pane startups wait only briefly for recovery; if
another recovery or a native zsh writer stays busy, they continue quietly and
retry on a later terminal start. Deferred attempts never mark records recovered.
Once the retained source is checkpointed, later starts do not lock or read the
user’s history again unless new source records appear. Actual file/access errors
still report a recovery warning. Recovery remains available if agent auto-resume
was disabled.
The native CLI still resolves the actual profile, model, permissions and history
from your normal environment and arguments. No profile or credential copies are
made. Explicit remote clients, batch commands and nested native tool calls pass
through. User aliases/functions and absolute binary paths retain their behavior
and can bypass the launcher.
The automatic shell entrypoint currently covers zsh. System Bash 3.2 does not
run the required ENV startup bridge; Bash/fish integration is left unchanged
until a verified bridge preserves their native startup behavior. Existing
explicit native hooks remain usable in those shells.

For Codex 0.166, terminal-local execution is necessary because shared-daemon
hooks cannot identify the TUI client. This compatibility layer preserves native
history, arguments, signals and exit status until upstream supplies client-side
session attachment events; see [the design](https://con.nowledge.co/docs/design/native-agent-client-link/).

An old conversation started before integration must be explicitly resumed once
in a new con terminal to establish its link. con never guesses one from recent
history. Other shells and explicit native safe/bare/ephemeral modes do not
acquire automatic links. Missing native history never creates a new conversation
as a substitute.

The native recovery registry also includes Cursor Agent, Qwen Code and GitHub
Copilot. These additional adapters currently require explicitly installed native
hooks; automatic profile-free launch integration covers Claude Code and Codex.
All adapters use exact native resume flags:

| Agent | Install name | Native store override | Exact resume |
|---|---|---|---|
| Claude Code | `claude` | `CLAUDE_CONFIG_DIR` | `claude --resume ID` |
| Codex | `codex` | `CODEX_HOME` | `codex resume ID` (con selects local mode) |
| Cursor Agent | `cursor` | `CURSOR_CONFIG_DIR` | `cursor-agent --resume ID` |
| Qwen Code | `qwen` | `QWEN_HOME` | `qwen --resume ID` |
| GitHub Copilot | `copilot` | `COPILOT_HOME` | `copilot --resume=ID` |

For an explicitly requested legacy/profile integration, the companion CLI still
provides `native-session install --agent NAME [--config-dir /absolute/path]` and
`uninstall`. Those explicit commands modify native settings, with private backups;
Codex installation can also edit a specified shell startup file. They are never
called by the automatic launch path. Cursor requires one local
workspace root and native transcripts enabled; its native `XDG_CONFIG_HOME/cursor`
fallback is respected when `CURSOR_CONFIG_DIR` is unset. Qwen histories must remain within
`QWEN_HOME`; a separate `QWEN_RUNTIME_DIR` outside that store is currently refused
at recovery. Unsupported or missing history never falls back to a recent session.

SessionStart links the exact native session ID, working directory, native store
and history path to that surface. It does not collect prompt text, credentials
or transcripts into con's layout file. The native agent owns its conversation
history. OSC 7501 activity reports and process names do not establish this link.

## Choose how to restore

By default, con restores the workspace and resumes valid linked conversations.
To restore only the layout without relaunching native agents, turn off
**Settings → General → Continuity → Resume Agent Sessions** and save Settings,
or set:

```ini
con.appearance.resume_agent_sessions = false
```

This preference is independent of terminal screen replay. Explicit `false`
settings are preserved. With automatic recovery disabled, linked conversations
remain available through **Resume Agent Session** in the terminal/surface menu:

```sh
con-cli --json surfaces list --tab 1
con-cli --json surfaces resume-agent --tab 1 --surface-id EXACT_SURFACE_ID
```

On restart, con resumes each valid linked surface once, including inactive tabs
and stacked surfaces. It waits for a proven local shell prompt and launches the
native CLI visibly in the recorded directory and native store. It selects the
exact saved conversation, never `--last`, and prevents concurrent automatic
resume of the same native identity. It sends no prompt and replays no tool call.
The agent retains its normal permission and trust flow.

On macOS, native session reports reach the terminal that launched the agent,
including terminals in a second con window and terminals moved between windows.
When quitting with several ordinary windows open, con saves their tabs together.
On restart, those tabs reopen in one window with their pane and surface layouts
intact. A window explicitly closed while another ordinary window remains open
is removed from the saved layout.

A restored native terminal starts with the native conversation UI instead of
replaying an old terminal screen over it. Hidden surfaces remain hidden until
the current canvas commits their real geometry.

## If recovery needs attention

`tree` and `surfaces list` expose a `native_agent` object with the saved reference,
phase and diagnostic. `started` acknowledges native process startup; Codex may
confirm its session only on the next user turn. con sends no extra prompt to
force that event. `observed` means a native hook confirmed the link; it is
not a claim that an agent is currently working. Hover information distinguishes
saved, resuming, linked, failed and interaction-needed conversations.

If the native CLI, directory or exact history is unavailable, or the native
agent needs onboarding, authentication or hook approval, inspect the terminal.
con retains the reference and does not create a replacement conversation or
relaunch repeatedly. After resolving the problem, resume explicitly. Do not
launch again when delivery is uncertain. An active TUI or remote SSH session is
not a safe shell target.

**Forget Session Link** removes only con's saved reference, retaining native
history and the running terminal. Its CLI equivalent is:

```sh
con-cli --json surfaces forget-agent --tab 1 --surface-id EXACT_SURFACE_ID
```

To remove con's integration from a native profile:

```sh
con-cli native-session uninstall --agent claude
con-cli native-session uninstall --agent codex
```

Uninstall preserves other hooks and native history; it leaves Codex's general
hooks feature enabled because other integrations may need it.

## Boundaries

- This resumes conversations in new processes after restart. It does not keep
  processes alive, run a server, or guarantee recovery of an unfinished tool.
- Native recovery currently runs on macOS for the adapters listed above. Windows/Linux retain
  references without launching; additional native agents need explicit adapters.
- Remote hosts, ephemeral sessions, missing histories and unsupported profiles
  are not silently migrated. Profiles requiring extra CLI flags need manual
  native setup; con does not persist arbitrary launch commands or permission flags.
- Private session files contain local paths and native IDs. Shared workspace
  profiles exclude these references. Treat native history according to the
  native agent's own privacy and retention settings.
- Verified native CLI versions and the exact live validation scope are recorded
  in [the implementation study](https://con.nowledge.co/docs/study/con-agent-orchestration/).

Cross-agent context transfer is a different operation: see
[Agent Handoff](https://con.nowledge.co/docs/con-cli/#agent-workflows). It does not replace exact native resume.
