agentwheel

One source. Every agent.

Weave skills, rules, instructions, commands, subagents, MCP, hooks, settings, and plugins across every AI agent you use, from any source, reconciled into each runtime with your private tweaks intact.

---

Why agentwheel?

Your AI agents are multiplying. OpenClaw, Claude Code, Codex CLI, Copilot, Hermes — and the next harness your team adopts. Each one wants its own skills, rules, instructions, commands, subagents, MCP servers, hooks, and settings, in its own layout.

agentwheel makes that one declared state. Add packages to .agentwheel/config.json, preview the runtime changes, then install the declared state into each target. Updates move tracking sources forward explicitly; installs make the current declaration true.

npm i -g agentwheel
agentwheel init
agentwheel add github:your-org/agent-pack --adapter codex --local --mode tracking
agentwheel plan
agentwheel install

No lock-in. No central gatekeeper. Packages live in plain git repos or local folders, customizations live in your workspace, and runtimes stay generated output.

Install Methods

CLI install

npm i -g agentwheel
agentwheel init

Prefer pnpm? pnpm add -g agentwheel works too.

AI agent handoff

Give an agent install.md when you want it to install Agentwheel, verify the CLI, install the companion skill, and show the right catalogue flow for your runtime.

curl -fsSL https://raw.githubusercontent.com/NestDevLab/agentwheel/main/install.md

Companion skills

The management skill keeps Agentwheel commands and safety rules inside the runtime you are using. Install the discovery skill separately when you also want proactive, non-installing suggestions:

agentwheel doctor --adapter codex --local
agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel
agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel-discovery

Supported runtimes & resources

agentwheel installs OpenPack resources into five built-in runtimes and into custom harnesses. Every built-in target is scoped by --installation-type <type>; built-ins currently use local for project/workspace installs and user for documented user-level installs. If a package can be installed in more than one type, agentwheel requires --installation-type instead of guessing.

• OpenClaw — workspace skills/, local plugin directories; user ~/.openclaw/skills, ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/workspace-subagents/<name>/AGENTS.md, and ~/.openclaw/openclaw.json
• Claude Code — CLAUDE.md, .claude/, .mcp.json, and user ~/.claude/
• Codex CLI — AGENTS.md, .agents/skills, plugins/, .codex/, and user equivalents
• GitHub Copilot CLI — .github/, user ~/.copilot/, and documented .agents skill alternatives
• Hermes — local AGENTS.md; user ~/.hermes/SOUL.md, ~/.hermes/skills, ~/.hermes/plugins, and ~/.hermes/config.yaml
• Bring your own — JSONC config adapters with --adapter-config, or programmatic adapters with --adapter-module

Supported resource types include instructions, rules, skills, commands, subagents, MCP, hooks, settings, plugins, and fragments. Runtime compatibility is per artifact and per installation type; see docs/design/artifact-harness-compatibility.md. Fragments are Agentwheel composition inputs, not runtime file-drop targets.

rules is an OpenPack artifact kind, not a portable runtime concept. Claude rules are behavioral/path-scoped instructions, Copilot rule-like installs map to custom instructions, and Codex .codex/rules command policy is intentionally outside the built-in behavioral rules target. Unsupported rule targets require an explicit custom adapter instead of an inferred folder.

Core Commands

Command	Meaning
agentwheel search <query>	Search configured registries and the public enriched/Vercel catalogue; supports stable JSON output for agent reranking.
agentwheel add <source>	Validate and save a package entry in .agentwheel/config.json; does not touch runtimes.
agentwheel plan [name-or-source]	Preview what install would reconcile without writing; supports --profile <name> and --json.
agentwheel install	Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default.
agentwheel install <name-or-source>	Ensure semantics: configured name/source scopes the install; a new source is added and installed.
agentwheel update [name]	Re-resolve tracking packages, then apply. A configured name preserves artifacts owned by other roots; --dependency <name-or-source> moves one tracking dependency while unrelated graph nodes stay locked.
agentwheel skill update <name>	Resolve the owning configured package and reconcile only that skill plus genuine transitive composition inputs; sibling artifacts stay byte-identical and retain manifest/lock state.
agentwheel uninstall <name-or-source>	Remove a configured package from runtimes and config.
agentwheel uninstall <name> --keep-files	Remove from config/manifest while leaving runtime files unmanaged.
agentwheel status	Show configured packages, manifest/lock presence, and install state. For a named fleet, use --fleet <fleet-id> --profile <name>; --fleet <fleet-id> --all uses profile all when present.
agentwheel ownership handoff <type/name>	Transfer one manifest entry to a different workspace root after exact owner, hash, and revision checks; runtime content is not rewritten.
agentwheel mcp retire <package>	Preview removal of one exact legacy MCP contribution under an explicitly selected install-state key; add --apply only after review.
agentwheel doctor	Check runtime setup and suggest explicit companion/selected skill install commands when they are missing.
agentwheel cache prune	Preview old Git source snapshots; add --apply to remove them while retaining locked commits.

