# Agents

> Coding agent sessions, workspace activity, the idle grace setting, fresh agents, forks and retained Git work.

## A workspace per agent

A cloud agent is Claude Code or Codex running in a persistent workspace. A project can have a main agent and several
extra agents. Each agent can have a Claude session and a Codex session; opening a live session reattaches it.
The [Cloud agents guide](https://docs.shardflux.dev/guides/cloud-agents.md) covers launch, apps and project sync **(CLI 0.13.2+)**.

`GET /v1/agents`, `cloud.agents.list()` **(TypeScript SDK 0.18.0+)**, `sf.agents.list()`
**(Python 0.14.0+)** and `agents_list` **(MCP 0.12.0+)** report sessions. A workspace detail view carries its
`agents` array. Sessions have an app, state, state-change time, title and optional Remote Control URL.

## States and workspace activity

| Session state | What it means | Command center label |
| --- | --- | --- |
| `working` | A turn is running, including waiting for a model response | working |
| `waiting` | The app is waiting for input or an approval | needs you |
| `exited` | The app process ended | done |

The workspace's parking state is separate. A waiting session in a parked workspace appears as parked. An exited
session stays done. Detached working agents keep going: the session belongs to the workspace, and closing a client
does not end it.

A live working session keeps the workspace awake for its whole turn. Waiting and exited sessions hold it for the
configured grace, then ordinary [idle rules](https://docs.shardflux.dev/concepts/lifecycle.md#idle-running-workspaces-are-parked) apply.
Background commands, CPU/network activity, keepalive and other active tools can also keep it awake. Agent workspaces
count toward the plan's [workspaces working at once](https://docs.shardflux.dev/limits.md#plans) while working or starting.

## Choose the idle grace

Grace keeps a waiting or exited agent awake briefly before normal idle handling. It never interrupts a working
turn. Set it with the workspace's agent idle grace option (TypeScript SDK 0.18.0+, Python 0.14.0+, CLI 0.13.2+,
MCP 0.12.0+). [Agent settings](https://docs.shardflux.dev/limits.md#cloud-agent-reachability) lists the values and defaults.

## New agents and forks

Every new cloud agent starts from its machine and project template. At the workspace API, `like` inherits the source's exact template version, sizes, secret bindings, text inputs,
volumes and agent options on a fresh disk **(TypeScript SDK 0.18.0+, Python 0.14.0+, CLI 0.13.2+, MCP 0.12.0+)**.
Explicit options override inherited ones. Reopening an existing key keeps its disk and template.

A cloud-agent fork copies the whole running state: files, memory, processes and services, with its machine and project template. It has its own agent conversation. Both keep shared-volume attachments, and neither copies the
volume's contents. Shared volumes store data outside workspace snapshots; attached agents can read or write them
according to the mount mode.

Machine and project templates are private filesystem templates and include secrets as ordinary files.
[Save or roll back either environment](https://docs.shardflux.dev/guides/machine-and-template.md); files update live and software at the next start.

## Keep and recover work

Extra-agent Git work is fetched into hidden `refs/shard/<agent>` refs **(CLI 0.13.2+)**. Opening a local editor
creates `.shard/worktrees/<agent>`. Merge applies committed work to the current branch, keep creates a real
`shard/<agent>` branch, and discard deletes the agent's worktree, ref and workspace.

CLI housekeeping archives saved Git work as `refs/shard/archive/<agent>`. `shard agents restore <agent> --path .`
returns that saved commit as a local branch. [Retention settings](https://docs.shardflux.dev/limits.md#cloud-agent-retention) describe its lifetime.

## Stay reachable while waiting

Waiting Claude agents keep their Remote Control conversation reachable from claude.ai and the Claude mobile app
for 30 minutes by default. A reply on the agent's connection wakes its parked workspace (CLI 0.13.2+,
TypeScript SDK 0.18.0+, Python 0.14.0+, MCP 0.12.0+). The session title starts with `[SF] `.

The reachability window is separate from the idle grace: grace controls when waiting work can park, and
`agent_reachable_seconds` controls how long a parked waiting agent can wake on reply traffic.
See [reachability settings and billing](https://docs.shardflux.dev/limits.md#cloud-agent-reachability).