Configuration

workspace.yaml

The workspace configuration file defines repositories, plugins, workspace file sync, and target clients.

setup:
  - bun install
  - bun run build

# Workspace file sync (optional)
workspace:
  source: ../shared-config              # Default base for relative file paths
  files:
    - AGENTS.md                         # String shorthand: same source and dest
    - source: docs/guide.md             # Object form with explicit source
      dest: GUIDE.md                    # Optional dest (defaults to basename)
    - dest: CUSTOM.md                   # File-level source override
      source: ../other-config/CUSTOM.md
    - dest: AGENTS.md                   # GitHub source
      source: owner/repo/path/AGENTS.md

repositories:
  - path: ../my-project
    source: github
    repo: myorg/my-project
    description: Main project repository
  - path: ../other-project               # Auto-discovers skills from client paths
  - path: ../framework
    skills:                               # Custom skill paths (relative to repo root)
      - plugins/my-plugin/skills
  - path: ../legacy-repo
    skills: false                         # Disable skill discovery for this repo

plugins:
  - code-review@claude-plugins-official
  - name: superpowers@obra/superpowers
    skills:                                # Allowlist: only sync these skills
      - brainstorming
      - test-driven-development
  - name: my-plugin@my-org/my-plugin
    skills:                                # Blocklist: sync all except these
      exclude:
        - verbose-logging

clients:
  - claude
  - copilot
  - cursor

JSON Schema and editor validation

AllAgents publishes separate, versioned schemas for the two workspace scopes:

• Project workspace schema for .allagents/workspace.yaml. It rejects the global profiles field.
• User workspace schema for ~/.allagents/workspace.yaml. It includes global profiles and strict client-specific settings.

Add the matching YAML Language Server directive as the first line of each file:

# yaml-language-server: $schema=https://allagents.dev/schemas/v1/project-workspace.schema.json
repositories: []
plugins: []
clients: []

# yaml-language-server: $schema=https://allagents.dev/schemas/v1/user-workspace.schema.json
profiles:
  review:
    clients:
      - name: claude

The v1 URLs are stable. A future breaking schema contract will use a new versioned directory. Runtime Zod validation remains authoritative; regenerate the committed schemas with bun run schema:generate after changing workspace input models, and verify drift with bun run schema:check.

Client Install Modes

A bare client name uses file sync. Native mode delegates compatible plugin resources to the client’s own package or plugin manager:

clients:
  - pi:native
  - name: omp
    install: native

The colon shorthand and object form are equivalent. A plugin object may set its own install: file or install: native override.

Pi native mode supports npm, Git, and local package sources at project or user scope. Project installs require trust recorded outside the project-controlled Pi agent root. OMP native mode accepts marketplace-backed plugin specs at project or user scope and requires OMP 18.1.17 or newer.

Global Profiles

Named profiles are declared only in the user workspace at ~/.allagents/workspace.yaml. A project .allagents/workspace.yaml containing profiles is invalid.

profiles:
  compound-engineering:
    clients:
      - name: omp
        install: native
        launcher: omp-compound
    plugins:
      - source: EveryInc/compound-engineering-plugin
        ref: main
        install: native

  pi-tools:
    clients:
      - name: pi
        install: native
        launcher: pi-tools
    plugins:
      - source: ./pi-package
        install: native
      - source: npm:pi-mcp-adapter
        install: native
    mcpServers:
      local-tools:
        command: node
        args: [/absolute/path/to/server.mjs]
        env:
          API_TOKEN: ${API_TOKEN}

  oc-review:
    clients:
      - name: opencode
        launcher: opencode-review
        settings:
          model: anthropic/claude-sonnet-4-5
          share: disabled
          autoupdate: false
    plugins:
      - source: ./review-tools
        install: file

  copilot-review:
    clients:
      - name: copilot
        launcher: copilot-review
        settings:
          autoUpdate: false
          remote: "off"
          remoteExport: false
          ide.autoConnect: false
    plugins:
      - source: EveryInc/compound-engineering-plugin
        install: native
      - source: ./review-tools
        install: file
        skills: [review]
    mcpServers:
      review:
        command: review-mcp
        env:
          REVIEW_TOKEN: ${REVIEW_TOKEN}

  codex-review:
    clients:
      - name: codex
        install: native
        launcher: codex-review
        settings:
          model: gpt-5.6-sol
          model_reasoning_effort: high
          approval_policy: on-request
          sandbox_mode: workspace-write
    plugins:
      - source: ./codex-marketplace
        install: native
    mcpServers:
      review:
        command: review-mcp
        env:
          REVIEW_TOKEN: ${REVIEW_TOKEN}

  claude-review:
    clients:
      - name: claude
        install: native
        launcher: claude-review
        settings:
          model: sonnet
          effortLevel: high
          fallbackModel: [haiku]
          autoUpdatesChannel: stable
    plugins:
      - source: ./claude-marketplace
        install: native
      - source: ./review-tools
        install: file
        skills: [review]
    mcpServers:
      review:
        command: review-mcp
        env:
          REVIEW_TOKEN: ${REVIEW_TOKEN}

