- Add internal/labels: parse and validate the optional work-repo file
agent-lib.labels.json (version 1; unlabeled items go to every client;
names match across types)
- Add "labels" to the client config: absent = no filtering, [] = unlabeled
items only; labels from the admin default config are pinned and cannot be
overridden by user, env or flag configs; a broken admin config aborts
- Filter in prepare() before planning; deselected items follow the
upstream-deletion rules (unmodified removed, modified kept + warn,
--force removes) with reason "not selected for this client's labels"
- Abort sync before any change when the labels file does not validate;
names that match no item only warn on the client
- Report the active selection in sync output and status (--json: labels
object with client, source, labels_file, not_selected, unknown_names)
- validate checks the labels file, including that every name resolves to
an own, vendored or MCP item
- Document in README ("Client labels"), fleet handoff and the proposal;
revise the "client-side selection" non-goal
- Tests: labels parser, config precedence, planner deselection, e2e for
filter/remove/keep-modified/abort/unknown names, validate
Refs: agent_lib-fh4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agent-lib
One Go binary, two roles: curator and client.
- Curator side —
agent-lib vendor …pulls external git repositories into a plain work repository underexternal/<source>/<type>/, pinned by revision, with per-source selection and collision-safe naming. Publication is nothing more thangit commit && git push. - Client side —
agent-lib syncpulls the work repository and deploys its content into the OpenCode runtime paths. Local modifications win over company updates, self-created items are never touched, and Windows toast notifications tell employees when their edits blocked an update.
No Nix, no Python, no git subprocess at runtime — a single static binary for windows/amd64, linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64.
Installation
Download the binary for your platform from the
GitHub releases, verify the
checksum, and put it on your PATH:
curl -fsSLO https://github.com/m3tam3re/agent-lib/releases/latest/download/agent-lib_linux_amd64.tar.gz
tar xzf agent-lib_linux_amd64.tar.gz
sha256sum -c checksums.txt --ignore-missing
install -m 0755 agent-lib /usr/local/bin/
agent-lib version
Fleet-managed machines receive the binary via a pinned rollout — see docs/fleet-handoff.md. There is no self-update.
From source: go build . (version is baked in via ldflags; make build uses
the git description).
Curator guide
The work repository layout:
skills/<id>/SKILL.md own skills (folder artifacts)
commands/<id>.md own OpenCode commands
agents/<id>.md own OpenCode agents
mcp/<id>.yaml own MCP fragments (never deployed by the binary)
external/<source>/<type>/ vendored content, mirrors the same four types
agent-lib.lock.json lockfile v2 — pins every source
agent-lib.labels.json optional — restricts items to labeled clients
This layout is exactly what OpenCode natively consumes — agent-lib is deliberately on the opencode standard, no conversion layer:
| Type | Canonical form |
|---|---|
| skills | <id>/SKILL.md folder (any depth, category nesting ok) |
| commands | flat commands/<id>.md |
| agents | flat agents/<id>.md |
| mcp | flat mcp/<id>.yaml (inventoried, never deployed) |
Migrating from folder-style agent repos (e.g. agents/<id>/AGENT.md
layouts): flatten agents/<id>/AGENT.md → agents/<id>.md, and move
documentation and manifests (SCHEMA.md, agents.json, README.md) out of
the typed directories. No folder support for agents/commands is planned —
adapting the source repo to the standard beats shipping a renderer.
Vendoring a source
agent-lib vendor add superpowers https://github.com/obra/superpowers/tree/main/skills
Pasted GitHub/GitLab web-tree URLs are normalized automatically. A URL
pointing directly at a type directory (e.g. …/tree/main/skills) selects
that directory as the skills root. --ref <branch-or-tag> pins a ref; the
resolved revision is pinned in the lockfile. Discovery understands the four
standard directories (skills/, commands/, agents/, mcp/); skills are
folders containing SKILL.md — found at any depth, so category-nested
layouts (skills/engineering/tdd/SKILL.md) work too, with the folder's base
name as the skill id — commands and agents are flat .md files, MCP
fragments are .yaml. A flat .md under commands/ or agents/ whose
frontmatter contains none of the definition keys (name, description,
mode, agent, model, argument-hint, temperature, permission) is
treated as dropped documentation: skipped with a recorded warning, never an
inventory entry. Everything is read-only scanned — upstream code is never
executed.
Selection rules
- Default: vendor everything (
mode: all). --include a,b,cswitches the source to include mode: only those ids arrive, and new upstream items do not arrive automatically.--exclude a,b,ckeeps all mode minus those ids — for taking the majority of a source while dropping a few items.--types skills,commands(allow-list) and--exclude-types agents,mcp(deny-list) filter whole content types. The filter is stored asexclude_typesin the lockfile and survives updates: new upstream items of an excluded type never enter the work repository.--typescovering all four types normalizes to no filter; excluding all four fails at the zero-selection guard.- Hard errors, enforced by
vendor add,vendor update,vendor selectandvalidate:allcombined with an include list → error- an exclude list without
all→ error (not supported in v2 selections) - an include or exclude entry that no longer exists upstream → error naming the item
--includecombined with--exclude→ error--typescombined with--exclude-types→ error- unknown type names → error listing
skills, commands, agents, mcp - an include entry belonging to a type the type filter excludes → error
(vendor select changes selections later — see
Changing your selection later below.)
Changing your selection later
vendor select manages the selection after the initial add — without ever
advancing the pinned revision (that is vendor update's job):
agent-lib vendor select superpowers --add tdd,brainstorm # include mode: grow
agent-lib vendor select superpowers --remove review,debug # include mode: shrink
agent-lib vendor select superpowers --remove review # all mode: move to exclude
agent-lib vendor select superpowers --types skills # replace the type filter
agent-lib vendor select superpowers --mode all # reset: take everything again
- include mode:
--addappends ids (validated against the pinned upstream — typos abort with the list of available ids),--removedrops ids and deletes their folders fromexternal/. - all mode:
--removemoves ids onto the exclude list (lockfile v2 supports exclude in all mode) and deletes their folders;--addis a hard error — everything is already selected. --types/--exclude-typesreplace the content-type filter (same semantics as onvendor add); when neither flag is passed, the stored filter stays as-is.--mode allclears include/exclude and the type filter and re-materializes the full pinned upstream, reporting what appeared.
Every select re-runs the collision checks and honors the lockfile rename map
— you can hand-add a rename for a not-yet-selected item, then --add it
under its deployed name. Failed selects mutate nothing.
Collisions and renames
Every item deploys into a flat per-type namespace. If a vendored id collides with one of your own items (or with another source's item), the operation aborts with a hard error naming both parties — before anything is written. Resolve it with an explicit, reviewable rename:
agent-lib vendor add superpowers "$URL" --rename review=superpowers-review
The on-disk folder always carries exactly the deployed name. Renaming onto another collision is an error.
Friendlier names for your users
Renames are not only for collisions — use them to give vendored items names
your colleagues recognize. vendor rename changes them at any time, without
moving the pinned revision or the selection:
agent-lib vendor rename superpowers brainstorming=ideen-sammeln tdd=test-first
agent-lib vendor rename superpowers --reset tdd # back to the upstream id
agent-lib vendor rename superpowers # list current renames
- The rename map lives in the lockfile and survives
vendor updateandvendor select. - A renamed skill gets the
name:in itsSKILL.mdfrontmatter rewritten to the new folder name (OpenCode requires both to match and shows that name). Commands and agents are renamed via their file name only. - Skill names must be 1–64 lowercase letters, digits and single hyphens
(
code-review, notCode Review). No name of any type may contain path separators or start with a dot. - Renaming an id that is not selected yet is allowed; it applies once the
item is added via
vendor select --add. - On the next
agent-lib sync, clients receive the item under the new name; the old name is removed from their machine like any upstream deletion (locally modified copies stay, as usual).
The maintenance loop
agent-lib vendor diff superpowers # read-only preview: new/changed/deleted vs selection
agent-lib vendor update superpowers # fetch latest of the pinned ref, rewrite, report
agent-lib vendor update --all # every source, reported per source
agent-lib vendor remove superpowers # delete external area + lockfile entry
In all mode new upstream items arrive automatically (and appear in the
update report); in include mode they deliberately do not — vendor diff
surfaces them as available upstream, not selected. Every update re-runs the
collision checks and honors the rename map.
Auditing
agent-lib validate # offline: rules + tree/lockfile consistency
agent-lib vendor list # sources with pin, mode, item counts
agent-lib vendor inspect <name> # full inventory with metadata + warnings
All three accept --json. The lockfile is deterministic JSON (sorted keys,
fixed indentation) — identical reruns produce identical bytes, so git diffs
stay clean.
Client guide
Employees run two commands:
agent-lib sync # pull the work repository and deploy
agent-lib status # report local state; exit 1 when updates are blocked
Both accept --repo <url> / --ref <ref> for config-free personal use —
see Configuration below.
Deployment mapping (OpenCode target):
| Type | Destination |
|---|---|
| skills | ~/.agents/skills/<id>/ (whole artifact folders) |
| commands | ~/.config/opencode/commands/<id>.md |
| agents | ~/.config/opencode/agents/<id>.md |
| mcp | never deployed — stays under fleet-controller merge |
Sync semantics (three-state)
Sync plans before it mutates. For every item the planner compares the repository, the local manifest and the on-disk content:
- new item → deploy
- managed & unmodified, upstream changed → update
- managed & locally modified → skip + warn — your version stays
- on disk but never deployed by us → leave + warn — self-created items are safe by construction
- upstream deleted & unmodified → remove
- upstream deleted & modified → skip + warn — your version stays
With --force the two skip cases turn into update and remove —
the repository version wins over local modifications. Unmanaged items
(leave + warn) are never touched, even with --force; neither are paths
occupied by items agent-lib never deployed.
Sync is idempotent (a second run is a byte-level no-op) and fails cleanly:
an unreachable repository never leaves a half-deployed machine. The default
branch is resolved from the remote's advertised HEAD, so a sync without
--ref always tracks the server's current default branch — even after the
cache has been re-fetched many times.
Configuration
The repository to pull comes from the first source that provides one:
--repo <url>flag (works with no config file at all)--config <path>flagAGENT_LIB_CONFIGenv- user-level config (personal machines)
- admin-protected platform default (fleet rollout)
| Source | Linux / macOS | Windows |
|---|---|---|
| user-level config | $XDG_CONFIG_HOME/agent-lib/config.json (default ~/.config/agent-lib/config.json) |
%AppData%\agent-lib\config.json |
| admin default | /etc/agent-lib/config.json |
%ProgramData%\agent-lib\config.json |
--repo overrides a repo_url from any discovered config; --ref narrows it
to a branch or tag. When no config exists anywhere, the error lists every
searched location, a minimal working example, and the --repo shortcut.
{
"repo_url": "https://git.example.com/company/agent-content.git",
"ref": "main",
"token": "<read-only deploy token>",
"token_user": "oauth2"
}
The token is used for basic auth only. It never appears in the lockfile, the
manifest, logs or error messages. On --repo runs (or when the discovered
config carries no token) AGENT_LIB_GIT_TOKEN / AGENT_LIB_GIT_USER supply
credentials instead — env never overrides a configured token.
Personal quickstart (no fleet, no config):
agent-lib sync --repo https://github.com/you/your-agent-content.git
The work repository must be a committed git repository (sync pulls it read-only via go-git; local uncommitted state is ignored).
Client labels
Not every client needs every item. Restrict items to clients that carry a
matching label with an optional agent-lib.labels.json at the work
repository root:
{
"version": 1,
"labels": {
"sales": ["crm-agent", "quote-writer"],
"finance": ["officecli-financial-model", "crm-agent"]
}
}
- Unlabeled items go to every client. Only restricted items appear in the file; a new item needs no entry to reach everyone.
- Entries are deployed item names (after renames) and match across types — one entry covers a skill and a command of the same name. MCP fragment names are allowed too (fleet tooling can scope MCP from the same file; the binary never deploys MCP).
- An item under several labels reaches clients with any of them.
- Labels match
^[a-z0-9][a-z0-9-]*$; lists must be non-empty; unknown keys and unknown versions are errors.
Clients opt in through labels in their config:
labels |
Delivered |
|---|---|
| absent | everything — no filtering (default, backward compatible) |
[] |
unlabeled items only |
["sales", "lead"] |
unlabeled items plus items labeled sales or lead |
Admin-pinned: when the admin default config exists and sets labels,
that value applies no matter which config supplied repo_url — a user-level
config, AGENT_LIB_CONFIG or --config can neither widen nor drop it. An
admin config that exists but cannot be parsed aborts the run.
Sync filters before planning. An item that is no longer selected follows
the upstream-deletion rules: unmodified copies are removed, locally modified
copies are kept with a warning (--force removes them); the reason reads
"not selected for this client's labels". A labels file that does not
validate aborts the sync before any change — it never falls back to
delivering everything. Names that match no item only warn on the client;
agent-lib validate treats them as errors on the curator side.
sync and status print the active selection
(labels: sales (admin) — 12 item(s) not selected); status --json adds a
labels object with client, source, labels_file, not_selected and
unknown_names.
Labels are a relevance filter, not access control: every client still fetches the whole revision into its cache. Keep confidential material in a separately authenticated repository.
Notifications
On Windows, a toast fires when (and only when) a sync kept local
modifications or discovered unmanaged items — never for routine syncs. The
same warnings are appended to the sync log
(~/.local/state/agent-lib/sync.log on Linux, %LocalAppData%\agent-lib
on Windows) and surfaced by status. Linux/macOS notification is a no-op.
status --json is machine-readable: deployed revision, repository revision,
pending changes, skipped and unrecognized items, and a problematic_drift
flag that drives the non-zero exit code — suitable for headless drift checks.
Security / trust model
- External sources are untrusted. Discovery and vendoring never execute upstream code; only file contents are read.
- The shared read-only token limits blast radius; rotation is a single fleet run (see the handoff doc).
- MCP fragments from vendored sources are never activated by the binary; merging and vault substitution remain an explicit fleet-controller decision.
- Binary updates happen exclusively via pinned fleet rollouts — there is no self-update path to abuse.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
error: … no client config found. Searched (in order): … |
No config anywhere. Create one where the error suggests, or skip it: agent-lib sync --repo <url>. |
error: … include entry "x" not found upstream |
Typo, or the item was renamed/removed upstream. Fix the lockfile include list, or re-add with a corrected --include. |
error: … collides with own skills "x" |
Deployed-name collision. Add --rename <upstream>=<deployed> (add) or fix the rename map (update). |
validate reports tree/lockfile divergence |
Someone edited external/ by hand. Re-run vendor update <source> to restore the pinned state. |
Skill didn't update, skipped (local modifications kept): 1 |
Working as designed — you edited the deployed item. Run agent-lib sync --force to overwrite local modifications with the repository version, or delete the local copy and re-sync. |
status exits 1 |
Local modifications block repository updates (or occupy names the repo needs). See status output for the item list. |
| Sync fails with clone/fetch error | Work repository unreachable, or token expired. Previous local state remains intact; fix config/network and re-run. |
| No toast on Windows | Toasts need an interactive user session — the scheduled task must run as the logged-in user, not SYSTEM. |
| Terminal window flashes on scheduled sync (Windows) | The task runs the console program agent-lib.exe. Point it at agent-libw.exe sync from the same zip: same commands, no window, no output. |
Development
make build # build with version ldflags
make test # unit + black-box e2e (fully offline, local fixture git repos)
make lint # go vet + gofmt check
./scripts/e2e-acceptance.sh # full spec walk: 60+ assertions, offline
Release: goreleaser release on a tagged commit builds all five targets with
checksums and publishes to GitHub releases. Verify with
goreleaser release --snapshot --clean or a tagged --skip=publish dry run.
Scope and non-goals (v2)
In scope: vendoring with selection/renames into any git work repository; OpenCode-only deployment with three-state protection; toast notifications; goreleaser/GitHub release pipeline.
Client-side selection is limited to label filtering (see Client labels) — no per-client profiles, overrides or inheritance.
Not in scope: additional targets (Pi, Hermes, Crush, Amp), MCP merge/vault (fleet-controller concern), binary self-update, git submodule sources, migration tooling from the Python-era lockfile.