Workspaces

A workspace is a directory that contains your AI tooling configuration.

Directory Structure

my-workspace/
├── .allagents/
│   ├── workspace.yaml    # Workspace configuration
│   └── sync-state.json   # Tracks synced files (auto-generated)
├── .claude/
│   └── commands/         # Claude-specific commands (from plugins)
├── AGENTS.md             # Agent instructions (auto-copied from template)
└── CLAUDE.md             # Claude-specific instructions (optional)

Agent Files

AllAgents automatically copies AGENTS.md and CLAUDE.md from your template source:

• AGENTS.md - Universal agent instructions (works with multiple clients)
• CLAUDE.md - Claude-specific instructions

Both files receive WORKSPACE-RULES injection, which tells AI agents to read workspace.yaml for repository paths.

If your template only has AGENTS.md and claude is in your clients list, AllAgents automatically copies AGENTS.md to CLAUDE.md so Claude has its instruction file.

Creating a Workspace

# Create from default template
allagents workspace init my-workspace

# Create from local template
allagents workspace init my-workspace --from ./path/to/template

# Create from remote GitHub template
allagents workspace init my-workspace --from https://github.com/myorg/templates/tree/main/nodejs
allagents workspace init my-workspace --from myorg/templates/nodejs  # shorthand

Remote Templates

You can initialize a workspace directly from any GitHub repository containing a workspace.yaml file. AllAgents will:

1. Fetch the workspace.yaml from .allagents/workspace.yaml or workspace.yaml in the target path
2. Convert relative workspace.source paths to GitHub URLs so sync works
3. Copy any AGENTS.md and CLAUDE.md files from the template source

Supported formats:

• Full URL: https://github.com/owner/repo/tree/branch/path
• GitHub shorthand: owner/repo/path
• Simple repo: owner/repo (looks for workspace.yaml in root)

workspace.yaml

workspace:
  source: "."           # Source for agent files (local path or GitHub URL)
  files: []             # Additional files to copy (AGENTS.md/CLAUDE.md are auto-included)

repositories:
  - path: ../my-project
    owner: myorg
    repo: my-project
    description: My main project

plugins:
  - code-review@claude-plugins-official

clients:
  - claude
  - copilot
  - cursor

Workspace Source

The workspace.source field specifies the default base directory for resolving file paths:

# Local path (converted to absolute during init)
workspace:
  source: "../shared-config"
  files:
    - AGENTS.md                    # Resolved from ../shared-config/AGENTS.md

# GitHub repository as default source
workspace:
  source: "myorg/my-templates/workspaces/default"
  files:
    - config/settings.json

File-Level Sources

Individual files can override the default workspace.source with their own source:

workspace:
  source: "../shared-config"       # Default base
  files:
    - AGENTS.md                    # Uses default: ../shared-config/AGENTS.md
    - dest: CUSTOM.md              # File-level override
      source: ../other-config/CUSTOM.md
    - dest: REMOTE.md              # GitHub source
      source: owner/repo/path/to/file.md

Source resolution priority:

1. Explicit source on file entry → used directly
2. No source on file → resolved relative to workspace.source
3. No workspace.source and no explicit source → validation error

GitHub file sources are fetched fresh on every sync to ensure you always have the latest version.

File Sync Behavior

• Source is truth: Local copies are overwritten on every sync
• Deleted files restored: If you delete AGENTS.md locally, sync restores it
• WORKSPACE-RULES injection: AGENTS.md and CLAUDE.md automatically get workspace discovery rules

When using --from during init, relative paths are automatically converted to absolute paths so that workspace sync can pull updates from the original source.

Syncing Plugins

allagents workspace sync

By default, sync pulls the latest version of remote plugins from GitHub. Use --offline to skip fetching and use cached versions:

allagents workspace sync --offline

Non-Destructive Sync

AllAgents uses non-destructive sync to protect your files:

• First sync: Overlays plugin files without deleting existing files
• Subsequent syncs: Only removes files that AllAgents previously synced

This means your personal commands, skills, or customizations in .claude/commands/ etc. are never deleted - only files that came from plugins are managed.

AllAgents tracks synced files in .allagents/sync-state.json. This file is automatically created and updated on each sync.

Syncing a Single Client

To sync only a specific client instead of all configured clients:

allagents workspace sync --client opencode

This is useful when you want to update files for one client without touching others. Files and sync state for non-targeted clients are preserved.

Dry Run

Preview what would happen without making changes:

allagents workspace sync --dry-run

User Scope

By default, plugins are installed to the current project. Use --scope user to install plugins to your home directory so they are available across all projects:

# Install a plugin for the current user
allagents workspace plugin install superpowers@obra/superpowers --scope user

# Sync user-scoped plugins
allagents workspace sync --scope user

# Remove a user-scoped plugin
allagents workspace plugin remove superpowers@obra/superpowers --scope user

User-scoped plugins are stored in ~/.allagents/workspace.yaml and sync to user-level directories (~/.claude/, ~/.codex/, etc.) instead of the project. This is useful for plugins you want available everywhere, like personal skills or productivity tools.

User-scoped and project-scoped plugins are independent — they do not interfere with each other.