Field	Required	Description
profiles.<name>.clients	Yes	One or more object-form profile clients
clients[].name	Yes	Supported profile client; currently pi, omp, opencode, copilot, codex, or claude
clients[].install	No	Default plugin mode, file by default; OpenCode rejects native because its CLI lacks a complete inspect/update/remove lifecycle
clients[].launcher	No	Safe command basename written to the configured user bin directory
clients[].settings	No	Strict client settings object; Pi and OMP accept no settings, while OpenCode, Copilot, Codex, and Claude accept their documented profile settings
profiles.<name>.plugins	No	Profile plugin declarations; defaults to an empty list
plugins[].source	Yes	npm, GitHub, marketplace, or local source supported by the selected adapter
plugins[].ref	No	Requested Git ref for a GitHub source
plugins[].install	No	Per-plugin file or native override
plugins[].clients	No	Restrict the plugin to named clients in this profile
plugins[].skills	No	Skill allowlist or { exclude: [...] } where the adapter supports filtering
profiles.<name>.mcpServers	No	Profile-scoped stdio or HTTP MCP declarations

Relative local plugin sources resolve from the user’s home directory, not the current project. Profile names and launcher names are safe command basenames; machine paths, resolved revisions, generated launcher paths, and ownership state are not declaration fields.

MCP credentials must remain runtime references. Environment values and HTTP headers accept exact ${ENV_VAR} references only, and credential-bearing command arguments must use the same exact form. Resolved secret values are never written to plans, launchers, profile state, or generated configuration.

OpenCode profile settings accept model, small_model, default_agent, username, share, autoupdate, snapshot, subagent_depth, logLevel, disabled_providers, and enabled_providers. All other keys fail validation. The launcher sets both OpenCode configuration override variables. These layers still merge with normal global and project configuration; they are not a strict runtime sandbox. ${ENV_VAR} MCP references are serialized to OpenCode’s runtime {env:ENV_VAR} syntax without resolving the value.

Copilot profiles require GitHub Copilot CLI 1.0.74 or newer. Their launchers set both COPILOT_HOME and COPILOT_CACHE_HOME; the selected configuration and cache roots are isolated while normal current-project discovery remains active. Copilot profile settings accept model, theme, autoUpdate, autoUpdatesChannel, banner, askUser, includeCoAuthoredBy, stream, streamerMode, toolSearch, updateTerminalTitle, respectGitignore, disableAllHooks, experimental, bashEnv, keepAlive, commandHistoryMaxSize, compactPaste, mouse, terminalProgress, remote, remoteExport, ide.autoConnect, shellShortcut, customAgents.defaultLocalOnly, storeTokenPlaintext, disabledMcpServers, and enabledMcpServers. All other keys fail validation. MCP declarations are written to the selected root’s mcp-config.json, retain ${ENV_VAR} references, and expose their declared tools to Copilot.

Copilot native plugins must resolve to exactly one authoritative marketplace entry. Native skill filters and native Git refs are rejected because Copilot cannot enforce either constraint. File installation supports skill selection and pinned Git sources instead.

Codex profiles require Codex CLI 0.149.0 or newer. Their launchers set an isolated CODEX_HOME, require the generated <profile>.config.toml, select it with --profile <profile>, and preserve the caller’s working directory for normal project discovery. Settings accept model, model_reasoning_effort, model_reasoning_summary, model_verbosity, approval_policy, sandbox_mode, web_search, and personality. All other keys fail validation.

Codex MCP declarations share the named TOML profile. Exact ${ENV_VAR} references become Codex environment-variable names (env_vars or env_http_headers) instead of literal values. References in commands, arguments, URLs, or remapped stdio variables fail before mutation because Codex does not interpolate them. Native plugins use authoritative marketplace identities; AllAgents delegates registration, install, Git marketplace upgrade, targeted refresh, uninstall, and safe marketplace removal to Codex.

Claude profiles require Claude Code 2.1.268 or newer. Their launchers select an absolute, isolated CLAUDE_CONFIG_DIR, isolate the plugin cache, and clear inherited plugin seed and transcript-bucketing selectors. The caller’s working directory remains unchanged, so project CLAUDE.md, settings, skills, and .mcp.json discovery continue normally.

