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 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 embeds repository paths and a skills index directly in the file so AI agents know which repos are available and what skills they contain.

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
    source: github
    repo: myorg/my-project
    description: My main project
    managed: true               # Let AllAgents clone/pull this repo
  - path: ../shared-lib
    skills:                     # Custom skill paths (overrides auto-discovery)
      - plugins/my-plugin/skills

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

clients:
  - claude
  - copilot
  - cursor
  - vscode

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, including a skills index if any repositories contain skills

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

Managed Repositories

A repositories[] entry is a reference by default. AllAgents reads it to build the skills index and propagate agent files, but it never runs git against the directory — whoever created that directory owns it.

Set managed when AllAgents should materialize the repository too:

Value	Behavior
omitted or false	AllAgents never clones or pulls
"clone"	Clones when the path is missing, never pulls
true or "sync"	Clones when the path is missing, pulls on every sync

This matters most when something else populates the directory. A CI job that checks out a pinned commit before calling allagents update should leave managed unset — or pass --no-managed to that run — so AllAgents cannot move the checkout to upstream HEAD. Pulls are skipped rather than forced when the working tree is dirty or is not on the declared ref.

See Managed Repositories in the configuration reference for the full field semantics.

VSCode Workspace Generation

When vscode is included in the clients list, allagents update automatically generates a .code-workspace file. Repository paths are resolved to absolute paths.

workspace.yaml

clients:
  - vscode
  - claude

Output Filename

The output filename defaults to <dirname>.code-workspace. Override with vscode.output:

vscode:
  output: my-project

Template File

Create .allagents/template.code-workspace for VSCode-specific settings, launch configurations, extensions, and extra folders. The template supports {path:../path} placeholders that resolve to absolute paths using repository paths from workspace.yaml.

{
  "folders": [
    { "path": "{path:../Shared}", "name": "SharedLib" }
  ],
  "settings": {
    "cSpell.words": ["myterm"],
    "chat.agent.maxRequests": 999
  },
  "launch": {
    "configurations": [
      {
        "type": "node",
        "name": "dev",
        "cwd": "{path:../myapp}/src",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run", "dev"]
      }
    ]
  },
  "extensions": {
    "recommendations": ["dbaeumer.vscode-eslint"]
  }
}

The generated workspace includes:

• Workspace root folder (.) listed first
• Repository folders (resolved to absolute paths)
• Template folders (deduplicated against repository folders)
• All template content (settings, launch, extensions) with {path:..} placeholders resolved

Syncing Plugins

allagents update

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

allagents update --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 update --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 update --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 update --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.