Interactive dev sessions

Every session you’ve seen so far starts because an agent picked up a task. A dev session is different: you create it yourself, whenever you want, with no task behind it. It’s a live git worktree and terminal pinned to one of your devices, for work you want to drive directly — trying something out, running a one-off command, or poking at a branch without filing a task first.

A dev session belongs to the person who created it. It doesn’t move through a workflow, doesn’t have stages, and never shows up on a task’s Workflow panel — it’s just yours to use until you stop or archive it.

Creating, stopping, and archiving a dev session all require owner or admin access in the workspace. Resuming is more permissive: the member who created the session can resume it, and so can any workspace owner or admin.

Creating a dev session

Web app: Open Sessions in the sidebar and click New session. The form asks for:

Field	Required?	What it does
Agent template	Yes	Which agent template’s launch config runs in the session.
Device	Yes	Which device provisions the worktree and runs the session.
Repo	No	The repository to check out into the worktree.
Base ref	No	The git ref to cut the worktree from. Defaults to the repo’s default branch.
Branch	No	The branch name for the worktree. Defaults to a generated name if left blank.
Title	No	A friendly label so you can find the session later.

Click Create dev session to submit. Once the worktree is ready, you’re dropped straight into the session’s live terminal.

Leave Repo blank and CodeHerder picks one for you the same way it would for a task’s build session: the workspace’s default repo if you’ve set one, otherwise its sole active repository — see Which repository a task builds in in Connecting repositories.

CLI:

ch dev-session create --agent <agentId> --device <deviceId> \
  [--repo <repoId>] [--base-ref <ref>] [--branch <branch>] [--title <title>]

--agent and --device are required; the rest are optional and match the web form fields above.

Unlike the web form, this doesn’t drop you into a terminal — the session goes through provision and lands ready, with no terminal running yet. Run ch dev-session resume <dev-sessionId> to bring it active, then ch dev-session attach <dev-sessionId> to connect — see Lifecycle and Dropping into a session below.

Finding your dev sessions

The Sessions list is the one place to find every session, task-driven or not. Each row’s Type column shows dev for a dev session, so you can tell them apart from task sessions at a glance — and its Working on cell shows the session’s owner instead of a task. Use the Live only and Include closed filters to widen or narrow what’s shown, same as for task sessions.

CLI:

ch dev-session list
ch dev-session show <dev-sessionId>

Dropping into a session

A live dev session row shows a ▶ Drop in button that opens the same live-terminal page task sessions use — see Following a live agent session for how the terminal, the Send box, and the audit trail work; those rules apply here unchanged.

CLI:

ch dev-session attach <dev-sessionId>

Run attach from a Unix machine (macOS or Linux) with an interactive terminal — it’s not supported from Windows or from a script/pipe. Once connected, press Ctrl-] to detach without stopping the session; Ctrl-C is forwarded to the remote process as a keystroke rather than detaching you.

If the session doesn’t have a live terminal yet — it’s ready but never started, or it’s stopped — attach fails and tells you to resume it first. Bring it active (see Lifecycle below), then attach again.

Lifecycle

A dev session moves through provision → ready → active → stopped → archived. A stopped session isn’t gone — you can bring it back to active, or archive it for good:

• provision — the worktree is being set up on the device.
• ready — the worktree is provisioned, but no terminal is running yet. Use Start (web) or ch dev-session resume (CLI) below to bring it active.
• active — the session has a live terminal you can drop into.
• stopped — the running process has been halted, but the session record and its worktree metadata are kept, so you can bring it back later. A session doesn’t only stop because you clicked Stop — see Automatic lifecycle below.
• archived — the session is retired for good; it can’t be brought back.

Stop halts the running process. In the web app, click Stop on an active session’s row and confirm. On the CLI:

ch dev-session stop <dev-sessionId>

Start / Resume bring a session active — from ready the first time, or from stopped to pick back up — same worktree, branch, and device either way. In the web app, click Start on a ready row or Resume on a stopped row; either brings the session active and the ▶ Drop in button appears. On the CLI, one command handles both:

ch dev-session resume <dev-sessionId>

The session’s device must be Online for this to succeed. Bringing a stopped session back also re-arms automatic resume — see below. An archived session can’t be brought back — archiving is permanent.

Archive retires the session permanently. In the web app, click Archive and confirm. On the CLI:

ch dev-session archive <dev-sessionId>

Automatic lifecycle

Beyond the stop/resume you trigger by hand, CodeHerder also moves a dev session between active and stopped on its own, in two situations:

• Your device reboots or reconnects. If a dev session is active on a device and the device restarts — or otherwise drops and re-establishes its connection — the session automatically comes back to active once the device is Online again. You don’t need to resume it yourself.
• The session sits idle. If a dev session is left active with no activity for a long stretch — about two weeks by default — CodeHerder automatically stops it to free up that device for other work. This idle-parking is non-destructive: your worktree, branch, and terminal history are all kept exactly as they were, and the session shows up as stopped, ready to bring back with Resume whenever you want it.

One invariant governs all of this: stopping a session, whether you do it yourself or CodeHerder does it for being idle, turns off automatic resume for that session. A session you (or idle-parking) stopped stays stopped — it will not come back on its own the next time its device reconnects. Resuming a session — by hand, or automatically after a reboot — re-arms automatic resume, so it can come back on its own again the next time it’s needed.

Related guides

• Following a live agent session — the live-terminal page, the Send box, and what gets recorded in the audit trail
• Managing your devices — pick and prepare the device a dev session runs on
• Agents and the CLI — agent templates, launch configs, and the ch command-line tool