Mental model: install = make what is declared true. update = move tracking declarations forward, then make them true. Scoped installs do not remove files owned only by other configured packages; run a full agentwheel install to reconcile those removals.

When a managed fleet profile moves between workspace roots, preview a single-artifact ownership handoff first. The dry-run prints the current artifact hash and manifest revision:

agentwheel ownership handoff skills/example-skill \
  --adapter codex --user --target-root "$HOME" \
  --from-workspace-root /old/fleet/profile \
  --to-workspace-root /new/fleet/profile \
  --dry-run

Apply the same command with the reviewed values added as --expected-hash <sha256> and --expected-revision <sha256>. Agentwheel takes the target apply lock, rejects a pending apply journal, rechecks the old owner and the live artifact hash, then atomically updates only the install manifest. Run one target at a time; named SSH agents use the same contract through --agent.

Use --from-unknown-owner instead of --from-workspace-root for an entry recorded as workspace:unknown. A plain file or directory whose runtime no longer matches the recorded hash is refused unless --carry-drift is passed: the dry-run prints the runtime hash, the apply also needs --expected-runtime-hash <sha256>, and the manifest keeps the recorded hash so the next install still reports the drift. Merge and managed-block entries never carry drift.

For a one-time MCP rename, keep the legacy artifact in a dedicated cutover workspace rather than the canonical desired-state profile. Set the legacy manifest stateKey on its named agent, then preview one runtime at a time:

agentwheel mcp retire legacy-mcp --agent legacy-codex \
  --from-workspace-root /old/cutover/workspace --dry-run
agentwheel mcp retire legacy-mcp --agent legacy-claude --dry-run

The package must render exactly one MCP artifact. The command accepts only an exact JSON MCP server object or exact Codex TOML MCP sections, rejects unexpected manifest entries or owners, and revalidates the exact contribution under the apply lock. It removes only the selected legacy server; sibling servers and user configuration remain. The command previews by default. A later runtime approval must use the same command with --apply instead of --dry-run.

When stable and legacy manifests disagree, update --recover-legacy-state explicitly uses recovered stable state while preserving legacy evidence. Preview the same command with --dry-run first.

For a surgical dependency update, start with a dry-run:

agentwheel update --dependency shared-core --agent lab-codex --dry-run
agentwheel update --dependency github:your-org/shared-core --agent lab-codex

The selector must uniquely match a locked tracking dependency by package name, dependency alias, node id, or source. Agentwheel advances that node and its required tracking closure, writes the complete graph lock, and applies atomically. Configured selections stay unchanged, so this mode rejects package arguments, --select, --skill, --frozen-lock, and --offline. A later full update can advance the remaining graph.

Quick Start

agentwheel init
agentwheel add github:your-org/agent-pack --adapter openclaw --installation-type local --mode tracking
agentwheel plan
agentwheel install

Artifact Discovery

Search configured registries and the complete public catalogue with one command:

agentwheel search "conversation memory"
agentwheel search "telegram integration" --type skill
agentwheel search "message recall" --json --limit 10

Use --scope registry, --scope enriched, or --scope vercel to restrict a query. The default --scope all combines every source, deduplicates equivalent artifacts, and reports every provenance plus the safe installation route.

The optional agentwheel-discovery skill notices capability gaps during normal work, uses the verified semantic catalogue index, reranks results against the original request, and suggests at most three artifacts. It can read one instruction skill with agentwheel try before installation. Search and trial never install or change configuration by themselves.

Registry maintenance remains available through agentwheel registry update and agentwheel registry list. Registry short names continue to resolve during add/install.

