Feature request: Session grouping (parent/child) for agent-spawned workers

[dbmcco]

Use case

I'm using freshell as the terminal orchestration layer for an agentic system where a "manager" agent (Derek) spawns multiple Claude Code worker sessions per task. A typical workflow looks like:

1. Derek gets a task ("implement feature X")
2. Derek spawns 3-8 Claude Code sessions via POST /api/tabs to work on subtasks
3. Workers complete, Derek reads results via capture-pane

Right now all sessions (mine + workers) show as flat siblings in the sidebar. With ~3,500 sessions, it's hard to find my interactive sessions vs agent-spawned workers.

Current workaround

excludeFirstChatSubstrings hides known worker patterns, which helps for filtering. But I'd also like to see workers when I want to — grouped under their parent session.

Proposed approach

1. Session metadata on tab creation

When creating a tab via the agent API, allow passing grouping metadata:

POST /api/tabs
{
  "name": "worker-auth-module",
  "mode": "claude",
  "cwd": "/path/to/project",
  "group": "task-123",
  "parentSessionId": "abc-def-456"
}

Store group and/or parentSessionId in the session index entry.

2. Sidebar grouping

When sessions share a group value:

• Show the parent (or first session) as the header
• Collapse child sessions underneath with a count badge
• Click to expand/collapse
• Default collapsed

Alternative: env-var based tagging

If modifying the API feels heavy, an env var like FRESHELL_SESSION_GROUP=task-123 set on the spawned process would also work — the session indexer could pick it up from the terminal's environment.

Context

I'm running freshell as a service (port 3550) alongside a multi-agent platform. The agent API (/api/tabs, /api/run, capture-pane, wait-for) is exactly what we needed for programmatic terminal control. Session grouping would make the UI usable for agent-heavy workflows.

Happy to contribute a PR if you're open to this direction.