Durable PTYReference
Agents
How dpty finds an agent's own session id and uses it to resume the conversation, instead of just replaying a shell.
In this guide
Guide
On this page
How resume works
An agent CLI keeps its own conversation state in its own session files. dpty does not try to replay what you typed — instead it finds the agent's session id and asks the agent to resume that id. On recovery, dpty relaunches the agent in the same working directory and environment, drops the original prompt (the agent already has it), and keeps every other flag you launched with.
claude and codex
claude is launched with --session-id <uuid>, so dpty generates and knows the id from the moment the session starts. Recovery runs claude --resume <id>.
codex does not take an id up front. dpty finds it by scanning ~/.codex/sessions after the session launches. Recovery runs codex resume <id>.
Restart policies
Every session has a restart policy, checked when its process exits:
| Policy | Behaviour |
|---|---|
never | The session is left exited. This is the default for a plain shell or an unrecognized command. |
on-failure | Restarted only if the process exited with a non-zero code. This is the default for claude, codex and grok. |
always | Restarted every time the process exits, success or failure. |
Set it explicitly with dpty new --restart on-failure … or change it later with dpty set ID --restart always. A session that keeps failing is capped at 5 restarts per 60 seconds, then marked restart-loop instead of retried forever.
The tag-agent hook
If an agent's session id cannot be detected automatically, the agent itself (or a hook it runs) can report it:
$DPTY_SESSION is the session's own id, available in its environment. Once tagged, dpty uses that id on the next resume.
Adding a custom agent
For an agent dpty has no built-in adapter for, pass --kind to name it and --resume-cmd to say how to resume it, with {id} standing in for the session id:
To support an agent in dpty itself rather than per-session, see CONTRIBUTING.md — adapters live in src/agents.rs.