Docs › Extending AstraCode

Plugins

Install plugins written for Claude Code or Cursor, or in the Agent Plugins format: skills, commands, agents, rules, hooks and MCP servers in one package.

A plugin bundles skills, commands, agents, rules, hooks and MCP servers so they can be shared and installed together. AstraCode installs plugins written for Claude Code (.claude-plugin/plugin.json), for Cursor (.cursor-plugin/plugin.json) and in the open Agent Plugins format (a root plugin.json), from the marketplaces those tools use. A plugin with no manifest at all is read from the default folders.

Adding a marketplace

A marketplace is a repository with a .claude-plugin/marketplace.json or .cursor-plugin/marketplace.json, or a repository that is itself one plugin. Add one in Settings > Customize > Plugins > Add marketplace, or from a terminal:

astracode-agent plugin marketplace add anthropics/claude-code
astracode-agent plugin list --available
astracode-agent plugin install hookify@claude-code-plugins

A marketplace can be owner/repo (optionally #branch), any https, ssh or git@ url, or a folder on your machine. Its name is the one its marketplace.json gives. A plugin source of type npm, archive or command is listed with the reason it cannot be installed; a command source would run a program before you had seen what the plugin does.

What you agree to

A plugin's skills, commands, rules and agents are text the agent reads, and every action the agent takes still goes through your approvals. Its hooks and MCP servers are programs that run by themselves. So before a plugin is installed you are shown every hook command and every server's command or url, exactly as it will run, and it is installed only if you allow them. In the CLI that is --yes, or a y typed at the question; in a script with no --yes the answer is no.

Your agreement is to that exact list. An update that adds a hook, changes a command or points a server elsewhere asks again, and saying no keeps the version you have. An update that changes only text installs without asking.

Nothing is read from outside a plugin's folder: a path with .., an absolute path, or a link pointing out of the plugin is refused and listed on the plugin's card. Links in a repository are checked out as plain files, and git runs without a shell.

Names

A plugin's skills and commands are named <plugin>:<name>, as Claude Code names them: /hookify:list. A command in a subfolder adds the folder, /<plugin>:db:migrate, and agents and rules are named the same way. The bare name, /list, works while no other plugin and none of your own files use it; when two do, type the full name.

What a plugin can contain

A manifest can point a component elsewhere. In a Claude Code plugin commands and agents replace their default folder, skills adds to it, and hooks and mcpServers are merged with the default files; in a Cursor plugin each key replaces its default. An Agent Plugins plugin has skills and mcp.json only. Output styles, LSP servers, hooks of a type other than command, and hooks with an if condition are listed on the plugin's card as not run.

${CLAUDE_PLUGIN_ROOT}, ${CURSOR_PLUGIN_ROOT} and ${PLUGIN_ROOT} are the plugin's folder, and ${CLAUDE_PLUGIN_DATA} and ${PLUGIN_DATA} a data folder kept across updates. A plugin's hooks and servers start in that environment, and its hooks are shown the payload of the tool they were written for.

Options

A plugin can ask for values: Claude Code's userConfig, Cursor's variables. Set them on the plugin's card, or with astracode-agent plugin config. One marked sensitive (or, in a Cursor plugin, one named like a key, token or secret) is kept in your keychain, never in a settings file, and the CLI never takes it from the command line. In a hook command an option is passed as the environment variable CLAUDE_PLUGIN_OPTION_<KEY>, so its value is never pasted into a shell line.

Where it applies

Install a plugin for yourself, or for one project. A project's plugin applies only when that folder is open and trusted, like everything else a project carries. A plugin you turn off contributes nothing. Plugins are kept in ~/.astracode/plugins, each at the commit it was installed from, and the editor and the CLI share them.

Team marketplace

On the dashboard's Plugins page, an owner or admin lists marketplace repositories and sets each plugin Off (developers can find and install it), On (installed and on by default; a developer can turn it off or uninstall it, and it is not put back) or Required (installed and kept on). Shared configuration is part of your plan.

Required does not let a plugin's hooks or MCP servers run. Each developer is shown what they run and asked once per machine; until they allow them, only the plugin's skills, commands, rules and agents apply. A change to what it runs asks again.

Seeing what a plugin did

Each installed plugin's card in Customize lists the skills, commands, agents, rules, hooks and servers it put into the editor, what in it could not be used and why, whether its hooks and servers are allowed, and which options still need a value. astracode-agent plugin list prints the same.

All documentation

Get started

• Quickstart
• Install AstraCode
• The chat panel

Agent

• Agent overview
• Approvals and permissions
• Plan mode
• What the agent can do
• Running commands
• Browser tools
• Checkpoints and undo
• Infrastructure as code
• Running several agents at once
• Subagents and background tasks
• Remote agents in GitHub Actions

Context

• How context works
• Rules
• Memories

Workspaces

• Workspaces
• Working across several repositories

Connectors

• Connectors (MCP servers)
• Use AstraCode from Claude, ChatGPT and other apps

Extending AstraCode

• Plugins and skills
• Plugins
• Skills
• Hooks
• Dictation

CLI

• AstraCode CLI

Reference

• Settings reference
• Keyboard shortcuts
• Models