workspace-agents

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:

# Claude Code agent
type: claude
flags: ""              # extra CLI flags
session_id: ""         # managed by save/recover

# Codex agent
type: codex
model: ""              # model name (e.g. o3)
session_id: ""

# Shell command (tools, dashboards)
type: cmd
cmd: "lazygit"         # command to run

Adding a new agent

To add an agent to an existing workspace:

1. Create the directory:

   mkdir -p working_agents/02_Developer/04_NewRole
   

2. Create config.yaml:

   cat > working_agents/02_Developer/04_NewRole/config.yaml << 'EOF'
   type: claude
   flags: ""
   session_id: ""
   EOF
   

3. Optionally add a CLAUDE.md with role instructions

4. Apply the change:

   workspace_agents reload
   

Removing an agent

1. Delete the directory:

   rm -rf working_agents/02_Developer/04_NewRole
   

2. 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  # in the workspace-for-agents repository root

Input

$ARGUMENTS