{"id":49896933,"url":"https://github.com/alexsmedile/apm","last_synced_at":"2026-05-16T00:28:15.866Z","repository":{"id":350886831,"uuid":"1203156403","full_name":"alexsmedile/apm","owner":"alexsmedile","description":"Agent Package Manager: Local-first CLI package manager for AI agent prompt files and skills. Write an agent once, install it everywhere.","archived":false,"fork":false,"pushed_at":"2026-05-05T23:28:19.000Z","size":552,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T01:29:08.145Z","etag":null,"topics":["ai-agents","bash","claude-code","cli","codex","cursor","prompt-management"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexsmedile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-06T19:22:22.000Z","updated_at":"2026-05-05T23:28:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexsmedile/apm","commit_stats":null,"previous_names":["alexsmedile/apm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexsmedile/apm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexsmedile%2Fapm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexsmedile%2Fapm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexsmedile%2Fapm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexsmedile%2Fapm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexsmedile","download_url":"https://codeload.github.com/alexsmedile/apm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexsmedile%2Fapm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33085696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bash","claude-code","cli","codex","cursor","prompt-management"],"created_at":"2026-05-16T00:28:14.993Z","updated_at":"2026-05-16T00:28:15.859Z","avatar_url":"https://github.com/alexsmedile.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# apm — Agent Package Manager\n_Write an agent once. Install it everywhere._\n\n**A local-first CLI package manager for AI agent and skill files.**\n\n`apm` syncs your library of agent definitions and manages installation into the agent runtimes it currently verifies end-to-end.\n\nIt handles: `install`, `diff`, `update`, `import`, and optional **GitHub sync** — all with atomic writes, locking, and backups.\n\n| Status | Targets |\n|---|---|\n| **Managed now** | Claude Code agents and skills, Gemini CLI agents, Codex skills, Windsurf skills, `agents-dir` generic store |\n| **Coming soon / not yet verified end-to-end** | Cursor, Continue, Codex agents, Windsurf rules, Gemini skills, generic export UX |\n\n\u003e This tool is under active development. It may contain bugs. Always back up your data.\n\n## Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003ch3\u003e📚 One Library, All Tools\u003c/h3\u003e\nDefine an agent once in your library. Install it to the runtimes `apm` currently verifies — with the right format for each.\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003ch3\u003e🔄 Sync State Tracking\u003c/h3\u003e\nAlways know what's installed, what's outdated, and what's drifted. \u003ccode\u003eapm list\u003c/code\u003e gives you a full picture at a glance.\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003ch3\u003e📥 Import Agents\u003c/h3\u003e\nAlready have agents scattered across tool directories? \u003ccode\u003eapm import\u003c/code\u003e brings them into your library with a single command.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003ch3\u003e☁️ GitHub Sync\u003c/h3\u003e\nBack up and share your library via GitHub. Monorepo or per-agent mode. Push, pull, and diff from the CLI.\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ch3\u003e🛡️ Safe by Default\u003c/h3\u003e\nAtomic writes, file locking, and automatic backups before every destructive operation. No silent overwrites.\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ch3\u003e🗂️ Categories\u003c/h3\u003e\nTag agents with a category and install entire groups at once. Keep your library organized as it grows.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Problems apm solves\n\n| Without apm | With apm |\n|---|---|\n| ❌ You copy-paste the same agent prompt into multiple coding tools — and they drift apart over time. | ✅ One source of truth in your library. Install to supported runtimes with one command. |\n| ❌ You edit an agent directly in `~/.claude/agents/` and forget which version is canonical. | ✅ Library always wins. Runtime is treated as a deploy target, never the source. |\n| ❌ You have no idea which installed agents are outdated or missing after switching machines. | ✅ `apm list` shows sync state for every agent — in-sync, outdated, ready, or unmanaged. |\n| ❌ You accumulate random `.md` files in your agents directories with no record of where they came from. | ✅ Every installed file is stamped with `apm.id`, platform, and install timestamp. |\n| ❌ Updating an agent means manually finding and overwriting files across multiple tools. | ✅ `apm update` reinstalls every outdated agent in one shot, with backups. |\n\n## Install\n\n```bash\ngit clone https://github.com/alexsmedile/apm.git\ncd apm\nbash install.sh          # links apm into ~/.local/bin\napm setup                # configure library path, platform, optional GitHub\n```\n\n**Requirements:**\n- bash 4+\n- python3 + PyYAML (`pip3 install pyyaml`)\n- git (optional, for GitHub sync)\n\n## Quickstart\n\n```bash\napm list                 # show all agents and sync state\napm install agent-mentor   # install agent to runtime (~/.claude/agents/)\napm link agent-mentor      # symlink runtime file directly to split instructions\napm diff agent-mentor      # compare library vs runtime\napm update               # reinstall all outdated agents\napm import               # import unmanaged runtime agents into library\n\n# Skills\napm -s list                                        # list all skills and sync state\napm -s find browser-use                            # search library\napm -s -p cc install browser-use                   # install to claude-code\napm -s -p cc,agt install browser-use               # install to multiple platforms at once\napm -s -p cc install --all                         # install all ready/outdated skills\n```\n\n## Library layout\n\n`apm` supports different canonical layouts for agents and skills.\n\nAgents:\n\n```text\nagents_db/\n  agent-mentor/\n    agent-mentor.md                  # required root file\n    instructions/                    # optional\n      agent-mentor@latest.md         # optional generic active body\n      agent-mentor.cc@latest.md      # optional platform-specific body\n    versions/                        # optional snapshots/backups/history\n```\n\nAgent rules:\n- The canonical ID is the folder name.\n- The required root file is `\u003cid\u003e/\u003cid\u003e.md`.\n- `instructions/` is optional and keeps the current body split out of the root file.\n- Body resolution order is `\u003cid\u003e.\u003cplatform-alias\u003e@latest.md` → `\u003cid\u003e@latest.md` → `\u003cid\u003e_latest.md` (legacy) → root file body.\n\nSkills:\n\nPreferred monorepo-style layout:\n\n```text\nskills_db/\n  repo-name/\n    skills/\n      browser-use/\n        SKILL.md\n      shadcn/\n        SKILL.md\n```\n\nFallback direct layout:\n\n```text\nskills_db/\n  browser-use/\n    SKILL.md\n  shadcn/\n    SKILL.md\n```\n\nSkill rules:\n- `apm` prefers `skills_db/\u003crepo\u003e/skills/\u003cskill\u003e/SKILL.md`.\n- If a top-level entry has no `skills/` folder, `apm` falls back to `skills_db/\u003cskill\u003e/SKILL.md`.\n- The canonical skill ID is the skill folder name that directly contains `SKILL.md`.\n- When a repo has multiple sub-skills, register the repo once in `skills_db` — all sub-skills are auto-discovered and individually installable by ID with no extra symlinks.\n\nPlatform aliases: `claude-code→cc`, `cursor→crs`, `gemini→gmn`, `codex→cdx`, `agents-dir→agt`, `generic→gen`\n\n\u003e **About the \"agents\".** In most AI tools, \"agent\" means the tool's primary AI persona, but the `agents/` directories (`~/.claude/agents/`, `~/.cursor/agents/`, etc.) actually hold **subagents** — specialized, named agents invoked for specific tasks. `apm` manages subagents only.\n\n### Categories\n\nAdd `category: \u003cname\u003e` (or `group: \u003cname\u003e`) to any agent's frontmatter to group it:\n\n```yaml\ncategory: devtools\n```\n\nThen install the whole group at once:\n\n```bash\napm install --cat devtools\n```\n\n`apm list` shows the category column when any agents have one set.\n\n## Install target folders\n\nThe tables below list the targets `apm` currently manages and that were re-checked against current platform docs.\n\nVerified agent install targets:\n\n| Platform | Global target | Project target |\n|---|---|---|\n| `claude-code` | `~/.claude/agents/` | `.claude/agents/` |\n| `gemini` | `~/.gemini/agents/` | `.gemini/agents/` |\n| `agents-dir` | `~/.agents/` | `.agents/` |\n\nVerified skill install targets:\n\n| Platform | Global target | Project target | Behavior |\n|---|---|---|---|\n| `claude-code` | `~/.claude/skills/` | `.claude/skills/` | symlink skill dir |\n| `codex` | `~/.agents/skills/` | `.agents/skills/` | symlink skill dir |\n| `windsurf` | `~/.codeium/windsurf/skills/` | `.windsurf/skills/` | symlink skill dir |\n| `agents-dir` | `~/.agents/skills/` | `.agents/skills/` | symlink skill dir |\n\n`generic` currently means an export-only convenience target (`~/Desktop/agents-export/` by default), not a verified first-class platform integration.\n\nComing soon:\n- `cursor`: official docs currently point to `.cursor/rules` and `AGENTS.md`, not a verified `.cursor/agents/` runtime.\n- `continue`: official docs currently point to `.continue/rules`, not a subagent runtime directory.\n- `codex` agents: current Codex docs emphasize `AGENTS.md` and skills; an `agents` runtime folder is not verified here yet.\n- `windsurf` agents: Windsurf exposes rules, skills, workflows, and `AGENTS.md`; `apm` does not yet model Windsurf rules as a first-class managed target.\n- `gemini` skills: Gemini CLI documents subagents in `.gemini/agents/`, but a SKILL.md-based skill runtime is not verified here yet.\n\n## Install modes and direct symlinks\n\n`apm` supports two different symlink-based workflows:\n\n- `install` with `INSTALL_MODE=symlink`:\n  `apm` writes the generated runtime file into `~/.agents/` and symlinks the tool-specific runtime path back to that managed file. This keeps frontmatter like `apm.id`, `installed-at`, and deploy metadata intact.\n- `--mode skills install`:\n  `apm` creates a directory symlink from the selected verified skill target back to the canonical skill folder in `SKILLS_DB`.\n- `link` / `unlink`:\n  `apm link \u003cid\u003e` creates a runtime symlink that points directly at the resolved split instruction body in your library. This is useful when you want runtime to follow the library body exactly without generating a runtime wrapper file.\n\nExamples:\n\n```bash\napm install agent-mentor                     # normal copy install\nINSTALL_MODE=symlink apm install agent-mentor\napm --mode skills --platform claude-code install browser-use\napm link agent-mentor\napm link agent-mentor --as review-helper\napm links\napm unlink agent-mentor --all\n```\n\nNotes:\n- `link` resolves the active body using the normal platform precedence: `\u003cid\u003e.\u003cplatform\u003e@latest.md`, then `\u003cid\u003e@latest.md`, then the root file body.\n- If the split file does not exist yet, `apm link` can generate `instructions/\u003cid\u003e.\u003cplatform-alias\u003e@latest.md` from the root body.\n- `unlink` removes only tracked symlinks and refuses to delete regular files.\n- Plain `unlink` targets the current scope. Use `--project`, `--global`, or `--all` to be explicit when needed.\n\n## GitHub sync\n\nTwo modes:\n- **monorepo** — all agents in one repo, each in a subdirectory\n- **per-agent** — each agent has its own repo\n\n```bash\napm github connect           # configure mode, owner, repo\napm github push --all        # push everything\napm github pull agent-mentor   # pull one agent (staged by default)\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `setup` | Interactive config wizard |\n| `config` | Show resolved configuration |\n| `list` | List agents with sync state and category |\n| `status` | Count summary by state |\n| `validate [id]` | Validate agent(s) in library |\n| `diff \u003cid\u003e` | Show library vs runtime diff |\n| `install \u003cid\u003e [id…]` | Install agents, or in `-s` mode create skill symlinks |\n| `install --all` | Install every ready/outdated agent or skill |\n| `install --cat \u003cname\u003e` | Install all agents in a category (agents mode) |\n| `find \u003cquery\u003e` | Search library by name or description |\n| `scan [--dir \u003cpath\u003e]` | Find unmanaged skills in tool directories |\n| `scan autofix` | Convert managed-copy skill entries to symlinks |\n| `duplicates` | Find content-identical or redundant skills (skills mode) |\n| `link \u003cid\u003e` | Symlink agent body directly into the runtime dir |\n| `unlink \u003cid\u003e` | Remove tracked symlink(s) for an agent |\n| `links [id]` | List tracked symlinks for one agent or all agents |\n| `remove \u003cid\u003e` | Remove agent runtime file, or in `--mode skills` remove the skill symlink |\n| `update [id]` | Reinstall outdated agent(s) — omit for all |\n| `import` | Pick from unmanaged runtime agents (interactive) |\n| `import [id]` | Import specific agent, or `--all` for everything |\n| `github connect` | Configure GitHub sync |\n| `github status` | Show library vs GitHub sync state |\n| `github push \u003cid\u003e` | Push agent to GitHub, or `--all` for everything |\n| `github pull \u003cid\u003e` | Pull agent from GitHub, or `--all` for everything |\n| `github diff \u003cid\u003e` | Diff library vs GitHub |\n| _(no args)_ | Interactive REPL dashboard |\n\n### Global flags\n\n```\n--db \u003cpath\u003e        Override library path\n--platform \u003cname\u003e  Override platform (claude-code, cursor, codex, gemini, agents-dir, generic)\n                   Comma-separated for multi-platform install: -p cc,agt\n--install-mode \u003cmode\u003e  Override install mode (`copy` or `symlink`)\n--json             Machine-readable JSON output\n--dry-run          Preview without writing\n--force            Skip confirmation prompts\n```\n\n## Sync states\n\n| Symbol | State | Meaning |\n|--------|-------|---------|\n| `✓` | in-sync | Runtime matches library |\n| `⤷` | linked | Runtime is a direct symlink to the active library body or skill dir |\n| `⤸` | linked-outdated | Runtime is a symlink, but points to the wrong target |\n| `~` | outdated | Runtime installed but behind library |\n| `○` | ready | In library, not yet installed |\n| `!` | unmanaged | Runtime file with no library entry |\n| `?` | orphan | Has apm.id but library entry missing |\n| `-` | no-deploy | No deploy config for current platform |\n| `x` | collision | Canonical ID conflict |\n\n## Docs\n\n- [`docs/TUTORIAL.md`](docs/TUTORIAL.md) — practical getting-started guide for normal users\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — module boundaries and data flow\n- [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) — usability Q\u0026A and edge cases\n- [`docs/AGENT_ENTRY_SCHEMA.md`](docs/AGENT_ENTRY_SCHEMA.md) — library metadata and deploy schema reference\n- [`docs/DATABASE_LIBRARY.md`](docs/DATABASE_LIBRARY.md) — canonical database layout guide\n- [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — version history\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — how to contribute\n\n## Playground\n\nA safe, resettable test database lives in `tests/fakeagents-db/` with two fake agents (`gino`, `pino`) synced to a private GitHub monorepo at `\u003cuser\u003e/fakeagents-db`.\n\n```bash\n# One-time config setup (recreate after reboot)\nmkdir -p /tmp/apm-fake-config \u0026\u0026 cat \u003e /tmp/apm-fake-config/config.sh \u003c\u003cEOF\nAGENTS_DB=\"$(pwd)/tests/fakeagents-db\"\nAPM_PLATFORM=\"claude-code\"\nAPM_GITHUB_MODE=\"monorepo\"\nAPM_GITHUB_OWNER=\"\u003cuser\u003e\"\nAPM_GITHUB_MONOREPO=\"fakeagents-db\"\nAPM_GITHUB_BRANCH=\"main\"\nEOF\n\n# Session env\nexport AGENTS_DB=\"$(pwd)/tests/fakeagents-db\"\nexport APM_CONFIG_DIR=/tmp/apm-fake-config\nexport CLAUDE_AGENTS=/tmp/fake-rt \u0026\u0026 mkdir -p \\$CLAUDE_AGENTS\n\n# Try it out\nbash apm --platform claude-code list\nbash apm --platform claude-code install gino\nbash apm --platform claude-code github status\n\n# Reset library to committed state\ngit checkout tests/fakeagents-db/\n```\n\n## Development\n\n```bash\nmake test       # run all 9 test suites (~127 tests)\nmake lint       # static checks (bash -n, py_compile)\nmake install    # install to ~/.local/bin\nmake uninstall  # remove symlink\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexsmedile%2Fapm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexsmedile%2Fapm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexsmedile%2Fapm/lists"}