Claude plugins

Atomic Agent reads plugin packages made for Claude Code, and also the Codex and Cursor plugin formats. You install a plugin with one command, and its skills, slash commands, MCP servers and hooks join the agent. You can install from a folder on disk or by name from a plugin marketplace.

Plugins are managed from the terminal with atomic-agent plugin. The desktop app has no Plugins screen yet.

Developer Preview

Atomic Agent is a Developer Preview. Command names, flags and supported plugin parts can still change between releases.

Install a plugin

From a folder:

atomic-agent plugin install ./my-plugin

From a marketplace, after you add one (see Marketplaces):

atomic-agent plugin install <name>
atomic-agent plugin install <name>@<marketplace>

The agent looks for a manifest in this order: .claude-plugin/plugin.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json, then plugin.json at the root. A folder with no manifest also works if it has the usual layout (skills/, commands/, agents/, hooks/, .mcp.json).

Installing a plugin never runs its code. Parts that would run a program on your computer stay off until you allow them. See Code stays off until you allow it.

What a plugin adds

Part	How it shows up
Skills	Listed as plugin:skill, for example review-kit:changelog. Turn one off by adding its name to skills.disabled.
Slash commands	/plugin:command in the TUI. A short /command alias works too when no built-in command, skill or other plugin uses that name.
MCP servers	Added as <plugin>-<server>. They always ask for approval, whatever trust level the plugin asks for. They start on the next agent start.
Hooks	PreToolUse and PostToolUse command hooks. See Hooks.

In plugin files, ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${PLUGIN_ROOT} and ${PLUGIN_DATA} are replaced with the plugin’s folder and its data folder. Other variables in .mcp.json, such as ${GITHUB_TOKEN}, are left as written.

Plugin state lives in <stateDir>/plugins/, by default ~/.atomic-agent/plugins/, not in config.json.

Slash commands

A plugin command is a Markdown file. When you run it, the text you type after the command fills its placeholders:

• $ARGUMENTS is everything you typed.
• $1 to $9 are single words, and single or double quotes group words, so "high priority" is one argument. $ARGUMENTS[N] is the argument at position N, counting from 0.
• If the command has no placeholder, your text is added at the end as ARGUMENTS: ....

The description and argument-hint fields from the command’s frontmatter show in the command palette. allowed-tools is read as a hint only and grants nothing. model is ignored.

Two things work differently from Claude Code. !`cmd` lines are not run and @file references are not inlined; both stay as plain text. Commands from ~/.claude/commands/ are not loaded. Plugin commands work in the TUI only.

Manage installed plugins

atomic-agent plugin list
atomic-agent plugin show <name>
atomic-agent plugin update <name>
atomic-agent plugin enable <name>
atomic-agent plugin disable <name>
atomic-agent plugin remove <name>

If the agent is running when you enable a plugin, restart it to start the plugin’s MCP servers.

Marketplaces

A marketplace is a list of plugins in a git repository or at a URL. No marketplace is added by default. Add one, then install plugins from it by name:

atomic-agent plugin marketplace add anthropics/claude-plugins-official
atomic-agent plugin install <name>

marketplace add accepts owner/repo, a git URL, a local folder, or a URL to a marketplace.json file. --ref <branch|tag> pins a branch or tag.

Command	What it does
plugin marketplace list	List added marketplaces.
plugin marketplace show <name>	List the plugins in one marketplace.
plugin marketplace update [name]	Fetch the latest list.
plugin marketplace remove <name>	Remove a marketplace. Plugins you installed from it stay.

The agent reads .claude-plugin/marketplace.json and .omp-plugin/marketplace.json. Entries that point to a folder, GitHub, a URL or git are supported. Entries that install through npm, pip or a custom command are refused. Git hooks are turned off while a marketplace is fetched. Private repositories work only if git already has your credentials.

Code stays off until you allow it

Every install and update runs a security scan of the plugin. If the scan flags something, the install asks you to confirm, or stops if the plugin looks dangerous. The scan also shows what changed in what the plugin can run.

A plugin’s local MCP servers and hooks run only after you allow its code:

atomic-agent plugin install ./my-plugin --accept-code
atomic-agent plugin allow-code <name>
atomic-agent plugin deny-code <name>

When an update changes what the plugin runs, your earlier permission is dropped and you are asked again. If there is no terminal to ask in and you did not pass --accept-code, the plugin installs with its code off. Its skills and commands still load.

Flag	What it does
--accept-code	Allow the plugin’s local programs (MCP servers, hooks) at install time.
--yes	Install even if the scan asked for confirmation.
--acknowledge-risk	Install even if the scan flagged the plugin as dangerous.
--force	Reinstall over an existing copy.

The scan is not a sandbox

Allowed plugin code runs with your user’s permissions, outside any sandbox. The scan uses simple rules and can miss things. Allow code only from plugins you trust.

Hooks

Hooks are your own scripts that run before or after the agent calls a tool. They use the same hooks.json format as Claude Code. A PreToolUse hook can block a call. A PostToolUse hook can add a note that the agent reads after the call.

Hooks come from two places:

• Your own file, ~/.atomic-agent/hooks.json (in general <stateDir>/hooks.json). The agent re-reads it when it changes, without a restart. Your own hooks run without a separate permission step.
• Plugins, from hooks/hooks.json or a hooks block in plugin.json. Plugin hooks run only after you allow the plugin’s code.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/bin/check-shell.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

Matchers use Claude Code’s tool names. Bash means os.shell.run. Read, Write, Edit, MultiEdit, Glob, Grep, LS, WebFetch and WebSearch map to the matching agent tools. Task means fusion.delegate. MCP tools are written mcp__<server>__<tool>.

How a hook decides:

• Exit code 2 blocks the call.
• JSON output with hookSpecificOutput.permissionDecision set to allow, deny or ask works, as do the older decision: block|approve and continue: false with stopReason.
• A PostToolUse hook can return additionalContext for the agent to read.

Hooks only make the agent stricter. allow does not skip an approval prompt, and a hook that answers ask can be followed by the tool’s own approval prompt. The default timeout is 60 seconds per hook, set with timeout per hook or defaultTimeout per file, up to 600. Hooks also run for Fusion worker calls. Hook messages go to the log; there is no screen to list or edit hooks yet.

Not supported yet

• Plugin output styles, LSP servers, monitors, bin and settings are skipped with the note “not supported yet”.
• Plugin subagents (agents/*.md) are read but nothing runs them.
• Only PreToolUse and PostToolUse hooks fire. SessionStart, Stop, UserPromptSubmit and the other Claude Code events are read but not run.
• Only {"type": "command"} hooks run. Other hook types, such as prompt, are skipped.
• The desktop app has no Plugins screen and does not offer plugin slash commands.

Related

Skills How skills load and how to turn one off.

MCP How MCP servers connect and ask for approval.

Approval gates What asks before it runs, and saved rules.

CLI Reference Every plugin subcommand and flag.