Extends

The extends field in agentsmesh.yaml lets you inherit shared configuration from remote repositories, local paths, or git URLs. Extended config merges with your local canonical config during generation.

Configuration

extends:
  # GitHub release tag
  - name: company-rules
    source: github:my-org/ai-config@v1.0.0
    features: [rules, commands]

  # GitLab repo
  - name: platform-config
    source: gitlab:infra/ai-standards@v2.3.1
    features: [rules, permissions]

  # Git SSH
  - name: private-rules
    source: git+ssh://git@github.com/org/config.git#main
    features: [rules]

  # Local directory (monorepo)
  - name: shared-local
    source: ../shared-ai-config
    features: [rules, commands, mcp]

  # Flat markdown directory forced to commands
  - name: team-workflows
    source: github:my-org/command-library@v1.2.0
    path: workflows
    as: commands
    features: [commands]

Fields

Field	Type	Required	Description
name	string	Yes	Identifier for this extends entry. Used in error messages.
source	string	Yes	Source URL or path (see formats below).
version	string	No	Version tag for remote sources (alternative to @tag in source).
target	string	No	Hint for native format auto-discovery (e.g., claude-code).
as	string	No	Force manual loading as rules, commands, agents, or skills. Useful for flat markdown directories.
features	string[]	No	Which features to inherit. Omit to inherit all.
path	string	No	Subdirectory within the source to look for config.
pick	object	No	Cherry-pick specific named resources.
accept	string[]	No	Consent to keep elevated artifacts (hooks, permissions, mcp) from a remote source. Stripped by default; ignored for local sources.

Source formats

Format	Example
GitHub shorthand	github:org/repo@v1.0.0
GitHub (latest)	github:org/repo
GitLab shorthand	gitlab:group/repo@main
Git SSH	git+ssh://git@github.com/org/repo#main
Git HTTPS	git+https://github.com/org/repo.git#v2.0.0
Local path	../shared-config or local:../shared-config

Cherry-picking specific resources

Use pick to inherit only specific named rules, commands, or agents from a source:

extends:
  - name: selective-rules
    source: github:org/big-config@v3.0.0
    features: [rules, commands]
    pick:
      rules: [security, performance, testing]
      commands: [commit, review]

Only the listed items are inherited; everything else in the source is ignored.

Cache behavior

Remote sources are cached in ~/.agentsmesh/cache/ after the first fetch. Subsequent generate runs use the cache.

To force a re-fetch:

agentsmesh generate --refresh-cache
agentsmesh generate --no-cache   # alias

Tip

Pin remote sources to a version tag (e.g., @v1.0.0) to ensure deterministic builds. Using @main or no version means you get the latest on every cache refresh.

Environment variables

Variable	Effect
AGENTSMESH_CACHE	Override the cache directory. Must be an absolute path and must not be the filesystem root (/ or a Windows drive root); otherwise the CLI throws at startup. Defaults to ~/.agentsmesh/cache.
AGENTSMESH_GITHUB_TOKEN	Token attached as Authorization: Bearer … for GitHub tarball/clone fetches. Required for private repos.
AGENTSMESH_GITLAB_TOKEN	Token interpolated into GitLab clone URLs (https://oauth2:$TOKEN@host/…). Required for private repos.
AGENTSMESH_ALLOW_INSECURE_GIT	When set to 1, enables insecure http:// git transports. Disabled by default because http strips transport security — a MITM on any hop can swap the cloned bytes before the SHA is pinned. Set to 1 only for closed-network development.
AGENTSMESH_ALLOW_LOCAL_GIT	When set to 1, enables git+file:// sources. Disabled by default because on shared/multi-tenant hosts a git+file:///tmp/world-writable-repo source could be planted by another user; combined with elevated-artifact emission this is a local privilege-escalation vector. Set to 1 only for closed-network development.

Fetch hardening

AgentsMesh applies the following limits to every extends: and install fetch:

• Tarball downloads are capped at 500 MiB. The CLI fast-fails on a Content-Length over the cap and aborts mid-stream when the running byte total exceeds it.
• Tar entries are allowlisted by type: only File and Directory entries extract. FIFOs, devices, hardlinks, symlinks, and any exotic tar variant are rejected. Entries with .. segments or absolute paths are also rejected (zip-slip protection).
• Git refs and clone URLs that begin with - are rejected as a defense against option injection (e.g. --upload-pack=evil). Avoid branch names that start with a dash.
• Canonical entity traversal — rules, commands, agents, and skill supporting files — does not follow symlinks, preventing a pack from pulling external bytes (e.g. rules/notes.md -> ~/.ssh/id_rsa) into canonical content and into a redistributed pack.
• Git transports are allowlisted: https and ssh are permitted by default; http requires AGENTSMESH_ALLOW_INSECURE_GIT=1, file requires AGENTSMESH_ALLOW_LOCAL_GIT=1, and all other transports (git://, ext::, …) are refused — enforced on the install ref-resolution path as well as extends:.
• Credentials are redacted from error output: oauth2:<token>@, x-access-token:<token>@, and any userinfo-bearing URL is masked (https://***@host/...) so tokens never leak into CI logs or terminal scrollback.

Elevated artifacts from remote sources

hooks, permissions, and mcp control local code execution at generate time — a remote source that ships them effectively gets to run commands on your machine the next time the target agent fires the matching event. So when an extends source is remote (github:, gitlab:, git+…, including git+file://), those three artifacts are stripped by default, even when listed in features. A warning reports what was dropped.

To merge them, opt in per-artifact with accept: on the entry — only what you list is kept:

extends:
  - name: company-base
    source: github:my-org/ai-config@v1.0.0
    features: [rules, hooks, permissions, mcp]
    accept: [hooks, permissions, mcp]

Local extends (e.g. ../shared-config) are trusted as-is and ignore accept — you already control those bytes. This mirrors the --accept-* flags on agentsmesh install.

Merge precedence

When extends sources define resources that conflict with your local canonical config, the merge order is:

1. Local .agentsmesh/ (highest priority — always wins)
2. Installed packs (.agentsmesh/packs/)
3. Extended sources (lowest priority)

This means your local overrides always take precedence over shared org config.

Installing extends via CLI

Instead of manually editing agentsmesh.yaml, you can use agentsmesh install --extends:

agentsmesh install github:org/base-config --extends

Unlike plain agentsmesh install, the --extends flag does not materialize a pack under .agentsmesh/packs/. It only adds the entry to the extends: list in agentsmesh.yaml; the content is fetched and merged on every agentsmesh generate. Use this when you want the extending repository to remain a live reference (always-on-latest) rather than a snapshotted pack.

Removing extends via CLI

agentsmesh uninstall <name>

Removes the matching extends: entry from agentsmesh.yaml (and, if the install also materialized a pack, the pack directory and installs.yaml row). For extends-only installs (no pack on disk):

• pack_path is reported as null in the JSON envelope.
• --keep-pack is a no-op because no pack directory exists.
• The post-uninstall generate pass re-resolves the remaining extends: list so any inherited content disappears from the generated target trees.

See agentsmesh uninstall for the full flag and exit-code reference.