Claude profile settings accept model, effortLevel, fallbackModel, outputStyle, autoMemoryEnabled, spinnerTipsEnabled, and autoUpdatesChannel. All other keys fail validation. AllAgents writes settings.json and an additive allagents.mcp.json; the launcher requires both files and passes only the MCP file explicitly, without suppressing normal project MCP discovery. ${ENV_VAR} references remain unresolved until Claude starts.

Native Claude plugins require exactly one authoritative marketplace identity. AllAgents writes the marketplace and enabled-plugin declarations Claude needs, then delegates install, update, uninstall, inventory, and safe marketplace cleanup to Claude’s user scope inside the selected root. Native skill filters and sparse marketplace paths fail before mutation; use file installation for those cases.

Install profiles explicitly with allagents profile install <name> --yes. Ordinary allagents update reconciles installed, still-declared profiles; repeat --profile <name> to select only installed profiles. Removing a declaration does not uninstall it—use allagents profile remove <name> --yes.

Setup Commands

The optional top-level setup field is an ordered list. A string runs on every platform. Use an object to select operating systems or CPU architectures:

setup:
  - bun install
  - run: curl -fsSL https://example.com/install.sh | sh
    platforms: [linux, darwin]
    architectures: [x64, arm64]
  - run: 'powershell -ExecutionPolicy Bypass -c "irm https://example.com/install.ps1 | iex"'
    platforms: [win32]

Field	Required	Description
run	Yes for object entries	Shell command to execute
platforms	No	Allowed Node platform names, such as linux, darwin, or win32
architectures	No	Allowed Node architecture names, such as x64 or arm64

When both selectors are present, the current platform and architecture must match. Nonmatching entries are reported as skipped without executing.

Run setup only with the explicit allagents workspace setup action. AllAgents never runs it during init, update, or sync. This is a trust boundary: remote workspace templates are untrusted until you review their setup commands and explicitly choose to execute them.

AllAgents reports entries in declaration order. Matching commands are shown immediately before they run, execute sequentially from the workspace root, inherit terminal I/O, and stop after the first nonzero exit or terminating signal. In --json mode, command announcements and output are forwarded to stderr so stdout remains one deterministic JSON document.

Plugin Skills

Control which skills are synced per plugin using the inline skills field on plugin entries:

plugins:
  # All skills (default — no skills field needed)
  - code-review@claude-plugins-official

  # Allowlist — only sync these skills
  - name: superpowers@obra/superpowers
    skills:
      - brainstorming
      - test-driven-development

  # Blocklist — sync all except these
  - name: my-plugin@my-org/my-plugin
    skills:
      exclude:
        - verbose-logging

Format	Behavior
omitted	All skills synced
string[] (allowlist)	Only listed skills are synced
{ exclude: string[] } (blocklist)	All skills except listed ones are synced

Skills are managed via the CLI:

• allagents plugin skills remove <skill> — disable a skill
• allagents plugin skills add <skill> — enable a skill
• allagents plugin skills list — view all skills with status

Selective install also sets up the allowlist automatically:

allagents plugin install superpowers@marketplace --skill brainstorming

Note

The top-level disabledSkills and enabledSkills arrays are deprecated (v1 format). They still work as a fallback for configs that haven’t migrated, but new configs should use the inline skills field on plugin entries instead.

Plugin Git Refs

GitHub plugin entries can select a release tag or branch with ref:

plugins:
  - source: https://github.com/EveryInc/compound-engineering-plugin
    ref: compound-engineering-v3.23.3

This is equivalent to the inline owner/repo@<ref> source form. An inline ref takes precedence, so do not configure both forms on the same entry. Local paths, marketplace plugin selectors, and GitHub /tree/ or /blob/ URLs already carry their own location and ignore object-form ref.

ref selects a symbolic Git ref; it is not a content-integrity lock. Sync state records the resolved commit SHA for provenance, but AllAgents does not currently reject a tag or branch that later resolves to a different commit.

Workspace File Sync

The workspace section enables syncing files from external sources to your workspace root.

Field	Required	Description
source	No	Default base directory for resolving relative file paths
files	Yes	Array of files to sync

File entry formats:

Format	Example	Description
String	AGENTS.md	Source and dest are the same, resolved from workspace.source
Object with source	{source: "path/file.md"}	Dest defaults to basename
Object with dest	{dest: "file.md", source: "..."}	Explicit source and dest

Source resolution priority:

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

GitHub sources:

• Format: owner/repo/path/to/file.md
• Fetched fresh on every sync (always pulls latest)

Behaviors:

• Source is the single source of truth; local copies are overwritten
• Deleted local files are restored on next sync
• AGENTS.md and CLAUDE.md automatically receive WORKSPACE-RULES injection

Repository Skill Discovery

During sync, AllAgents scans workspace repositories for skills and embeds an index in the WORKSPACE-RULES section of AGENTS.md. AI agents use this index to find and load skills from repos they’re working in.

