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. Rename it in package.json to a scope you own first.

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 search --kind cognet --sort installs

search takes 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.