agentwheel

KO | EN

gitlite — search

#ai-agent #html #developer-tools #database #linux #pdf #vue #graphql #awesome #video

(★ 9)

Skills, rules, and instructions across every AI agent. One source, every agent.

File Explorer

ZIP Download

- - auto-release-tag.yml
  - catalogue-contract.yml
  - catalogue-sync.yml
  - ci.yml
  - release.yml
- - README.md
- manifest.json
- - candidate-1.png
- favicon.png
- logo-wordmark.svg
- logo.png
- catalogue-share-worker.js
- wrangler.toml
- - logo.png
- - artifact-harness-compatibility.md
  - bootstrap-skill.md
  - codex-subagents-todo.md
  - dependency-composition.claude-analysis.md
  - dependency-composition.codex-proposal.md
  - dependency-composition.gate-review.md
  - dependency-composition.md
  - dependency-composition.xhigh-review.md
  - semantic-artifact-discovery.md
- - openpack.md
- - cli-verb-redesign-0.9.md
  - revision-provider-v1.md
- .nojekyll
- catalogue.html
- favicon.png
- fleet-config.md
- git-authentication.md
- index.html
- semantic-catalogue-home.js
- semantic-search-core.js
- semantic-search-demo.css
- semantic-search-demo.js
- semantic-search-worker.js
- release-check.mjs
- release-prepare.mjs
- release-shared.mjs
- smoke-codex-local-skill.sh
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - claude.ts
  - codex.ts
  - copilot.ts
  - hermes.ts
  - index.ts
  - openclaw.ts
  - programmatic.ts
  - resolve.ts
- - client.ts
- - format.ts
  - index.ts
  - render.ts
  - serve.ts
  - update-check.ts
  - version.ts
- - markdown.ts
- - apply.ts
  - desired.ts
  - index.ts
  - instructions-block.ts
  - json-merge.ts
  - manifest.ts
  - merge-removal.ts
  - openclaw-json-merge.ts
  - path-safety.ts
  - paths.ts
  - plan.ts
  - toml-merge.ts
  - transaction.ts
  - uninstall.ts
  - yaml-merge.ts
- - customization.ts
  - fleet-normalize.ts
  - mcp-retirement.ts
  - ownership-retire-stale.ts
  - ownership.ts
  - profile.ts
  - source-plan.ts
  - trust.ts
  - update.ts
- - adapter.ts
  - artifact.ts
  - cache-identity.ts
  - catalogue.ts
  - fleet.ts
  - graph-lock.ts
  - graph.ts
  - manifest.ts
  - mutation.ts
  - package-migrate.ts
  - package-validate.ts
  - package.ts
  - registry.ts
  - selection.ts
  - workspace-composition.ts
  - workspace-owner.ts
  - workspace.ts
- - commands.ts
  - coordinator.ts
  - declarations.ts
  - index.ts
  - process.ts
  - protocol.ts
  - providers.ts
  - receipts.ts
  - repository.ts
- - members.ts
- - client.ts
  - publish.ts
- - graph-diff.ts
  - graph.ts
  - identity.ts
  - render.ts
  - semver.ts
- - reload.ts
  - target.ts
- - index.ts
- - index.ts
- - auth.ts
  - cache.ts
  - clawhub.ts
  - git.ts
  - identify.ts
  - index.ts
  - local.ts
  - mcp-registry.ts
  - skill-artifacts.ts
  - skillkit.ts
  - types.ts
  - vercel-skills.ts
- - claude-subagents.ts
  - codex-subagents.ts
  - copilot-artifacts.ts
  - customize.ts
  - openclaw-subagents.ts
  - staging.ts
- - report.ts
  - repository.ts
- - index.ts
  - local.ts
  - ssh.ts
  - types.ts
- - skill.ts
- - fs.ts
- - adapter-targets.ts
  - artifacts.ts
- - policy.ts
- - ensure-cli-build.ts
- adapter-config.test.ts
- adapter-target-skip.test.ts
- agentwheel-skill.test.ts
- agentwheel-smoke.test.ts
- artifact-compatibility.test.ts
- asset-includes.test.ts
- catalogue-search.test.ts
- catalogue-semantic-search.test.ts
- catalogue-site.test.ts
- claude-adapter.test.ts
- claude-codex-adapters.test.ts
- cli-verb-redesign.test.ts
- codex-adapter.test.ts
- composite-profile.test.ts
- copilot-adapter.test.ts
- ensure-cli-build.test.ts
- fleet-normalize.test.ts
- fleet.test.ts
- hermes-adapter.test.ts
- install-v2-b2.test.ts
- install.test.ts
- instructions-block.test.ts
- lifecycle.test.ts
- mcp-retirement.test.ts
- merge-adoption.test.ts
- mutation-policy.test.ts
- openclaw-adapter.test.ts
- openpack-b3-e2e.test.ts
- openpack-composition.test.ts
- openpack-package.test.ts
- openpack-phase-c.test.ts
- openpack-phase-d.test.ts
- openpack-phase-e.test.ts
- openpack-v3.test.ts
- ownership-handoff.test.ts
- ownership-retire-stale.test.ts
- p1-validation-guardrails.test.ts
- plan-json.test.ts
- plugin-semantic-shims.test.ts
- public-fleet-docs.test.ts
- registry-publish.test.ts
- registry.test.ts
- release-scripts.test.ts
- resolve-graph.test.ts
- resolve-identity.test.ts
- runtime-target.test.ts
- search-cli.test.ts
- semantic-search.test.ts
- serve.test.ts
- site-runtime-matrix.test.ts
- skill-frontmatter-validation.test.ts
- skill-selection.test.ts
- source-drivers.test.ts
- update-check.test.ts
- version-policy.test.ts
- version.test.ts
- wave2.test.ts
- wave3.test.ts
- workspace-composition.test.ts
- workspace-owner.test.ts
- yaml-merge.test.ts
.gitignore
AGENT.md
AGENTS.md
CHANGELOG.md
DESIGN.md
install.md
LICENSE
LIFECYCLE.md
llms.txt
openpack.json
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.json
tsup.config.ts
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">agentwheel</h1>

<p align="center"><strong>One source. Every agent.</strong></p>

<p align="center">
  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.
</p>

---

## 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.

```bash
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**

```bash
npm i -g agentwheel
agentwheel init
```

Prefer pnpm? `pnpm add -g agentwheel` works too.

**AI agent handoff**

Give an agent [`install.md`](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.

```bash
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:

```bash
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`](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:

```bash
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`.

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:

```bash
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`.

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

```bash
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

```bash
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:

```bash
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:

```bash
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](docs/git-authentication.md)
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:

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

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

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
cd ~/.openclaw
agentwheel install
```

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

```bash
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.

```jsonc
{
  "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" }
      ]
    }
  }
}
```

```bash
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.

```bash
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.

## 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.

```bash
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](docs/specs/revision-provider-v1.md) 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:

```jsonc
// 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.

```bash
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:

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

### Root version policy

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

```jsonc
{
  "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.

```json
{
  "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" }] }
  }
}
```

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:

```json
{
  "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>`.

```bash
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:

```jsonc
{
  "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
  `` 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.

```json
{
  "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.

```jsonc
{
  "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:

```bash
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:

```bash
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:

```jsonc
{
  "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" }
    }
  }
}
```

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

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

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

## License

See [`LICENSE`](LICENSE).

agentwheel

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

agentwheel

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README