Source Inputs

Agentwheel can install from explicit local paths, Git sources, catalogue short names, provider indexes, and generated OpenPack wrappers:

agentwheel install ./my-pack --adapter codex --local
agentwheel install github:your-org/agent-pack --adapter codex --user
agentwheel install skillkit:owner/skill-name --adapter claude --user
agentwheel install vercel:owner/skill-name --adapter codex --user
agentwheel install mcp-registry:publisher/server-name --adapter claude --local
agentwheel install clawhub:@openclaw/whatsapp --adapter openclaw --local

Private GitHub sources

OpenPack manifests stay portable and do not contain personal GitHub accounts or tokens. Configure local gh accounts through a user-local auth profile; see Git Authentication for the configuration format and runtime behavior.

mcp-registry:<server-name> reads the public MCP Registry and stages a generated OpenPack package only when the server exposes a safe unauthenticated streamable-http remote. Entries that require secret headers or only publish native package instructions remain discovery-only until they are wrapped by an explicit OpenPack source.

clawhub:<package-name> reads ClawHub package metadata and stages a generated OpenPack plugin wrapper for OpenClaw. The generated artifact plans openclaw plugins install --force clawhub:<name>; plugin execution remains opt-in through Agentwheel's plugin execution controls.

Runtime reloads or service restarts remain a separate opt-in gate. Configure structured reloadCommands on an agent or profile runtime, then pass --reload-runtimes (or the alias --restart-runtimes) with an apply command that executes plugins:

agentwheel install --profile extra-message-policy --execute-plugins --reload-runtimes

Submit a public resource to the catalogue without editing index.json by hand:

npx agentwheel@latest registry publish https://github.com/owner/repo \
  --description "Reusable skills and rules for coding agents." \
  --tag skills,rules

The command normalizes the source, drafts the registry JSON, prints a verification command, and prints a prefilled GitHub submission URL you can review before sending.

Contributor install from source:

git clone https://github.com/NestDevLab/agentwheel
cd agentwheel
pnpm install
pnpm build
pnpm link --global

plan, install --dry-run, and update --dry-run show what would change before runtime files are written. uninstall removes clean managed files and keeps drifted files by default; use agentwheel uninstall --force only when you also want to remove drifted managed files.

agentwheel checks npm for newer versions at most once every 24 hours and prints a non-blocking stderr warning when an update is available. Disable it with --no-update-check or AGENTWHEEL_NO_UPDATE_CHECK=1.

Companion Skill Doctor

Agentwheel ships two optional companion skills in github:NestDevLab/agentwheel:

• skills/agentwheel provides explicit search, setup guidance, safety rules, and artifact management.
• skills/agentwheel-discovery proactively notices capability gaps, suggests up to three matches, and offers a read-only skill trial before installation.

Install only the management skill when proactive recommendations are unwanted. Install both when you want Agentwheel to surface reusable capabilities during normal work.

The CLI never installs the companion skill silently into runtime folders. Use doctor to check the selected runtime and print the exact preview and install commands when a skill is missing:

agentwheel doctor --adapter copilot --user
agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel --dry-run
agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel
agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel-discovery --dry-run
agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel-discovery

doctor also accepts explicit skill checks and machine-readable output. In Syncwheel-managed workspaces, it automatically includes the Syncwheel skill so Git/worktree maintenance guidance can be installed into the active agent runtime when needed.

agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel --json
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel --dry-run
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel

Run the dry-run first when you want to inspect the target path and conflict status before writing.

Runtime Targeting

Normal use does not need --target-root. Run agentwheel inside a runtime folder and it detects the target:

cd ~/.openclaw
agentwheel install

Explicit source installs with an explicit adapter default to user-level artifacts, so this works as a global install:

agentwheel install github:your-org/agent-pack --adapter codex,claude

Use --local for the current directory or -t/--target-root <project> for another project/workspace. Use exactly one of --user, --local, or --fleet <fleet-id> when desired state scope matters. -i/--installation-type <type> selects the runtime's install layout inside that scope. For example, Codex local skills install into .agents/skills, while Codex user skills install into ~/.agents/skills. Named fleets are optional; ordinary user and local work does not require a fleet registry.

When adding a new source this way, Agentwheel saves one package entry per adapter so later installs do not collapse Codex and Claude state into the same config entry.

