Session JSON Format

Session Status File

Each session has a JSON file at ~/.claude-sessions/<tmux-session-name>.json.

Full Schema

{
  "tmux_session": "my-session",
  "status": "working",
  "message": "Implementing login feature",
  "cwd": "/home/user/projects/app",
  "timestamp": 1738972800,
  "current_pbi": "PBI-38",
  "current_pbi_title": "Enhanced GitHub PR Integration",
  "git": {
    "branch": "feature/login",
    "dirty": true,
    "ahead": 3,
    "behind": 0,
    "last_commit": "abc1234 Add login form",
    "remote": "origin",
    "pr_num": 42,
    "fetched_at": 1738972800
  },
  "metrics": {
    "started": 1738970000,
    "total_seconds": 2800,
    "working_seconds": 2400,
    "waiting_seconds": 400,
    "tools": {
      "Read": 15,
      "Write": 8,
      "Bash": 5,
      "Grep": 3
    },
    "recent_tools": ["Read", "Write", "Bash", "Read", "Grep"]
  },
  "tokens": {
    "input": 45000,
    "output": 12000,
    "total": 57000
  },
  "team": {
    "name": "my-project",
    "agents": [
      {
        "name": "researcher",
        "status": "working",
        "timestamp": 1738972800
      },
      {
        "name": "implementer",
        "status": "idle",
        "timestamp": 1738972850
      }
    ]
  },
  "agents": {
    "opencode": {
      "status": "idle",
      "timestamp": 1738972780
    }
  }
}

Required Fields

Field	Type	Description
tmux_session	string	tmux session name (used as unique key)
status	string	Current session status (Claude Code)
message	string	Status message or question
cwd	string	Working directory path
timestamp	int64	Unix timestamp of last status update

Optional Fields

Field	Type	Description
current_pbi	string	Currently active PBI ID (set by session metadata)
current_pbi_title	string	Human-readable PBI title
git	object	Git repository information
metrics	object	Time and tool metrics
tokens	object	Token usage from transcripts
team	object	Claude Code agent team information
agents	object	External agent statuses (OpenCode, etc.)

External Agents

The agents field is a map keyed by agent type:

{
  "agents": {
    "opencode": {
      "status": "working",
      "timestamp": 1738972800
    }
  }
}

Field	Type	Description
agents.<type>.status	string	Agent’s current status
agents.<type>.timestamp	int64	Unix timestamp of last agent update

Both Claude Code hooks (notify.sh) and external agent plugins preserve each other’s fields during read-modify-write operations.

Status Values

See Status Icons for the complete list of valid status values. The same status values apply to all agents (Claude Code, team agents, and external agents).

Composite Status

The TUI computes a composite status across all agents using priority ordering:

permission > waiting > working > error > idle > stopped > done

The highest-priority status across Claude Code and all external agents becomes the session’s display status. See Multi-Agent Support for details.

Task Provider Output

Task providers output JSON to stdout:

{
  "current_pbi_id": "PBI-38",
  "current_pbi_title": "Enhanced GitHub PR Integration",
  "groups": [
    {
      "id": "PBI-38",
      "title": "Enhanced GitHub PR Integration",
      "status": "InProgress",
      "is_current": true,
      "url": "https://github.com/org/repo/milestone/1",
      "tasks": [
        {
          "id": "38-1",
          "title": "PR Detail Data Types",
          "status": "Done",
          "assignee": "alice",
          "labels": ["feature"],
          "priority": 1,
          "url": "https://github.com/org/repo/issues/42",
          "created": "2026-01-01T00:00:00Z",
          "updated": "2026-01-02T00:00:00Z"
        }
      ]
    }
  ]
}

Provider Hint Fields

Field	Type	Description
current_pbi_id	string	Provider’s hint for which PBI is currently active
current_pbi_title	string	Human-readable title for the current PBI
groups[].is_current	bool	Whether this group is the currently active PBI

These fields are used by the PM engine’s current-PBI resolver.