Pause and resume agent sessions

Enable recovery when creating an agent to preserve its conversation and tool history across a stop or crash. Continue on the original machine with codity-agent resume --last.

Enable recovery before starting

Check Enable recovery in the agent form, or set recovery_enabled: true when creating a configuration through the Agents API. Recovery is off by default. The one-step codity agent launch command does not currently expose a recovery option; use the dashboard or the API configuration flow when you need it.

Recovery checkpoints are encrypted in Codity and expire 30 days after upload. They include conversation and tool data, which can contain file contents the agent read. Enable recovery only when you are comfortable storing that session data centrally.

Pause normally

Let the agent complete at least one turn, then press Ctrl+C in its terminal. Wait for shutdown to finish. The runner flushes its checkpoint and reports Paused if a resumable checkpoint is available.

From the same working folder:

codity-agent resume --last

The command selects the most recently updated saved session in this folder. It restores history and starts a replacement run under the same agent configuration. The original run remains visible in the dashboard.

If you stop before the first checkpoint, there may be nothing to resume. The terminal reports that condition instead of promising recovery. Generate a fresh install command to start again.

Choose a session or give a new task

# List sessions saved for this folder.
codity-agent sessions

# Pick a session interactively.
codity-agent resume

# List or choose sessions across working folders.
codity-agent sessions --all
codity-agent resume --all

# Resume a specific session ID from the list.
codity-agent resume SESSION_ID

# Continue with a new instruction, retaining previous conversation history.
codity-agent resume --last --prompt "Summarize what we completed and continue the remaining work."

resume --all opens a picker across folders; it does not start every session. A session ID is a saved run ID, not the agent configuration ID in the dashboard URL. A completed session can resume for follow-up work; its original task is not automatically rerun.

Recover after a crash

On the original machine, run codity-agent resume --last after the previous agent process has died. The saved machine credential lets the runner replace that run immediately. You do not need to wait for the dashboard's lost-worker detection.

If the old local process is still alive, resume refuses to start a duplicate. Stop it in its own terminal first. Recovery uses the latest acknowledged checkpoint, so work after that checkpoint may require verification. Codity does not automatically restart a crashed worker.

Review an interrupted action

A process can die after an action takes effect but before its result is saved. For example, a command might have sent a request or changed a file. Resume asks whether the unfinished actions completed or should be retried. Check the actual effects before choosing; retry can repeat side effects.

For a deliberate noninteractive decision:

codity-agent resume --last --reconcile=completed

Or, after confirming that retry is appropriate:

codity-agent resume --last --reconcile=retry

These decisions apply to the interrupted actions listed for that checkpoint. Choosing completed does not reconstruct missing tool output. Explain verified results in a follow-up prompt if the agent needs them. Without an interactive terminal or an explicit decision, resume stops with instructions rather than silently retrying.

Changed files or another machine

Recovery restores conversation and tool state. It does not restore the repository, uncommitted edits, files, installed dependencies, remote state or environment secrets. Checkpoint workspace checks may refuse to continue if the relevant files or checkout changed.

After reviewing and reconciling those changes, explicitly consent with:

codity-agent resume --last --accept-workspace-changes

For another machine, open the original run in the dashboard and use Resume session. Review interrupted actions and expand Changed files or another machine when needed. Copy the command and execute it in a prepared matching working folder on the target. An installed machine can use the direct codity-agent command; the panel also offers an installer command for a new machine. Commands contain short-lived credentials and should be treated as private.

The dashboard can only offer recovery once the source run is eligible; a crashed remote worker may first need to be marked lost. Prepare matching files and machine-side secret access yourself. Policy changes take effect on resume, and the runner needs the engine version compatible with the saved checkpoint.

Local files and unavailable sessions

The installer puts the command in ~/.local/bin/codity-agent and session records in ~/.codity-agent/sessions. Records contain a scoped resume credential, not the provider API key, and are created with private file permissions. Do not share them. CODITY_AGENT_HOME and CODITY_AGENT_BIN_DIR can override the storage and command locations.

Already running agents started with an older runner may not have these local records. Use the dashboard recovery command for an eligible saved checkpoint, or start a new recovery-enabled agent using a fresh installer.

Revoked agents, explicitly stopped dashboard runs, expired checkpoints and sessions already claimed by a replacement cannot be resumed again from that source. Select the latest replacement session when continuing. See Troubleshooting if recovery is unavailable.