What defines an orphan?

An orphan is a session whose PID is dead or whose last heartbeat is older than 5 minutes with a dead process.

How do I clean orphans?

Use the clean argument to force-clean orphaned sessions; it runs without prompts.

What output formats are produced?

Printed text blocks summarize Active Sessions and Orphaned Sessions in a layout similar to the sample.

Sessions

Scanned

npx machina-cli add skill Speedy0000007/claude-tandem/sessions --openclaw

Files (1)

SKILL.md

1.6 KB

Tandem Sessions

Inspect the session registry at ~/.tandem/sessions/.

Steps

List all session directories under ~/.tandem/sessions/. For each, read state.json and display:
- Session ID
- Project (basename of project path)
- Branch
- Status (active/ended)
- Current task
- Last heartbeat (and how long ago)
- PID (and whether it's still alive: kill -0 $pid)
Group by project to show topology: which sessions share a project.
Identify orphans: sessions where the PID is dead or heartbeat is older than 5 minutes with a dead process. Offer to clean them up (delete the session directory) if found.

Output format

Active Sessions:
  jonnyn-cv (2 sessions)
    abc123  main  "building session topology"  heartbeat: 30s ago  pid: 12345 ✓
    def456  main  "fixing CSS layout"          heartbeat: 2m ago   pid: 12346 ✓

  claude-tandem (1 session)
    ghi789  main  "adding frontmatter schema"  heartbeat: 1m ago   pid: 12347 ✓

Orphaned Sessions:
  jkl012  jonnyn-cv  pid: 99999 ✗ (dead)  last heartbeat: 15m ago
  → Clean up? (delete ~/.tandem/sessions/jkl012/)

Arguments

No arguments: show all sessions
clean: force-clean all orphaned sessions without prompting
<session-id>: show detailed state.json for a specific session

Implementation

Use bash to read ~/.tandem/sessions/*/state.json files. Check PIDs with kill -0. Calculate heartbeat age from the ISO timestamp. No external dependencies beyond jq.

Source

git clone https://github.com/Speedy0000007/claude-tandem/blob/main/plugins/tandem/skills/sessions/SKILL.mdView on GitHub

Overview

This skill lets you see all active Tandem sessions, inspect per-session state details, identify orphaned sessions, and understand which sessions share a project. It reads the session registry at ~/.tandem/sessions, groups results by project, and flags dead PIDs or stale heartbeats.

How This Skill Works

The tool scans ~/.tandem/sessions/*/state.json, extracting fields like Session ID, Project, Branch, Status, Current task, Last heartbeat, and PID. It uses kill -0 to verify if a PID is alive, computes the age of the heartbeat, and flags orphans when the process is dead or the heartbeat is stale (older than 5 minutes). You can run clean to purge orphaned sessions without prompts.

When to Use It

See all active sessions and their topology
Inspect a specific session's state for troubleshooting
Identify and clean orphaned sessions
Understand which sessions share a project to map topology
Review activity across multiple projects

Quick Start

Step 1: Run the skill with no arguments to list all sessions
Step 2: Run the skill with clean to purge orphaned sessions without prompts
Step 3: Run <session-id> to view detailed state.json for that session

Best Practices

Run with no arguments first to list all sessions
Use clean to remove orphans without prompts
Verify liveness of PIDs with kill -0 after listing
Check heartbeat timestamps to assess freshness
Group results by project to understand cross-project activity

Example Use Cases

List all active sessions and view the project topology
Identify an orphan like jkl012 and clean it up
Show details for a specific session abc123
Audit multiple projects to compare activity and health
Use clean to tidy the registry after outages

Frequently Asked Questions

Add this skill to your agents