Group workspaces into higher-level folders

[olfway]

It would be useful to have an optional higher-level grouping mechanism for workspaces.

The current hierarchy is:

Workspace → Session

For larger setups, I would like to organize them as:

Folder → Workspace → Session

My main use case is working with several monorepo-based projects. Each project may contain multiple related workspaces, and each workspace may contain several sessions. With only the current two-level hierarchy, the workspace list becomes difficult to navigate because workspaces belonging to different projects are mixed together.

For example:

• Project A
  • Frontend workspace
  • Backend workspace
  • Infrastructure workspace
• Project B
  • Application workspace
  • Services workspace
  • Documentation workspace

Ideally, folders could be collapsible in the sidebar and workspaces could be assigned to, moved between, or left outside a folder. The feature could remain entirely optional so the existing workflow would not change for users who do not need another hierarchy level.

This would make agterm easier to use when managing multiple large projects, monorepos, or collections of related repositories.

[umputun]

going to pass on the folder level, but the container you're describing mostly exists already, it's called a window.

a window is a named bundle of workspaces and sessions with its own sidebar, so Project A and Project B become two windows, each showing only its own workspaces. They're persisted and reopen at the next launch with their frames. It's all in the Window menu: New Window (⌘⌥N), Rename Window… to name it, Open Window to switch. Or from a script if you'd rather set the whole thing up at once:

agtermctl window new "Project A"
agtermctl window new "Project B"
agtermctl window list

