Workspaces

Workspaces provide isolated development environments for each issue, enabling multiple agents to work on different features simultaneously without conflicts.

What Are Workspaces?

Workspaces are git worktrees - isolated working directories for each issue/feature. Each workspace:

Has its own feature branch (e.g., feature/min-123-add-login)
Shares git history with the main repo (no separate clone)
Can run independently (separate node_modules, builds, containers)
Is located at {project}/workspaces/{issue-id}/

This architecture allows multiple agents to work simultaneously without stepping on each other’s toes.

Why Workspaces?

Without workspaces:

Only one agent can work at a time (shared working directory)
Branch switching disrupts running agents
Can’t test multiple features simultaneously
Risk of cross-contamination between issues

With workspaces:

Multiple agents work in parallel on different issues
Each has its own branch, dependencies, and containers
Complete isolation - no shared state
Clean, predictable environment per issue

Architecture

project/
├── .git/                  # Shared git repository
├── src/                   # Main project (always on 'main' branch)
├── package.json
└── workspaces/
    ├── feature-min-123/   # Workspace for MIN-123
    │   ├── .git           # Symlink to ../.git
    │   ├── .planning/     # Planning artifacts (ephemeral)
    │   ├── src/           # Feature branch code
    │   ├── node_modules/  # Independent dependencies
    │   └── docker-compose.yml
    └── feature-min-456/   # Workspace for MIN-456
        ├── .git
        ├── .planning/
        └── src/

Git Worktrees

Git worktrees allow multiple working directories to share a single git repository. Benefits: Efficiency:

No need to clone the repo multiple times
Shared git history and objects (saves disk space)
Fast branch switching (just create a new worktree)

Isolation:

Each worktree has its own checked-out branch
Changes in one worktree don’t affect others
Can build/test multiple branches simultaneously

Safety:

Can’t accidentally checkout the same branch twice
Main project stays on main branch (protected)
Feature work isolated to dedicated worktrees

Workspace Structure

workspaces/feature-min-123/
├── .planning/                 # Planning artifacts (ephemeral)
│   ├── STATE.md               # Current planning state
│   ├── output.jsonl           # Full conversation history
│   ├── PLANNING_PROMPT.md     # Initial planning prompt
│   ├── CONTINUATION_PROMPT.md # Context for continued sessions
│   └── output-*.jsonl         # Backup of previous rounds
├── src/                       # Feature branch code
├── node_modules/              # Independent dependencies
├── package.json
└── docker-compose.yml         # Workspace-specific containers

Planning Artifacts

⚠️ Note: .planning/ is currently ephemeral (not tracked in git) The .planning/ directory is listed in .gitignore to prevent cross-contamination between issues. When branches merge, planning state from issue A could contaminate issue B’s workspace, causing agents to work on the wrong tasks. Current behavior: Planning state is local to your machine only. If you switch machines, you’ll need to re-run the planning session.

When planning completes, the AI generates:

STATE.md - Current understanding, decisions made, and implementation plan
Beads tasks - Trackable sub-tasks with dependencies
Feature PRD - Copied to docs/prds/active/{issue}-plan.md for documentation

What persists:

Context recovery - STATE.md and beads preserve planning decisions
Audit trail - See decisions made in STATE.md
Beads tasks - Sub-tasks ARE persisted (beads uses label-based isolation)

Docker Integration

Workspaces can have independent Docker environments, allowing:

Isolated databases per feature
Independent service configurations
No port conflicts (unique project names)

Starting Containers with Workspaces

# Create workspace and start Docker containers
pan workspace create MIN-123 --docker

What happens:

Creates the workspace (git worktree)
Looks for docker-compose files in workspace
Runs docker compose -p "{project}-feature-{issue}" up -d --build

Docker Project Naming: Each workspace gets a unique Docker Compose project name:

Format: {project-name}-feature-{issue-id}
Example: mind-your-now-feature-min-123
Container names: {project}-{service}-1

This prevents conflicts when running multiple workspaces simultaneously.

Dashboard Integration

The planning dialog includes a “Start Docker containers” checkbox:

Default: Enabled (containers start automatically)
Preference saved: Your choice is remembered in browser localStorage

Why this helps:

Containers start warming up while you review the issue
Environment ready when planning agent starts
Can test assumptions during planning without waiting

Workspace Lifecycle

1. Creation

# Create workspace without Docker
pan workspace create MIN-123

# Create workspace with Docker containers
pan workspace create MIN-123 --docker

What happens:

Creates git worktree at {project}/workspaces/feature-min-123/
Checks out feature branch feature/min-123-*
Optionally starts Docker containers
Registers workspace in Panopticon registry

2. Usage

Agents work inside the workspace:

Planning agents - Explore codebase, create STATE.md and beads tasks
Work agents - Implement features, run tests, commit changes
Specialists - Review code, run tests, merge changes

All activity isolated to the workspace directory.

3. Cleanup

# Destroy workspace (safe - checks for uncommitted changes)
pan workspace destroy MIN-123

# Force destroy (even with uncommitted changes)
pan workspace destroy MIN-123 --force

What happens:

Stops and removes Docker containers (if any)
Checks for uncommitted changes (unless —force)
Removes git worktree
Cleans up planning artifacts
Unregisters from Panopticon

Main Project Branch Convention

CRITICAL: The main project directory must ALWAYS stay on the main branch. All feature work happens in workspaces.

Why this matters:

Specialists (review-agent, test-agent) need a stable reference point
Merge operations require a clean target
Multiple agents won’t interfere with each other

Wrong:

# In main project directory
git checkout feature/min-123  # ❌ BAD!

Right:

