What problem does this solve?
I've been building a phone dashboard that mirrors the Supacode tree, so I can
check on sessions and answer prompts without walking back to the Mac. For that I
need to know, per worktree, what tabs exist, what they're called, which surface
belongs to which tab, and which pid the agent runs under. The pid is the one
that matters most: it's what lets me join a Supacode window to a Claude Code
session via ~/.claude/sessions/<pid>.json.
tab list and surface list both work, but they return bare UUIDs:
$ supacode tab list --worktree "$WT"
E8F2AF33-7079-4118-9BD7-F49C955401C6
3EC4BF85-44F7-49A8-8521-CF558083DC48
$ supacode surface list --tab E8F2AF33-7079-4118-9BD7-F49C955401C6
3579CBDF-E286-4462-802A-9A2E88506E00
No titles, no agent pid, and nothing saying which tab an agent is actually
running in. So I parse ~/.supacode/layouts.json instead, walking the nested
split layout for leaf surfaces and pulling agents[0].pids[0] off each one. It
works and it's fast. It's also about 90 lines I'd rather not own, since it's
your internal state and it can change shape in any release without that being a
bug on your side.
Proposed solution
A --json flag on tab list returning what the app already knows:
[
{
"id": "E8F2AF33-...",
"title": "fix login redirect",
"index": 0,
"surfaces": [
{ "id": "3579CBDF-...", "agent": "claude", "pid": 41293 }
]
}
]Title, surface ids, and agent pid are the three I need. Anything else is a
bonus. surface list --json with the same per surface shape would work just as
well if you'd rather not nest.
Alternatives considered
Parsing ~/.supacode/layouts.json, which is what I do today. Accurate, fast,
and it keeps working with the app closed, which the CLI doesn't. The only
problem is that it's private state.
Walking the process tree from the Claude pid up to the owning zmx session also
works. It resolved 17 of 18 windows for me where the layouts.json pid join
resolved 18 of 18, so I dropped it.
I did wonder whether you'd rather not commit to a stable shape here at all. If
that's the case, saying so in the docs would still help. I'd know I'm on my own
rather than waiting for something that isn't coming.
Supacode version
0.10.8 (build 1785775286), macOS 26.6.1
Are you planning to build this yourself?
Before submitting
What problem does this solve?
I've been building a phone dashboard that mirrors the Supacode tree, so I can
check on sessions and answer prompts without walking back to the Mac. For that I
need to know, per worktree, what tabs exist, what they're called, which surface
belongs to which tab, and which pid the agent runs under. The pid is the one
that matters most: it's what lets me join a Supacode window to a Claude Code
session via
~/.claude/sessions/<pid>.json.tab listandsurface listboth work, but they return bare UUIDs:No titles, no agent pid, and nothing saying which tab an agent is actually
running in. So I parse
~/.supacode/layouts.jsoninstead, walking the nestedsplit layout for leaf surfaces and pulling
agents[0].pids[0]off each one. Itworks and it's fast. It's also about 90 lines I'd rather not own, since it's
your internal state and it can change shape in any release without that being a
bug on your side.
Proposed solution
A
--jsonflag ontab listreturning what the app already knows:[ { "id": "E8F2AF33-...", "title": "fix login redirect", "index": 0, "surfaces": [ { "id": "3579CBDF-...", "agent": "claude", "pid": 41293 } ] } ]Title, surface ids, and agent pid are the three I need. Anything else is a
bonus.
surface list --jsonwith the same per surface shape would work just aswell if you'd rather not nest.
Alternatives considered
Parsing
~/.supacode/layouts.json, which is what I do today. Accurate, fast,and it keeps working with the app closed, which the CLI doesn't. The only
problem is that it's private state.
Walking the process tree from the Claude pid up to the owning zmx session also
works. It resolved 17 of 18 windows for me where the layouts.json pid join
resolved 18 of 18, so I dropped it.
I did wonder whether you'd rather not commit to a stable shape here at all. If
that's the case, saying so in the docs would still help. I'd know I'm on my own
rather than waiting for something that isn't coming.
Supacode version
0.10.8 (build 1785775286), macOS 26.6.1
Are you planning to build this yourself?
ready.Before submitting
ready.