For a control-plane setup, register a named fleet and define its agents and profiles in that fleet's config. A fleet is selected explicitly with --fleet <fleet-id>; no fleet has global priority and Agentwheel never merges desired state from user, local, and fleet scopes.

{
  "schemaVersion": 3,
  "fleetId": "example-fleet",
  "packages": [
    {
      "name": "core-agent-pack",
      "source": "github:example-org/core-agent-pack",
      "driver": "git",
      "adapter": "codex",
      "installationType": "local",
      "mode": "tracking"
    }
  ],
  "agents": {
    "lab-codex": {
      "adapter": "codex",
      "installationType": "local",
      "root": "/workspace/project",
      "transport": "local"
    }
  },
  "profiles": {
    "daily": {
      "runtimes": [
        { "agent": "lab-codex" }
      ]
    }
  }
}

agentwheel fleet register example-fleet \
  --root /srv/agentwheel/fleets/example-fleet \
  --required-package core-agent-pack
agentwheel fleet list
agentwheel fleet show example-fleet
agentwheel install --fleet example-fleet --agent lab-codex
agentwheel install --fleet example-fleet --all
agentwheel update --fleet example-fleet --profile daily --dry-run
agentwheel install --fleet example-fleet --profile daily
agentwheel status --fleet example-fleet --profile daily
agentwheel install --all-detected

If another scope already owns an intended runtime path, the plan fails closed even when the bytes match. Use the separate normalization command to preview an explicit ownership transfer, review its plan digest, and apply only that same plan. Fleet selection never implies takeover.

agentwheel fleet normalize example-fleet --from user --package core-agent-pack --json
agentwheel fleet normalize example-fleet --from user --package core-agent-pack \
  --plan-digest <reviewed-sha256> --apply
agentwheel fleet normalize example-fleet --from user --recover

Recovery restores the source side from a pending normalization journal after verifying that the recorded configs, manifests, and graph locks have not changed outside the transaction.

Named fleets use workspace schema v3 or newer and require a compatible Agentwheel CLI. Upgrade the CLI first, verify agentwheel --version and agentwheel fleet --help, then create the fleet config and register it. Do not edit the config to an older schema or run an older CLI against it.

SSH targets use the same manifest and drift model as local targets. Planning reads the remote install manifest and hashes remote files before deciding whether a file is up to date, drifted, or conflicting. SSH hosts need ssh, tar, and node available on PATH.

Target resolution order is exact: --target-root wins, then --agent, then auto-detect from the current directory, then fallback to the current directory. --all-detected is an explicit escape hatch for applying to every runtime marker found in the current directory or --target-root; --all remains reserved for configured agents.

Target state identity

Graph-backed installs keep two target fingerprints with different purposes:

• The full target fingerprint records rendering inputs in the graph lock. Adapter code, adapter configuration, and adapter module changes therefore remain visible and can produce a real update.
• The stable state fingerprint selects the graph lock, install manifest, source lock, and apply journal. It is derived from the contribution scope and effective destination, including the normalized install root and a structured local or SSH endpoint. Adapter implementation evolution that resolves to the same destination reuses the installed state instead of orphaning it.

Changing an artifact destination within the same effective install root is handled as a planned transition from the old path to the new path. Changing the effective install root, local/SSH kind, or SSH endpoint selects a different target state. SSH state identity requires an explicit host; a display label is not endpoint identity.

State created by an older Agentwheel release may be named with the full target fingerprint. For a local target, Agentwheel adopts that state only when one canonical graph lock, its v2 install manifest, the contribution owner, and target details agree. When a tracked graph lock has advanced past the installed manifest, Agentwheel uses the manifest only as prior runtime state and resolves the graph fresh; it never treats that newer lock as the previously installed graph. Mixed digests inside the owned contribution still fail closed. A supported install or uninstall carries an explicit migration and revalidates the old and new state under the shared apply lock before replacing the legacy paths. An explicit stateKey remains the manifest and source-lock key while its legacy graph-lock path moves. Status, dependency inspection, uninstall, and journal commands use the same discovery rules.

Agentwheel refuses ambiguous candidates, a graph lock without its correlated manifest, or disagreeing stable and legacy state, and preserves those files for manual reconciliation. A pending apply journal that embeds and exactly correlates the missing manifest and graph state remains discoverable for recovery. Legacy SSH state is also preserved and refused because the old records do not prove which endpoint owned it.

