Installing

Four commands pull things out of the registry, and they differ in what you end up owning. Picking the wrong one is the most common way to get stuck, so it is worth thirty seconds up front.

install — use someone's capability

axon install @axon/github
axon i @axon/github          # same thing

Run from an agent project. The module becomes a dependency of that agent, and three things happen:

• the module source is exposed at node_modules/@scope/name
• its npm dependencies are merged into the agent's package.json and materialised
• any environment keys it declares are printed for you to fill in

Installed modules are discovered automatically — nothing to register, no import to write. Their tools appear in the agent's manifest at next boot, namespaced under the module (github.openPr, never a bare openPr).

modules/ stays for local, relative-path modules you are writing yourself. Registry modules live in node_modules like any other dependency, because that is what they are.

Identifiers are always scoped. @axon/github, never github — every artifact carries its scope as part of its identity, so a bare name resolves to nothing.

If the module declares required env vars, put local values in the agent's .env; deployed values are read from that same file at deploy time. See Environment.

clone — read or modify the source

axon clone @axon/github
axon clone @axon/github ./tools

Downloads the artifact as a standalone project you can edit, keeping its original identity. Use it to read how something works, or to run a modified copy locally.

You cannot publish a clone — the scope belongs to someone else, and publishing would fail on ownership. That is what fork is for.

fork — make it yours

axon fork @axon/github --as @me/github

The same download, with the package identity rewritten to a scope you own. The rename is the whole difference, and it is the tedious part — publishing a clone means editing the manifest, the config, and every internal reference by hand, which is easy to half-finish.

axon fork @axon/github --as @me/github
cd github
axon prepare
axon publish

Extensions install differently

axon ext install @axon/mocha-theme

An extension shapes your terminal, not an agent — so it installs machine-wide into your profile rather than into a project, and it works from any directory. Themes, commands, keybinds and status lines all arrive this way.

The bare axon install recognises which you meant: if the name resolves to an extension it routes there, otherwise it installs a module into the current agent.

Finding things

axon search obsidian --modules
axon list --kind cognet --sort installs

search and list share every filter — --kind, --scope, --sort, --limit. Or browse the registry from the terminal with %, which installs into the focused agent on Enter.

Removing

axon uninstall @axon/github

Mirrors install and routes the same way, except it decides from what your project and profile declare rather than by asking the registry. That is both faster and more correct — uninstalling something already removed from the registry still has to work.