desk ps

List running agents managed by Desk on the current machine. Add -A or --all to include saved history and discovered unmanaged Claude, Codex, Qoder, and Bob processes.

Availability

The running-only default, native process discovery, full directory paths with --no-trunc, and the --all and --runtime=native options are available in Desk 0.2.5 and later. Earlier versions list all saved Desk records by default and do not discover unmanaged processes.

# Running agents managed by Desk.
desk ps

# All managed records and discovered unmanaged processes.
desk ps -A

# Full directory paths and full IDs.
desk ps --no-trunc
desk ps -A --no-trunc

With -A, live processes appear first, ordered by PID. Saved records that have not been matched to a live process follow, newest first, including packed sources and exited targets. For example:

AGENT ID       AGENT    RUNTIME   MANAGED   STATUS    PID    PACK ID        DIRECTORY
-              claude   native    no        running   4120   -              my-project
8af321bd9750   codex    native    yes       running   4188   37d823aa9021   api
37d823aa9021   claude   native    yes       packed    -      37d823aa9021   api

Managed and unmanaged agents

A managed agent has a record in the active Desk store, created by an operation such as packing a source or moving to a target. A live process is linked to that record only when its harness and process identity match.

An unmanaged agent is a discovered harness process without a verified link to a Desk record. Starting a harness directly, including resuming a conversation from a previous move, does not automatically register its new process with Desk. It appears only with -A, with MANAGED set to no and no Desk or pack ID.

The default view requires both a verified managed process and an observed running state. Stopped processes and prepared, starting, packed, exited, failed, or unverified saved records are shown only with -A. An empty default table means no verified running managed agents were found.

Columns

Column	Meaning
AGENT ID	First 12 characters of the Desk management-record ID; - for a discovered process without a verified record match.
AGENT	Harness type.
RUNTIME	Execution runtime; currently native.
MANAGED	yes for a saved Desk record or verified live match; no for an unmanaged process.
STATUS	Observed process state or saved lifecycle state.
PID	Observed process ID for a live row, or recorded process ID for a history row; - when none was recorded.
PACK ID	Associated source pack ID, shortened to 12 characters; - when no pack is associated.
DIRECTORY	Working directory basename, or full path with --no-trunc; - when unavailable.

--no-trunc shows full agent IDs, pack IDs, and directory paths for both live processes and saved records. For example, my-project becomes /home/dev/projects/my-project. It preserves spaces and replaces terminal control characters so each entry stays on one row. It does not change which agents are listed.

move --resume accepts unique agent-ID prefixes for retained entries that are still prepared. A discovered PID is not a Desk agent ID and cannot be passed to move --resume.

Native process discovery

Desk inspects processes owned by the current user. On Linux and WSL it inspects /proc in the current PID namespace. On macOS it uses native process metadata; the system’s lsof supplies working directories when available. No vendor CLI is launched, and process arguments and environment values are not displayed or saved. Inaccessible processes may be omitted, and a process can exit immediately after discovery.

Common executable names and interpreter launchers are recognized. A launcher waiting for a recognized child of the same harness is consolidated into the child’s row. Arbitrarily renamed binaries or custom wrappers may not be recognized. running means the process is present, including when waiting for input; stopped means the operating system has suspended it. Neither state establishes whether the harness is authenticated or ready to accept work.

New Desk launches record a process start identity. A matching PID, start identity, and harness allow the live process and its saved record to share one row. An npm or shell launcher can also supply that match. Older records without a start identity remain separate and require -A because a PID alone can be reused.

Discovery does not register processes, update saved records, or control their lifecycle. Container and microVM discovery, and remote machine inspection, are not implemented. --runtime currently accepts only native.

Saved lifecycle states

A packed source has status packed. A target normally passes through prepared, starting and running, then ends in exited or failed.

For unmatched saved running records, Desk checks the recorded PID. It can display running (PID present), exited (unobserved), or unknown. A different observed start identity produces exited (PID reused). PID presence alone cannot establish that an older record still refers to the original process.

The command accepts no positional arguments. The store defaults to ~/.desk/store. Set DESK_HOME to use $DESK_HOME/store; this selects saved Desk records without changing which local user processes are inspected.