After reviewing agentwheel ownership recovery-plan, use --recover-legacy-state only for an invalid local candidate whose historical files must remain preserved. The recovery plan ignores that candidate when constructing the new stable state; it does not authorize runtime replacement. Adopting matching unmanaged files still requires --force-conflict, while replacing differing files still requires --replace-conflict. Review the resulting plan before applying the same flags:

agentwheel plan --fleet example-fleet --agent lab-claude \
  --recover-legacy-state --force-conflict --replace-conflict
agentwheel install --fleet example-fleet --agent lab-claude \
  --recover-legacy-state --force-conflict --replace-conflict

Once the stable manifest exists, normal status and planning use it while retaining the invalid historical candidate for explicit later cleanup.

When stale ownership must be retired before the target-state migration can run, bind the retirement to the exact already-installed Fleet manifest instead of asking target-state discovery to choose it:

agentwheel ownership retire-stale \
  --from-workspace-root <missing-worktree> \
  --to-workspace-root <fleet-root> \
  --source-state-key <stale-state-key> \
  --destination-state-key <fleet-owned-state-key> \
  --fleet <fleet-id> --agent <agent> --json

The dry-run still proves exact destination coverage and runtime bytes. Apply only its emitted command, which includes the plan, source, destination, and manifest-inventory revisions. For duplicate state owned by the same registered Fleet, set both workspace roots to the Fleet root and add --from-fleet-id <fleet-id>. The planner selects only legacy paths covered by the stable Fleet manifest. For JSON deep merges it also accepts a source contribution that is an exact recursive subset of the destination contribution. Across package revisions, merge entries must identify the same package and artifact with equal source hashes; other merge contributions must match exactly. A source-only path stays in the legacy manifest; when every source entry is covered, apply removes the old manifest and source lock without changing runtime files or the stable manifest. Preserve copies of those old state files before applying a retirement when they are needed as historical evidence.

A nested, non-Fleet workspace (for example a profile checked out beneath a registered Fleet root) can inherit paths that older installs claimed under a fingerprint-only state key. Those claims name another plain workspace root, or this workspace's own root from before it was Fleet-qualified, so install refuses them as foreign. Adopt them into this workspace's stable state without --force-foreign-state, running from the workspace that owns the target:

agentwheel ownership adopt-legacy --agent <agent> \
  --source-state-key <adapter>.<installation-type>.<legacy-fingerprint> \
  --from-workspace-root <previous-owner-root> --json

The dry-run proves each moved entry: the previous owner root must hold a graph lock named by the legacy fingerprint, and for another workspace root exactly one such lock must match the entry's graph-lock digest, node, selector, and source hash. Only entries the current graph still installs at the same path with the same artifact identity move; the rest stay in the source manifest and are listed. The current graph groups packages as install does, by installation type and adapter configuration, and the command refuses when they resolve to more than one install state or when --installation-type, --adapter-config, or --adapter-module differs from what install resolves. Runtime bytes must match the recorded hash unless --carry-drift keeps that hash, so the next install reports drift instead of overwriting local changes. A path another owner still claims blocks the plan. A duplicate claim by the same previous owner is listed only when it sits under another legacy key of that root with the same proof and the same recorded artifact and hashes; run the command again with that key to retire it. Any other duplicate, including one in that root's current state, blocks the plan. Apply only the emitted command. It writes the stable manifest first and the legacy manifest second, and changes nothing else. A pending apply journal blocks the command. If an apply stops after the stable manifest was written, run the dry-run again: paths already in the stable state are then retired from the legacy key.

Core Ideas

Three places, one direction:

	Where	What
Author	the package's git repo	upstream content, never edited in place
Workspace	your repo, under .agentwheel/	config, locks, trust decisions, and customizations
Runtime	.openclaw/, ~/.claude/, .codex/, ...	generated output

Flow: author + workspace → install → runtime.

Governed mutations

Workspace schema v4 can require a full mutation reason, durable receipts, and automatic commit-after-verify revisioning for Agentwheel's mutating commands. Revision providers can use the built-in exact-path Git implementation or a strict JSON command whose absolute entrypoint is SHA-256 pinned. Runtime output remains generated state; only declared and verified repository paths are eligible for a commit.

