| name | workspace-agents |
| description | Create and manage multi-agent AI workspaces. Auto-trigger when someone needs to set up a new agent team, add/remove agents from an existing workspace, check workspace status, save agent sessions, or recover after a crash. Provides the workspace_agents CLI, directory conventions, and agent configuration format. |
| model | sonnet |
| allowed-tools | Bash(workspace_agents *), Bash(tmux *), Bash(mkdir *), Bash(cat *), Read, Write, Glob |
workspace-for-agents — Workspace Management
Create and manage multi-agent AI teams using directory conventions and tmux sessions.
How it works
A directory tree under working_agents/ defines your team. Each folder level maps to tmux:
working_agents/
01_Reviewer/ → tmux tab "Reviewer"
CLAUDE.md → Persona identity
01_Security/ → tmux pane (column 1)
config.yaml → type: claude
CLAUDE.md → Role instructions
02_CodeQuality/ → tmux pane (column 2)
config.yaml
02_Developer/ → tmux tab "Developer"
...
- Level 1 = Tabs (personas)
- Level 2 = Panes (roles)
- Level 3 = Rows (vertical splits within a pane)
Numeric prefixes control order and are stripped from display names.
Commands
Create a new workspace
Creates the directory tree from the bundled template:
workspace_agents create
Only works if working_agents/ doesn't exist or is empty. Creates all persona folders, role folders, CLAUDE.md files, and config.yaml files.
Start the workspace
Scans the directory tree and builds a tmux session:
workspace_agents open
If the session already exists, attaches to it instead of creating a new one.
Check status
Shows all agents, their types, and whether their panes are alive:
workspace_agents status
Save sessions before shutdown
Extracts session IDs from running agents and saves to config.yaml:
workspace_agents save
This enables --resume when the workspace is restarted.
Apply changes after modifying the directory tree
If you add, remove, or reorganize agent folders:
workspace_agents reload
Diffs the directory tree against the live tmux session, shows what changed, and applies after confirmation.
Recover after crash
Kills the session and rebuilds from config.yaml files:
workspace_agents recover
Agents with saved session_id are launched with --resume.
Agent config.yaml
Every agent pane needs a config.yaml:
type: claude
flags: ""
session_id: ""
type: codex
model: ""
session_id: ""
type: cmd
cmd: "lazygit"
Adding a new agent
To add an agent to an existing workspace:
-
Create the directory:
mkdir -p working_agents/02_Developer/04_NewRole
-
Create config.yaml:
cat > working_agents/02_Developer/04_NewRole/config.yaml << 'EOF'
type: claude
flags: ""
session_id: ""
EOF
-
Optionally add a CLAUDE.md with role instructions
-
Apply the change:
workspace_agents reload
Removing an agent
-
Delete the directory:
rm -rf working_agents/02_Developer/04_NewRole
-
Apply:
workspace_agents reload
CLAUDE.md layering
Claude Code inherits CLAUDE.md from the working directory up to the git root:
working_agents/CLAUDE.md → shared project context (all agents see this)working_agents/01_Persona/CLAUDE.md → persona identity (all roles in this tab)working_agents/01_Persona/01_Role/CLAUDE.md → role-specific instructions
Put shared team rules in the root. Put persona personality in the tab. Put role details in the pane.
Workspace config
Required file at working_agents/config.yamls:
tmux_session: agents_myproject
Sets the tmux session name. Without this, the script won't start.
Persona naming convention
The persona name (used by comms for message routing) comes from the first line of each tab's CLAUDE.md:
# PersonaName — Description
Example: # Reviewer — Auditor → persona is "Reviewer"
Integration with comms
After creating a workspace, install comms from comms-for-agents to enable inter-agent messaging. The comms system reads the same directory tree to discover agents and route messages.
Full specification
For complete details on directory conventions, pane index mapping, session lifecycle, and all command options:
cat specs.md
Input
$ARGUMENTS
