# How to List Background Sessions in OpenClaude: Using the Built-in `ps` Command

> Easily list background OpenClaude sessions using the claude ps command. View IDs, types, start times, and statuses. Filter by status and details for efficient session management.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Use the `claude ps` command to display all active background sessions, including their IDs, types, start times, and current statuses, with optional filtering via the `--status` and `--details` flags.**

OpenClaude supports executing long-running operations such as validation jobs, local agents, and tool operations in the background. To monitor these asynchronous tasks, you can list background sessions in OpenClaude through the CLI's integrated task management system. The `ps` command queries the internal registry and formats the output to match the familiar Unix process status utility.

## Using the `ps` Command to List Sessions

The `ps` command is registered in the command catalog under the **session** category within [`web/src/data/commands.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/commands.ts). When invoked, it calls the task-summary helper defined in [`src/utils/taskSummary.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskSummary.ts), which aggregates data from the background-task registry and renders a formatted table.

Run the following to view all background sessions:

```bash
claude ps

```

The output displays a table with the following columns:

- **ID**: The unique session identifier
- **Type**: The session category (e.g., `tool-background-validation`, `agent-local-agent`)
- **Started At**: The timestamp when the session began
- **Status**: The current state (`running`, `completed`, or `failed`)

Example output:

```bash
$ claude ps
┌─────┬──────────────────────────┬─────────────┬───────────┐
│ ID  │ Type                     │ Started At  │ Status    │
├─────┼──────────────────────────┼─────────────┼───────────┤
│ 12  │ tool-background-validation │ 2024-09-06 12:34 │ running   │
│ 13  │ agent-local-agent        │ 2024-09-06 12:35 │ completed │
└─────┴──────────────────────────┴─────────────┴───────────┘

```

## Filtering and Inspecting Sessions

The `ps` command supports flags to narrow results or retrieve detailed metadata for specific sessions.

### Filter by Status

To display only sessions matching a specific state, use the `--status` flag. This filters the output based on the status field tracked in the task registry.

```bash
claude ps --status running

```

### View Detailed Session Information

To inspect a specific session's metadata, including output logs and detailed progress, append the `--details` flag followed by the session ID.

```bash
claude ps --details 12

```

This renders extended information such as:

```bash
Session ID: 12
Type: tool-background-validation
Started: 2024-09-06 12:34
Status: running
Output: /tmp/claude-bg-12.log

```

## Implementation Architecture

The background session listing functionality relies on a coordinated pipeline across several source files. In [`web/src/data/commands.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/commands.ts), the command parser registers the `ps` instruction and routes it to the task manager.

The [`src/utils/taskSummary.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskSummary.ts) module collects session data by polling the background-task registry. Status updates are managed by [`src/utils/taskReport.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskReport.ts), which writes state changes that [`taskSummary.ts`](https://github.com/Gitlawb/openclaude/blob/main/taskSummary.ts) subsequently reads. Real-time progress events are emitted through [`src/utils/task/sdkProgress.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/task/sdkProgress.ts), ensuring the **Status** column reflects the latest activity.

## Summary

- Execute `claude ps` to list all background sessions in OpenClaude with their IDs, types, timestamps, and statuses.
- Use `claude ps --status <state>` to filter results for specific states like `running` or `completed`.
- Use `claude ps --details <id>` to inspect log paths and metadata for individual sessions.
- The command is registered in [`web/src/data/commands.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/commands.ts) and aggregates data via [`src/utils/taskSummary.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskSummary.ts).

## Frequently Asked Questions

### What is the equivalent of Unix `ps` in OpenClaude?

The `claude ps` command serves as the direct equivalent to the Unix `ps` utility, but operates on OpenClaude's internal background-task subsystem rather than operating system processes. It displays sessions managed by the OpenClaude task registry, including agents and validation jobs.

### How do I check if a background task is still running?

Run `claude ps --status running` to filter the output and display only sessions with a `running` status. This queries the live task registry maintained by [`src/utils/taskReport.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskReport.ts) and shows currently active operations.

### Where does OpenClaude store background session information?

Session metadata is maintained in-memory by the background-task registry and exposed through the [`src/utils/taskSummary.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskSummary.ts) utility. Progress events are tracked in [`src/utils/task/sdk_progress.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/task/sdk_progress.ts), while status updates are handled by [`src/utils/taskReport.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/taskReport.ts).

### Can I terminate a session directly from the `ps` list?

The `ps` command is read-only and designed for monitoring. To terminate a background session, you must use the specific kill or stop command for that session type, as the `ps` implementation in [`web/src/data/commands.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/commands.ts) does not register termination handlers.