agentwheel install --reason "Install the reviewed artifact set"
agentwheel mutation list
agentwheel mutation show <operation-id>
agentwheel mutation finalize <operation-id>
agentwheel mutation recover-runtime <operation-id>

See the v1 revision-provider specification for configuration, the JSON protocol, crash recovery, and fail-closed boundaries.

Provider-owned drafts are recorded as owned-but-unpublished, including their stack, branch, projected draft tip, and integration control commit. Agentwheel never publishes them and does not invent a publication command; inspect the durable record and follow the provider's separately documented, authorized workflow. An active-active provider check may deliberately remain blocked until then.

Packages

A package is a git repo or folder with an OpenPack manifest and a canonical layout:

// openpack.json
{
  "schemaVersion": 2,
  "name": "your-org/agent-pack",
  "version": "0.1.0",
  "provides": [
    { "type": "instructions", "path": "instructions/AGENTS.md" },
    { "type": "rules", "path": "rules" },
    { "type": "skills", "path": "skills" }
  ]
}

Install only part of a package with --select <type>/<name>. --skill <name> is a shortcut for --select skills/<name>, and selections saved during add are reused by later install and update runs.

agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex --installation-type local
agentwheel plan
agentwheel install

Package authors can mark artifacts as required. Required artifacts are always installed and cannot be deselected:

{
  "type": "rules",
  "path": "rules/core-safety.md",
  "required": true
}

Root version policy

Workspace packages can combine source movement with an npm-style release policy:

{
  "name": "agent-pack",
  "source": "github:your-org/agent-pack",
  "driver": "git",
  "mode": "tracking",
  "version": "^1.4.0"
}

mode: pinned never advances automatically. mode: tracking may advance to the newest release allowed by an exact version, ~, ^, comparator range, or *. Status always reports installed, locked, latest allowed, and latest overall versions, including newer releases outside the selected policy. Version discovery uses a 24-hour cache by default; --refresh bypasses it and --offline uses cached metadata marked stale when its TTL has expired. Git packages use semver tags as enumerable releases. A branch without tags can report a changed HEAD but cannot select an older compatible release; explicit refs and commits remain pins.

Project-owned selection exports

Workspace configuration schemaVersion: 2 can export named artifact selections. This is useful when a project owns its content and portable local profiles, while a fleet only references the project's curated selection for a remote runtime.

{
  "schemaVersion": 2,
  "exports": {
    "selections": {
      "default": {
        "select": ["skills/project-start", "skills/project-checkin"]
      },
      "remote": {
        "extends": "default",
        "add": ["skills/remote-guard"],
        "exclude": ["skills/project-checkin"]
      }
    }
  },
  "packages": [
    {
      "name": "project-workspace",
      "source": ".",
      "driver": "local",
      "adapter": "copilot",
      "mode": "pinned",
      "selection": { "export": "default" }
    }
  ],
  "agents": {
    "mac-copilot": { "adapter": "copilot", "root": ".", "installationType": "local" }
  },
  "profiles": {
    "local-mac": { "runtimes": [{ "agent": "mac-copilot" }] }
  }
}

Configured packages can opt into adapter runtimes with "runtimes": ["claude"]. Profile and named-agent plans match the declared target adapter; plain workspace commands match each package's configured adapter. Agents sharing an adapter receive the same package roots. Upgrade every member to a version supporting this field before using it in shared configuration.

The import is data-only: Agentwheel resolves the package first, then reads only exports.selections from that resolved source's .agentwheel/config.json. It never imports the source project's agents, profiles, SSH fields, adapter modules, trust policy, or other workspace settings. Initial support is intentionally limited to local and git sources, so a Git import uses the same immutable checkout as its artifacts.

A consuming fleet can reuse that selection without inheriting the project's runtime policy:

{
  "schemaVersion": 2,
  "packages": [
    {
      "name": "project-workspace",
      "source": "/workspace/project",
      "driver": "local",
      "adapter": "hermes",
      "mode": "pinned",
      "selection": {
        "export": "remote",
        "add": ["skills/fleet-only-check"],
        "exclude": ["skills/remote-guard"]
      }
    }
  ]
}

Resolution order is: exported base selection, each exported extends step, importer add, then importer exclude; exclusion wins. Required artifacts remain selected. A package may use either selection or select/legacy skills, never both, and CLI --select/--skill cannot override an imported selection.

