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

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. When invoked, it calls the task-summary helper defined in 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:

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:

$ 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.

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.

claude ps --details 12

This renders extended information such as:

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, the command parser registers the ps instruction and routes it to the task manager.

The src/utils/taskSummary.ts module collects session data by polling the background-task registry. Status updates are managed by src/utils/taskReport.ts, which writes state changes that taskSummary.ts subsequently reads. Real-time progress events are emitted through 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 and aggregates data via 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 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 utility. Progress events are tracked in src/utils/task/sdk_progress.ts, while status updates are handled by 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 does not register termination handlers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}