By default, skill discovery scans each repository’s client skill directories (e.g., .claude/skills/, .agents/skills/, .codex/skills/) based on which clients are configured. Symlinks and junctions are skipped.

The skills field on each repository controls discovery:

Value	Behavior
omitted or true	Auto-discover from client skill paths
string[]	Scan only these custom paths (relative to repo root)
false	Disable skill discovery for this repo

repositories:
  - path: ../my-project                  # Auto-discovers from .claude/skills/, .agents/skills/, etc.
  - path: ../framework
    skills:
      - plugins/agentv-dev/skills        # Only scan these paths
      - plugins/agentic-engineering/skills
  - path: ../legacy-repo
    skills: false                        # No skill discovery

Skills must have a SKILL.md file with YAML frontmatter containing name and description fields. The generated index uses relative paths from the workspace root so AI agents can read the full skill instructions on demand.

Duplicate Skill Resolution

When multiple repositories (or multiple client paths within the same repo) contain skills with the same name, AllAgents picks a single winner:

Priority	Rule
1st	Skills under .agents/ paths take priority
2nd	The skill with the largest file size wins
3rd	First-seen skill wins (repository order in workspace.yaml)

This differs from plugin skill deduplication, which keeps all copies and renames them for uniqueness. Repository skills are an index of pointers, so only the best source is kept.

MCP Servers

The optional top-level mcpServers field defines MCP servers managed directly by the workspace. Servers defined here are synced to all configured project-scoped MCP clients (claude, codex, vscode, copilot).

mcpServers:
  deepwiki:
    type: http
    url: https://mcp.deepwiki.com/mcp
    headers:
      Authorization: Bearer ${DEEPWIKI_TOKEN}

  gh-server:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-github'
    env:
      GH_TOKEN: ghp_xxx

  # Per-server client filter — only sync to specific clients
  claude-only:
    type: http
    url: https://mcp.example.com
    clients:
      - claude

Field	Required	Description
type	No	http or stdio (inferred from presence of url vs command if omitted)
url	http only	HTTP URL for the MCP server
headers	No	HTTP headers map (http transport only)
command	stdio only	Executable for the stdio command
args	No	Command arguments array (stdio transport only)
env	No	Environment variables map (stdio transport only)
clients	No	Subset of project-scoped clients that should receive this server. Defaults to all configured clients.

Manage these entries declaratively in workspace.yaml, or via the allagents mcp commands. Workspace-level servers override any plugin-supplied server with the same name (with a warning).

Servers AllAgents adds are tracked in .allagents/sync-state.json; pre-existing user-managed servers in client MCP configs (.mcp.json, .vscode/mcp.json, .copilot/mcp-config.json, .codex/config.toml) are never touched.

MCP Proxy

The optional mcpProxy section rewrites HTTP MCP servers to stdio via AllAgents’ built-in allagents mcp proxy bridge for clients that need it. See the MCP Proxy guide for details.

mcpProxy:
  clients:
    - claude
    - copilot
  servers:
    my-internal-api:
      proxy:
        - codex

Field	Required	Description
clients	Yes	Clients where all HTTP servers are proxied to stdio
servers	No	Per-server overrides with additional client lists
servers.<name>.proxy	Yes (per entry)	Additional clients to proxy this specific server for

Only servers with HTTP transport (url field) are transformed. Stdio servers pass through unchanged.

VSCode Configuration

The optional vscode section controls .code-workspace file generation when vscode is in the clients list.

vscode:
  output: my-project    # Output filename (without .code-workspace extension)

Field	Required	Description
output	No	Custom filename for the generated .code-workspace file. Defaults to the workspace directory name.

Template File

Place a template.code-workspace in .allagents/ to customize the generated workspace:

{
  "folders": [
    { "path": "{path:../Shared}", "name": "SharedLib" }
  ],
  "settings": { "editor.formatOnSave": true },
  "launch": { "configurations": [] },
  "extensions": { "recommendations": ["dbaeumer.vscode-eslint"] }
}

The {path:../path} placeholder syntax resolves to absolute paths using repository paths from workspace.yaml. It works in any string value within the template (folders, settings, launch configs).

User-Level workspace.yaml

When using --scope user, AllAgents stores a separate config at ~/.allagents/workspace.yaml:

plugins:
  - superpowers@obra/superpowers

The user file accepts the same ordinary workspace fields as a project file, and also accepts global profiles. Its repositories, plugins, and clients arrays default to empty, so it may contain only profiles. User-scoped ordinary plugins sync to user-level directories (~/.claude/, ~/.codex/, etc.); profile lifecycle remains explicit and independent.

Sync state for user-scoped plugins is tracked in ~/.allagents/sync-state.json.