Plans print IMPORT and SELECT audit lines with the source, export catalog hash, requested export, extension chain, additions, exclusions, and effective selectors. agentwheel plan --profile local-mac, agentwheel install --profile local-mac --dry-run, and --json expose the same audit data. The export catalog and resolved selection are recorded in graph locks, so --frozen-lock rejects config-only selection changes.

Package authors can also declare suggested companion packages. Suggestions are not installed by default; users opt in with --with-suggestions for all suggestions relevant to selected artifacts, or --suggestion <alias> for one named suggestion. The choice is saved when used with add or install <source>.

agentwheel add github:your-org/agent-pack --skill triage --with-suggestions --adapter codex --local
agentwheel plan --skill triage --with-suggestions
agentwheel install github:your-org/agent-pack --skill triage --suggestion brainstorming --adapter codex --local

Dependencies And Composition

OpenPack packages can depend on other packages and compose shared markdown fragments:

{
  "schemaVersion": 2,
  "name": "your-org/agent-pack",
  "version": "1.0.0",
  "requires": {
    "core": {
      "source": "github:your-org/core-pack",
      "version": "^1.2.0",
      "select": ["rules/safe-actions.md", "fragments/risk.md"]
    }
  },
  "suggests": {
    "brainstorming": {
      "source": "vercel:skills.sh/example/agent-skills",
      "select": ["skills/brainstorming"],
      "reason": "Generate options before converging."
    }
  },
  "provides": [
    { "type": "fragments", "path": "fragments" },
    {
      "type": "skills",
      "path": "skills",
      "items": {
        "triage": { "suggests": ["brainstorming"] }
      }
    }
  ]
}

• Recursive resolution, locked. install reads the existing graph lock when present; newly added packages resolve fresh and then write a deterministic lock.
• Explicit updates. update re-resolves tracking sources and applies the new graph. Pinned packages stay on the locked graph unless their declaration changes.
• Fragment composition. Markdown files can transclude shared fragments with <!-- openpack:include fragments/review-style.md --> or cross-package aliases such as core:fragments/risk.md.
• Trust. New transitive sources prompt before install. Pre-approve with --trust <glob> or --yes, set a workspace trust policy, and manage persisted decisions with agentwheel trust.
• Suggested companions. suggests uses the same source/selection shape as requires, but it is opt-in. --with-suggestions pulls all relevant suggestions as non-blocking optional edges; --suggestion <alias> pulls a specific suggestion and fails if that explicit suggestion cannot resolve.
• Offline & frozen installs. --offline guarantees zero network; --frozen-lock hard-fails if resolution would differ from the lock.
• Introspection. agentwheel deps tree prints the resolved graph (source resolution may refresh incidental local caches but does not recover runtime journals or persist trust); agentwheel deps why <selector> explains why an artifact is installed.

Meta-packages (packs)

OpenPack v2 packages can omit provides when they declare at least one dependency. These meta-packages install nothing of their own; they aggregate curated selections from other packages. Uninstalling a meta-package removes the dependencies it pulled in unless those dependencies are still owned by another configured package.

{
  "schemaVersion": 2,
  "name": "test/meta-pack",
  "version": "0.1.0",
  "requires": {
    "dep": { "source": "../dep-a", "select": ["rules/a.md"] }
  }
}

Source Overrides

Use package-level overrides when a workspace intentionally wants one selected source to replace an artifact that arrives from another package, such as a forked skill replacing the same skill pulled in by a meta-package. Overrides are explicit; package array order never decides precedence.

{
  "schemaVersion": 1,
  "packages": [
    {
      "name": "nestdev-must-have-core",
      "source": "github:NestDevLab/agent-must-have#core",
      "driver": "git",
      "adapter": "codex",
      "installationType": "local",
      "mode": "tracking"
    },
    {
      "name": "agent-toolkit-nestdev",
      "source": "github:example-org/agent-toolkit#main",
      "driver": "git",
      "adapter": "codex",
      "installationType": "local",
      "mode": "tracking",
      "select": [
        "rules/self-improve-on-correction.md",
        "skills/self-improve"
      ],
      "overrides": [
        "github:example-upstream/agent-toolkit::rules/self-improve-on-correction.md",
        "github:example-upstream/agent-toolkit::skills/self-improve"
      ]
    }
  ]
}