the reason I don't want an extra level in the tree is the model rather than the effort. Workspaces are peers, and a workspace holds the sessions for one project or context, so nesting them under a named parent pushes a convention that isn't universal (plenty of people, me included, don't organize workspaces to mirror a project layout). Same call as #259 and #265. "It stays optional" doesn't move me much on its own either, I closed an opt-in, default-off affordance in #248 because it's still one more flag and one more code path for something I'd keep off.

windows aren't a free substitute though, and it's worth being straight about what they cost:

• closing a project window kills its shells. Reopening re-spawns fresh ones in the saved directories, it doesn't reattach, so "put project B away for now" isn't as cheap as collapsing a row would be.
• no moving sessions or workspaces between windows. That's a deliberate 1:1 invariant, so reorganizing across projects means recreating.
• Ctrl-Tab, ⌃P, attention-nav and auto-follow are per-window, so two windows split those too.

so pls try one window per project. If something specifically falls short after that, tell me what it is.

[olfway]

Unfortunately, separate windows do not fit my workflow very well. I was specifically trying to avoid managing five or more project windows across different desktops and would prefer to keep everything inside a single window.

After thinking about it further, I realized that I may not actually need all sessions to remain running. A more useful model for me could be “lazy” or persistent session entries: a session could be stopped without disappearing from the sidebar, and then started again later in its saved directory and configuration.

I understand that this may also conflict with agterm’s current model, especially if sessions are intended to represent active shells rather than saved launch configurations. Without something like that, I agree that adding a third grouping level becomes less compelling, since collapsed groups would still contain many continuously running sessions.

[umputun]

stepping back from the specific ask, because I think the framing is the problem here.

agterm deliberately keeps the tree model small and puts the flexibility somewhere else: 65 commands on the control socket that drive every part of the app, plus custom commands in keymap.conf that run any shell line and show up both on a keyboard shortcut and in the action palette (⌃⇧P). So a workflow that isn't in the model is not a feature request, it's a script. That's why I keep saying no to new tree levels, not because folders are hard, but because the answer to "I organize my work like X" is meant to be a few lines of shell, not another node type everyone else carries.

so, your case. It splits in two: showing only one project's workspaces at a time, and putting a project away without losing where its sessions were. Both work today. The first is already in the sidebar, the second is a short script over the socket.

the grouping half already exists in pieces. A click anywhere on a workspace row folds or unfolds it, not just the triangle. View ▸ Collapse Workspaces (sidebar collapse) folds everything except the one you're in, and Expand Workspaces (sidebar expand) opens them all back. workspace focus goes further and shows a single workspace, scoping session navigation to it. The flagged view (session flag + sidebar mode flagged) is the other angle: a flat list of just the sessions you're on right now, cutting across workspaces.

what those don't do is "keep project A's three workspaces open and fold the rest", since the built-in collapse keeps exactly one. That's where a script starts paying. Name workspaces A / frontend, A / backend so they sort together and match on a prefix, then:

#!/bin/sh
# agt-only.sh "A" - expand A's workspaces in the sidebar, collapse the rest
p=$1
agtermctl tree --json |
  jq -r --arg p "$p" '.result.tree.workspaces[]
    | "\(if (.name|startswith($p)) then "expand" else "collapse" end) \(.id)"' |
  while read -r act w; do agtermctl workspace "$act" --target "$w"; done

one entry per project in the palette and the sidebar reshapes itself around whatever you're on. That alone may be enough, without closing anything.

this is just one way to write it. Prefix matching is what I picked for the example, you might key off a file listing the workspace names per project, off the session cwd, off a flag, whatever fits how you actually think about your projects. The commands are the same either way.

the park-and-resume half is the script. I'd rather not turn a session into both a live shell and a saved launch config in the model, but you get the same behavior from outside it: tree --json reports every session's name, cwd and foreground (the live argv), and session new takes --cwd, --name, --command, --workspace, --no-select. Park is snapshot plus close, resume is replay.

#!/bin/sh
# agt-park.sh "A" - snapshot every workspace whose name starts with A, then close them
p=$1; mkdir -p ~/.agterm-projects
t=$(agtermctl tree --json)
printf '%s' "$t" | jq --arg p "$p" '[.result.tree.workspaces[] | select(.name|startswith($p))
  | {name, sessions: [.sessions[] | {name, cwd, cmd: (.foreground // [] | map(@sh) | join(" "))}]}]' \
  > ~/.agterm-projects/"$p".json
printf '%s' "$t" | jq -r --arg p "$p" '.result.tree.workspaces[] | select(.name|startswith($p)) | .id' |
  while read -r w; do agtermctl workspace delete --target "$w"; done

#!/bin/sh
# agt-resume.sh "A" - recreate the parked workspaces and their sessions
p=$1
jq -c '.[]' ~/.agterm-projects/"$p".json | while read -r w; do
  ws=$(agtermctl workspace new "$(printf '%s' "$w" | jq -r .name)" --collapsed --json | jq -r .result.id)
  printf '%s' "$w" | jq -c '.sessions[]' | while read -r s; do
    cmd=$(printf '%s' "$s" | jq -r .cmd)
    set -- --workspace "$ws" --no-select --cwd "$(printf '%s' "$s" | jq -r .cwd)" \
           --name "$(printf '%s' "$s" | jq -r .name)"
    [ -n "$cmd" ] && set -- "$@" --command "$cmd"
    agtermctl session new "$@"
  done
done

the captured argv is absolute (/opt/homebrew/bin/nvim, not nvim), so --command runs it without a zsh -lc wrapper. And the snapshot is a plain json file, so you can hand-edit it into the launch config you actually want instead of whatever happened to be running when you parked. That is your persistent session entry, it just lives in a file instead of the sidebar.

then wire them up in ~/.config/agterm/keymap.conf:

command "park A"    ctrl+alt+1  ~/bin/agt-park.sh "A"
command "resume A"  ctrl+alt+2  ~/bin/agt-resume.sh "A"
command "park B"                ~/bin/agt-park.sh "B"
command "resume B"              ~/bin/agt-resume.sh "B"

with a chord it's a keystroke. Without one the entry is palette-only, which scales past two or three projects better than keys do: ⌃⇧P, type the project name, enter. Custom commands appear there marked custom alongside the built-ins, and the script runs in the focused session's directory with $AGT_SESSION_PWD, $AGT_SELECTION and friends in its environment. Reload with File ▸ Reload Keymap or agtermctl keymap reload.

and you don't have to write any of this by hand. Install the agent skill from Help ▸ Install Agent Skill… (plus Install Command Line Tool… so agtermctl is on PATH). It teaches Claude Code or Codex the whole model and every one of the 65 commands with their flags and return shapes, so you describe the flow you want in plain English inside an agterm session and the agent writes the scripts and the keymap lines for you. Most of what people ask for as a feature is 20 lines of shell an agent can produce in a minute.

worth sanity-checking the premise first though. Rendering is demand-driven, so an idle session draws nothing and an idle shell is a few MB. 30 idle shells across five projects is not a real cost. If what actually bothers you is dev servers, agents and watchers piling up, then those are what you want parked, and killing them is the point rather than a side effect.

two caveats on the scripts: workspace delete keeps at least one workspace per window, so parking literally everything leaves one behind, and a resumed session is a fresh shell with no scrollback.

[umputun]

one more angle, since your objection to windows was managing five of them across desktops rather than windows themselves.

nothing says they have to sit in five different places, and you don't have to place them by hand either. A script reads the frame of the window you're in and pushes it onto all the others, so they stack exactly. From then on raising one looks like switching a tab, not moving between windows: same size, same position, one spot on one desktop, each window still carrying its own workspace tree, sessions and sidebar. I tried it on a scratch instance before writing this up, three windows on an identical frame, and cycling through them is indistinguishable from one window changing contents.

the obvious question is why stack them instead of just hiding the ones you're not using, and the answer is that half the API is missing. window select already raises a window and un-minimizes it if it was in the Dock, so the show leg is there, but there is no command to minimize or hide one, and window move clamps the origin to keep a grabbable strip on the display, so you can't park a window off-screen either. That's my oversight, not a design position. I'll add the hide leg, with the matching flag on window list so a script can read the state back. After that these scripts get simpler and more honest: minimize the ones you're not on instead of leaning on the front window covering them.

until then, stacking gets you the same result, because a raised window covers identical frames behind it exactly.

the aligning script, run once and again whenever you resize:

#!/bin/sh
# agt-stack.sh - give every window the active window's frame so they overlap exactly
set -- $(agtermctl window list --json |
  jq -r '.result.windows[] | select(.active) | .geometry | "\(.x) \(.y) \(.width) \(.height) \(.display)"')
front=$(agtermctl window list --json | jq -r '.result.windows[] | select(.active) | .id')
agtermctl window list --json | jq -r '.result.windows[].id' | while read -r id; do
  agtermctl window select "$id" >/dev/null   # a window that was never raised has no frame yet
  agtermctl window resize "$id" --width "$3" --height "$4"
  agtermctl window move "$id" --x "$1" --y "$2" --display "$5"
done
agtermctl window select "$front" >/dev/null

switching, per project:

#!/bin/sh
# agt-win.sh "Project A" - raise the window with that name
agtermctl window list --json | jq -r --arg n "$1" '.result.windows[] | select(.name==$n) | .id' |
  while read -r id; do agtermctl window select "$id"; done

that second one is optional. Window ▸ Open Window already lists every window by name with a checkmark on the open ones, and ⌘` cycles them, so once the frames match you have a project switcher without writing anything. The script only buys you a named palette entry and a dedicated chord per project.

window select also opens a window that was closed, so a project you shut down earlier comes back on the same frame from the same command.

one wrinkle I hit while testing: a window created by window new reports no geometry and refuses resize/move until it has been raised once, which is why the aligning script selects each window before positioning it.

[umputun]

the hide leg is in, merged in #294 and released in v0.17.1.

agtermctl window minimize <id> [on|off|toggle]   # default toggle
agtermctl window new "Project A" --minimized     # create it already parked
agtermctl window list --json                     # reads back as `minimized`

so the stacking advice above is obsolete, and for exactly the reason I gave when I wrote it: you no longer have to lean on the front window covering identical frames. Park the ones you're not on instead.

#!/bin/sh
# agt-win.sh "Project A" - park every other window in the Dock, then raise that one
n=$1
t=$(agtermctl window list --json)
printf '%s' "$t" | jq -r --arg n "$n" '.result.windows[] | select(.name != $n) | .id' |
  while read -r id; do agtermctl window minimize "$id" on; done
printf '%s' "$t" | jq -r --arg n "$n" '.result.windows[] | select(.name == $n) | .id' |
  while read -r id; do agtermctl window select "$id"; done

one entry per project in the palette, or a chord each in keymap.conf, same as before. window select deminiaturizes, so a project you parked last week comes back from the Dock with that same command, and it still opens a window you had closed entirely.

a minimized window keeps reporting its geometry, so agt-stack.sh is still worth running once if you want them all on one spot when raised. It just isn't doing the hiding job anymore.

the wrinkle I hit while testing that script is gone too. window new used to report no geometry and refuse resize/move until the window had been raised once, which is why it selected each window before positioning it. That's fixed in #294, so the select line isn't needed.

one limit: minimize is rejected on a window in native full screen. AppKit no-ops miniaturize there, so replying ok would be a lie.

none of this changes the folder answer, and park-and-resume is still the script from my previous message. What it does cover is the objection you actually raised, managing five project windows across desktops. Four of them sit in the Dock now and one palette entry swaps which.

[olfway]

Thanks for the detailed explanations and for putting together all these examples.

I’m going to try the park / resume workflow for managing my projects. I actually like the idea of pre-generating the required workspaces and sessions, then opening them from the command palette. The window-based approach also looks useful for separating work and personal projects while still keeping the experience close to having a single window open.

By the way, a small repository with scripts like these might be useful as a collection of practical recipes showing what can be done with agtermctl, as well as a source of ideas and inspiration for people building their own workflows.

[umputun]

the sidebar half of this is in v0.18.0 (#297), so the gap I named above is gone.

I said the built-in collapse keeps exactly one workspace, and that "keep project A's three workspaces open and fold the rest" is where a script starts paying. The focus filter now marks a set instead of a single workspace, so that part is built in. Right-click a workspace row and pick Add to Focus for each one you want, then the grid button in the sidebar's bottom bar shows only those. Focus on the same menu is unchanged, it still replaces the set with that one workspace.

two things it does that the collapse script didn't:

• non-members are hidden, not folded. The tree is the project you're on, instead of that project plus twelve collapsed rows.
• session navigation follows. While the filter is applied, session go, Ctrl-Tab, attention-nav and the ⌃P palette are scoped to the marked workspaces' sessions.

the set and the filter flag are independent, which is the part that matters for your case. Turning the filter off keeps the marks, so peeking at the whole tree and coming back is one toggle each way rather than a rebuilt selection. That toggle is the same bottom-bar button, View ▸ Toggle Workspace Filter, or the toggle_workspace_filter keymap action, which ships keyless so bind a chord or run it from ⌃⇧P.

over the socket:

agtermctl workspace focus add --target <ws>   # mark it, filter flag untouched
agtermctl workspace filter on|off|toggle      # apply or suspend, marked set untouched

add never switches the filter on, because a mark that narrowed the tree would hide the rows you still have to mark. Mark several, apply once.

so agt-only.sh from my earlier message collapses to this, same prefix convention (A / frontend, A / backend):

#!/bin/sh
# agt-only.sh "A" - show only the workspaces whose name starts with A
p=$1
agtermctl workspace filter off       # unmark with the whole tree still on screen
agtermctl tree --json |
  jq -r --arg p "$p" '.result.tree.workspaces[]
    | "\(if (.name|startswith($p)) then "add" else "off" end) \(.id)"' |
  while read -r mode w; do agtermctl workspace focus "$mode" --target "$w"; done
agtermctl workspace filter on

one entry per project in the palette, same as before. Read-back is per workspace as focused on the tree node, plus the top-level workspaceFilter for the flag, reported independently, so a script can record a working set and put it back exactly as it was.

three things worth knowing:

• filter on with nothing marked is refused. It returns ok having changed nothing, so an applied filter always has at least one visible member.
• selecting a session outside the set suspends the filter and keeps the set, so jumping out and back costs one filter on.
• it's per-window and persisted, and orthogonal to sidebar mode. The flagged view is a flat session list and ignores the filter entirely.

none of this is the folder level, it's still a flat set with no parent node, and park-and-resume is still the script from before. What it does cover is the "show me only this project" half, with no script at all if you don't mind clicking the rows.

[umputun]

the collection suggested above now exists, under cookbook/. Seven recipes, each a directory with a README (what it does, requirements, setup, usage, how it works, limits) and its scripts. The three from this thread are in there: project-switcher, park-and-resume, window-per-project. cookbook/CONTRIBUTING.md covers submitting your own.

the scripts I posted above have four bugs. Use the cookbook versions, not the ones in this thread. Reviewing them properly before shipping them turned these up:

• agt-park.sh with no argument deleted every workspace in the window. startswith("") matches everything, so a bare run snapshotted the lot and then deleted it. Guarded now.
• agt-park.sh overwrote a good snapshot with [] when nothing matched. jq returns an empty array with exit 0, so the mv ran anyway. Park twice, or park with a different window frontmost, and the only record of the layout was gone, silently, after the shells had already been killed. It now refuses to publish an empty snapshot and exits non-zero before deleting anything.
• agt-win.sh errored on every closed window. window minimize rejects those with window not open — window.select it first. Fixed with a .open filter, kept off the target lookup since window select opens a closed window on purpose.
• agt-win.sh with a name matching nothing parked every window and raised none. The target id resolves first now and a miss exits before anything is minimized.

one more that was wrong in my explanation rather than the code: I said the captured argv comes back absolute, so --command could run it directly. It does not. parseProcArgs skips the executable path and returns argv as typed, so nvim comes back as nvim, and the replay shell reads no profile and gets the GUI PATH without the Homebrew prefix. Resuming anything Homebrew-installed died with exit 127 and the session closed immediately. The cookbook version wraps the replay in zsh -lc.

the snapshot also holds full argv for everything that was running, which can include a token or a password passed on a command line, so it now writes with umask 077.

none of this changes the answer about folders. What it does change is that "it's a script" is only a good answer if the script is somewhere findable and someone has actually checked it.