A plugin bundles skills, slash commands, agents, hooks, MCP server configurations, and LSP server configurations into one installable unit.
A plugin is a directory that holds any combination of these components:
- Skills -- a
skills/directory of SKILL.md files - Slash commands -- a
commands/directory of command files - Agents -- an
agents/directory of agent definitions - Hooks -- a
hooks/hooks.jsonfile of lifecycle hooks. Plugin hooks also receiveAINXT_PLUGIN_ROOTandAINXT_PLUGIN_DATA(see the Hooks guide for every environment variable passed to hooks). - MCP servers -- a
.mcp.jsonfile of server configurations - LSP servers -- a
.lsp.jsonfile of language server configurations
If a plugin includes a plugin.json manifest, the manifest can override paths or add metadata; otherwise components load from the convention directories. The manifest is optional: without one, ainxt discovers the components above from their standard directories.
For example, a team-tools plugin might include a deploy skill, a code-review agent, pre-commit hooks, and a Linear MCP server. Install them together in one step.
Plugin hooks receive two environment variables beyond the standard ones set for every hook:
| Variable | Description |
|---|---|
AINXT_PLUGIN_ROOT |
Absolute path to the plugin's installed directory. |
AINXT_PLUGIN_DATA |
Absolute path to the plugin's writable data directory, for plugin state, caches, and logs. |
ainxt sets these values and overrides any value you declare for the same key in the hook JSON's env map. (ainxt also sets the CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA aliases for compatibility.) See the Hooks guide for every environment variable passed to hooks.
ainxt discovers plugins from these locations, in priority order:
| Location | Scope | Trust |
|---|---|---|
_meta.pluginDirs (session/new / session/load) |
Session -- loaded for that session only | Trusted automatically |
--plugin-dir (CLI flag, ainxt agent) |
Process -- loaded for that agent process only | Trusted automatically |
.ainxt/plugins/ |
Project -- shared with the team through version control | Requires trust |
~/.ainxt/plugins/ |
User -- personal plugins for every project | Trusted automatically |
[plugins].paths (config) |
Custom directories you add in config.toml |
Depends on location |
ainxt also reads the .claude/plugins/ equivalents for compatibility. When two plugins share a name, the higher-priority location wins.
The Agent SDKs load per-session plugins through AinxtOptions.plugins, which arrives as _meta.pluginDirs on session/new and session/load; because the caller controls the directory, these plugins are always trusted -- their hooks and MCP servers activate without a prompt, and they never persist beyond the session. The --plugin-dir flag is the process-wide equivalent for direct CLI use (repeatable: ainxt agent --no-leader --plugin-dir A --plugin-dir B stdio); it applies to dedicated agent processes only and is ignored in leader mode (the shared leader discovers its own plugins).
| Action | Opens |
|---|---|
Ctrl+L (from any pane; non–VS Code family) |
Plugins tab |
/plugins (any terminal; required on VS Code family) |
Plugins tab |
The modal has five tabs: Hooks, Plugins, Marketplace, Skills, and MCP Servers. Switch tabs with Tab (forward) or Shift+Tab (backward). The /hooks, /marketplace, /skills, and /mcps commands each open the modal on the matching tab.
Press Enter to expand a plugin row and show its details:
- Name and version
- Scope --
cli,project,user,custom path, or the marketplace source name - Skills -- names or count
- Agents -- names or count
- Hooks -- count
- MCP servers -- count (or
blockedwhen the plugin is not trusted) - Description and path
Use these keys in the Plugins tab:
| Key | Action |
|---|---|
r |
Reload all plugins |
a |
Add a plugin from owner/repo, a URL, or a local path |
Space |
Enable or disable the selected plugin |
x |
Uninstall the selected plugin |
f |
Filter by status (all, enabled, or disabled) |
Enter |
Expand or collapse plugin details |
/ |
Search plugins by name |
Browse and install plugins from your configured marketplace sources.
Use these keys in the Marketplace tab:
| Key | Action |
|---|---|
i |
Install the selected plugin |
d |
Uninstall the selected plugin |
a |
Add a marketplace source |
x |
Remove the selected source and its plugins |
r |
Refresh marketplace sources |
u |
Update the selected marketplace plugin |
Enter |
Expand or collapse a source or plugin |
/ |
Search plugins by name |
Component summaries on list rows and per-category component details in the
expanded view appear only for marketplaces that publish a plugin-index.json
catalog.
Manage plugins without starting an interactive session.
ainxt plugin list [--json] [--available] # List installed plugins (--available requires --json)
ainxt plugin install <source> --trust # Git URL, GitHub shorthand (user/repo), or local path
ainxt plugin uninstall <name> [--confirm] [--keep-data] # Aliases: rm, remove
ainxt plugin update [<name>] # Omit the name to update all plugins
ainxt plugin enable <name>
ainxt plugin disable <name>
ainxt plugin details <name> # Show the plugin's component inventory
ainxt plugin validate [<path>] # Validate plugin.json (default: current directory)
ainxt plugin tag [<path>] [--push] [--force] [--dry-run] # Tag a release from the manifest versionRun ainxt plugin install <source> without --trust and ainxt prints the source and warns that installing will activate the plugin's hooks, MCP servers, and skills, then stops without installing. Add --trust to install it.
The <source> argument accepts:
user/repo-- GitHub shorthanduser/repo@v1.0-- pinned to a refuser/repo#subdir-- subdirectory within the repohttps://github.com/user/repo.git-- full URLgit@github.com:user/repo.git-- SSH./local-diror/absolute/path-- local directory
ainxt plugin marketplace list [--json]
ainxt plugin marketplace add <url> # Git URL, GitHub shorthand (user/repo), or local path
ainxt plugin marketplace remove <url> # Git URL or local path of a configured source
ainxt plugin marketplace update [<name>] # Omit the name to refresh all sourcesainxt plugin marketplace add my-org/team-plugins
ainxt plugin marketplace list
ainxt plugin install my-org/team-plugins --trust
ainxt plugin list
ainxt plugin updateIn an interactive session, these commands open the modal on a specific tab. They take no arguments — manage plugins from the modal or with the ainxt plugin CLI.
| Command | Opens |
|---|---|
/plugins |
Plugins tab |
/hooks |
Hooks tab |
/marketplace |
Marketplace tab |
/skills |
Skills tab |
/mcps |
MCP Servers tab |
Configure plugin directories and per-plugin state in ~/.ainxt/config.toml:
[plugins]
paths = ["~/my-plugins/custom-tools"] # Additional plugin directories
disabled = ["user/a1b2c3d4/noisy-plugin"] # Plugin IDs or names to skip
enabled = ["project/9f8e7d6c/team-tools"] # Plugin IDs or names to force onList a plugin in disabled to discover it but skip loading its components. List a plugin in enabled to activate it — plugins are disabled by default unless a CLI override or an explicit config path enables them, so add them here to turn them on. Each entry is either a plain plugin name (as shown by ainxt plugin list) or a full plugin ID in the form <scope>/<hash>/<name>.
To hide the hooks and plugins UI — the /hooks and /plugins commands and the scrollback annotations — set this in ~/.ainxt/pager.toml:
disable_plugins = trueAdd git or local marketplace sources to discover and install plugins.
Each source needs a name and either a git URL (with an optional branch) or a local path:
[[marketplace.sources]]
name = "My Team Plugins"
git = "https://github.com/my-org/plugins.git"
[[marketplace.sources]]
name = "Local Dev"
path = "~/dev/my-plugins"Add sources under extraKnownMarketplaces, keyed by name. Each entry's source is one of git (with url), github (with repo), or local (with path):
{
"extraKnownMarketplaces": {
"my-marketplace": {
"source": { "source": "git", "url": "git@github.com:my-org/plugins.git" }
}
}
}Place this file at ~/.ainxt/settings.json or ~/.claude/settings.json.
Enabling a plugin loads its skills, slash commands, and agents. Trust is separate and controls whether a plugin's code runs: even for an enabled plugin, its hooks, MCP servers, and LSP servers stay inactive until you trust it. This prevents an untrusted repository from running code on your machine.
ainxt trusts plugins from ~/.ainxt/plugins/ automatically. Project plugins in .ainxt/plugins/ require explicit trust. To trust a plugin, install it with --trust:
ainxt plugin install <source> --trustRun ainxt inspect to see every discovered plugin and what it provides:
ainxt inspect # Show plugins with their skills, agents, hooks, and MCP servers
ainxt inspect --json # Emit machine-readable JSONPlugin-provided components appear in their sections (Skills, Agents, MCP Servers, and so on) with a plugin: <name> label, so you can see where each component originates.
These keys work across every tab in the modal:
| Key | Action |
|---|---|
Tab |
Next tab |
Shift+Tab |
Previous tab |
j / down-arrow |
Move selection down |
k / up-arrow |
Move selection up |
Enter |
Expand or collapse the selected item |
/ |
Search the current tab by name |
Esc |
Clear the search, or close the modal |
Some actions, such as uninstalling a plugin, ask for confirmation. Press y to confirm or Esc to cancel.