The source::type/name selector identifies the artifact to replace. github:owner/repo matches that repository at any ref; add #main or another ref to narrow it. The replacing package must select exactly one artifact with the same type/name, and the override must match exactly one losing artifact. Otherwise planning fails instead of hiding a collision.

The same declaration can be created from the CLI:

agentwheel add github:example-org/agent-toolkit#main \
  --skill self-improve \
  --override 'github:example-upstream/agent-toolkit::skills/self-improve'

agentwheel plan, agentwheel deps tree, and agentwheel deps why print OVERRIDE lines for these decisions, and graph locks store them for review.

Migrating an existing legacy package takes one command:

agentwheel package migrate

Customizing Without Getting Overwritten

Drift detection blocks accidental edits to generated runtime files. Intentional changes live under .agentwheel/:

• Layer local instructions with agentwheel remember.
• Add separate local artifacts under .agentwheel/additions.
• Override content for an upstream item under .agentwheel/overrides.
• Override source precedence with package overrides when a forked source should replace a colliding artifact from another package.
• Eject an item into .agentwheel/ejected when you want local ownership.

Custom And Private Runtimes

A runtime adapter is a config with capabilities and paths. Internal runtimes do not need to be published:

{
  "name": "myco-internal",
  "targets": {
    "instructions": {
      "local": { "dest": ".myco/context/AGENTS.md" }
    },
    "rules": {
      "local": { "dest": ".myco/policy/rules" }
    },
    "skills": {
      "local": { "dest": ".myco/lib/skills" },
      "user": { "root": "home", "dest": ".myco/skills" }
    }
  }
}

agentwheel install ./my-pack --adapter-config ./myco-internal.jsonc

For adapter behavior that needs code, load a programmatic adapter module:

agentwheel install ./my-pack --adapter-module ./myco-adapter.js

Built-in runtime targets:

Runtime	Native supported targets
OpenClaw	local: skills/, .openclaw/plugins/; user: ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/workspace-subagents/<name>/AGENTS.md, ~/.openclaw/skills, ~/.openclaw/openclaw.json; no built-in rules target
Claude Code	local: CLAUDE.md, .claude/skills, .claude/rules, .claude/commands, .claude/agents, .claude/plugins, .mcp.json, .claude/settings.json; user: ~/.claude/... except project MCP; rules are behavioral/path-scoped
Codex CLI	local: AGENTS.md, .agents/skills, plugins/, .codex/agents, .codex/config.toml, .codex/hooks.json; user: ~/.codex/AGENTS.md, ~/.agents/skills, ~/.codex/plugins, ~/.codex/agents, ~/.codex/config.toml, ~/.codex/hooks.json; no built-in rules target; generic settings are planned, not implemented
Hermes	local: AGENTS.md; user: ~/.hermes/SOUL.md, ~/.hermes/skills, ~/.hermes/plugins, ~/.hermes/config.yaml; rules require explicit adapter config
GitHub Copilot CLI	local: .github/copilot-instructions.md, .github/instructions, .github/prompts, .github/skills, .github/plugins, .github/agents, .github/mcp.json, .github/hooks, .github/settings.json; user: ~/.copilot/copilot-instructions.md, ~/.copilot/instructions, ~/.copilot/skills, ~/.copilot/plugins, ~/.copilot/agents, ~/.copilot/mcp-config.json, ~/.copilot/hooks, ~/.copilot/settings.json; rule-like artifacts map to instructions

Docs

• install.md — AI-agent handoff for installing Agentwheel and the companion skill.
• AGENT.md — concise operating guide for AI agents using Agentwheel.
• llms.txt — LLM-oriented map of the public docs.
• docs/spec/openpack.md — OpenPack package spec.
• docs/fleet-config.md — named agents, SSH targets, and profiles.
• docs/design/federated-fleet-clusters.md — federating autonomous workspaces under one doctor/update control plane.
• docs/design/artifact-harness-compatibility.md — artifact/harness compatibility matrix and rule semantics.
• Resource catalogue: https://www.nestdev.it/agentwheel/catalogue.html.
• DESIGN.md — architecture and module layout.
• LIFECYCLE.md — publish, install, update, and customization model.

License

See LICENSE.