# Create a workspace instead
pan workspace create MIN-123  # ✅ GOOD!
cd workspaces/feature-min-123

Git Hooks for Branch Protection

Panopticon provides git hooks to enforce the main branch convention. These hooks are automatically installed:

On pan project add - Hooks installed when registering project
On pan sync - Hooks updated in all registered projects

Auto-revert behavior:

Agents & planning sessions: Automatically revert to main if they accidentally checkout a feature branch
Human users: Display prominent warning (no auto-revert by default)

To enable auto-revert for humans:

export PANOPTICON_AUTO_REVERT_CHECKOUT=1  # Add to .bashrc/.zshrc

Safeguards

Planning vs Work Agent Safeguard

The dashboard prevents starting a work agent (agent-<issue>) while a planning agent (planning-<issue>) is still running. This prevents conflicts where both agents try to modify the same workspace. If you see “Planning agent is still running”:

Complete planning - Use “Complete Planning” button
Or abort - Use “Abort Planning” to discard
Or kill manually - tmux kill-session -t planning-<issue>

Specialist Agent Safeguards

All specialist agents (review-agent, test-agent, merge-agent) are configured to:

Run in workspaces only - Never in main project directory
Never checkout branches - Work with branch already in workspace
Create workspaces if needed - Use pan workspace create instead of git checkout

These safeguards are enforced through:

Prompt instructions - Clear warnings in all specialist prompts
Code enforcement - Specialists spawn with workspace as cwd
Git hooks - Auto-revert if checkout detected in tmux sessions

Use Cases

Feature Development:

pan workspace create MIN-123
cd workspaces/feature-min-123
# Agent implements feature in isolation

Parallel Development:

pan workspace create MIN-123
pan workspace create MIN-456
pan workspace create MIN-789
# Three agents work simultaneously without conflicts

Testing Multiple Approaches:

pan workspace create MIN-123 --docker
pan workspace create MIN-123-alternative --docker
# Compare two implementation approaches side-by-side

Emergency Hotfix:

pan workspace create MIN-999-hotfix
# Fix doesn't interfere with ongoing feature work

Best Practices

Workspace Management:

Create workspace before starting work (don’t checkout in main project)
One workspace per issue (don’t reuse for multiple issues)
Clean up completed workspaces to free disk space
Use --docker flag to warm up containers early

Branch Naming:

Follow convention: feature/{issue-id}-{description}
Example: feature/min-123-add-login
Panopticon auto-generates appropriate names

Docker Usage:

Use unique container names via project naming
Clean up containers when destroying workspace
Keep docker-compose.yml in workspace (not main project)

Planning Artifacts:

.planning/ is ephemeral - don’t rely on it for cross-machine work
STATE.md and beads persist the important context
Feature PRD goes to docs/prds/active/ for permanent storage

Remote Workspaces (Fly.io)

Panopticon supports remote workspace execution via Fly.io Machines. Remote workspaces provide cloud-hosted agent environments without local resource constraints.

Why Remote Workspaces?

Resource isolation — Heavy builds and tests don’t compete with your local machine
On-demand provisioning — Machines spin up per workspace and shut down after merge
Same workflow — CLI and dashboard work identically for local and remote workspaces

Setup

# Initialize Fly.io provider
pan remote init

# Configure remote environment
pan remote setup

# Check remote workspace status
pan remote status

# View resource allocation
pan remote resources

Creating Remote Workspaces

Remote workspaces are created through the dashboard planning dialog or CLI:

# Create workspace with remote execution
pan workspace create MIN-123 --remote

The workspace is provisioned on a Fly.io Machine with your project’s dependencies pre-installed. Agents connect to the remote environment via the same tmux-based interface used for local workspaces.

Troubleshooting

Workspace creation fails:

# Check if worktree already exists
git worktree list

# Remove stale worktree
git worktree remove workspaces/feature-min-123

Docker containers conflict:

# Check running containers
docker ps | grep feature-min-123

# Stop conflicting containers
docker compose -p mind-your-now-feature-min-123 down

Main project on wrong branch:

# Go back to main
cd /path/to/project
git checkout main

Disk space issues:

# List all workspaces
pan workspace list

# Destroy completed workspaces
pan workspace destroy MIN-123
pan workspace destroy MIN-456

Workspace Commands - CLI reference
Specialists - Specialist agent workspace usage
Planning Session - Using workspaces for planning

Features

Documentation Index

​Workspaces

​What Are Workspaces?

​Why Workspaces?

​Architecture

​Git Worktrees

​Workspace Structure

​Planning Artifacts

​Docker Integration

​Starting Containers with Workspaces

​Dashboard Integration

​Workspace Lifecycle

​1. Creation

​2. Usage

​3. Cleanup

​Main Project Branch Convention

​Git Hooks for Branch Protection

​Safeguards

​Planning vs Work Agent Safeguard

​Specialist Agent Safeguards

​Use Cases

​Best Practices

​Remote Workspaces (Fly.io)

​Why Remote Workspaces?

​Setup

​Creating Remote Workspaces

​Troubleshooting

​Related Guides

Workspaces

What Are Workspaces?

Why Workspaces?

Architecture

Git Worktrees

Workspace Structure

Planning Artifacts

Docker Integration

Starting Containers with Workspaces

Dashboard Integration

Workspace Lifecycle

1. Creation

2. Usage

3. Cleanup

Main Project Branch Convention

Git Hooks for Branch Protection

Safeguards

Planning vs Work Agent Safeguard

Specialist Agent Safeguards

Use Cases

Best Practices

Remote Workspaces (Fly.io)

Why Remote Workspaces?

Setup

Creating Remote Workspaces

Troubleshooting

Related Guides