Install a plugin

Installing a plugin writes its skills, agents, rules and MCP servers into a local project directory, as a plugin package or as files, whichever each of your AI coding tools takes. A plugin is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and plugin files. You install one with the init command of the Athenode CLI, run athenode sync when the plugin changed, and run init again when your choice of plugin or of AI tools changes.

init asks up to five questions, shows a plan of every file it would add, change or remove, and writes nothing until you confirm the plan.

Install a plugin for the first time

The first run binds a directory to a project of the local daemon and installs a plugin there. You need Node.js 22.16 or later, a terminal and the daemon running, as Install Athenode describes. To bind a project on an Athenode Pro server, add --server with the server's address, as the Athenode Pro guide describes.

1. Open a terminal in the root of your repository. Every later command looks for .athenode/config.json in the current directory, so the root is the place that works for all of them.

2. Run init:

   athenode init

3. Choose the project, or create one named after the directory. --project <id> binds an existing project without asking.

4. If the project has more than one plugin, choose one at "Which plugin should Athenode install?". Your project's copy of the standard plugin is first in the list and marked (project copy). A project with one plugin skips the question.

5. At "Which AI coding tools should Athenode install into?", select the tools you use in this repository. The tools whose files init finds in the directory are already selected. If it finds none, Claude Code and Codex are selected.

6. At "Add the generated files to .gitignore?", answer yes or no. The suggested answer is yes.

7. Read the plan and answer "Apply this plan?".

8. Follow the steps the CLI prints under "Still to do in your tools:", such as trusting the project folder in a tool or approving its MCP servers.

The CLI prints Applied. Plugin '<slug>' is installed., where the slug is the short name of the plugin. Under "Still to do in your tools:" it lists what the selected AI tools need before they use the plugin, each step with the tools it applies to. When the plugin contains the skill /atn:settings, the CLI adds one line per selected AI tool that says how to run it there, because the way to run a skill differs by AI tool. Run it once to choose the project's workflow settings. The /atn:settings reference describes its questions.

Answering no at "Apply this plan?" prints "Cancelled. Nothing was changed.", and leaving any earlier question with Ctrl+C stops init before it installs anything.

On Athenode Pro each member of a project installs separately, in their own local project directory. A plugin installed as a plugin package is written for one computer and does not reach another member through git, so each member runs athenode sync after a change to the plugin as well.

Read the plan before you confirm it

The plan is the list of everything init is about to do in your directory. It opens with "Plan for plugin", followed by the plugin's slug and id, and then has up to seven parts.

Part of the plan	What it lists
"Install formats:"	One line per selected AI tool that says whether the tool receives the plugin as a plugin package or as files.
"Removed", marked -	Files, MCP servers and agents that Athenode installed earlier and the plugin or your selection of AI tools does not include any more.
"Added", marked +	Files that do not exist in the directory, and MCP servers and agents that are missing from your configuration files.
"Changed", marked ~	Files and entries that exist and differ from the plugin.
"Not installed"	Per AI tool, the MCP servers and agents (the CLI calls them subagents) that the tool does not receive, each with the reason.
"Warnings"	Changes to files of your own that you may want to check first, such as a configuration file that loses its comments.
"Blocking errors"	Files that stop the plan, such as a configuration file that cannot be read.

The headings "Removed", "Added" and "Changed" carry the number of their entries, and a plan with nothing under those three says "No file changes.".

An entry is a path. A note in brackets after the path says what kind of change it is: "rules block" for the part of a rules file that Athenode writes, "rules block removed", and "generated files block" for the list in .gitignore. A plugin package is one entry, the folder that holds it, with the note "plugin" followed by the slug and the version. The entry of a tool's local settings file carries the note "plugin declaration". An MCP server is shown as the configuration file, a # and the server's name, for example .mcp.json#athenode. An agent that an AI tool keeps as an entry of a shared file is shown the same way.

A line that starts with "warning:" under an entry tells you that confirming loses something of yours.

Warning under an entry	Meaning
"locally edited, will be overwritten"	You edited an installed file by hand since the last install. Confirming replaces your edit with the plugin's version.
"locally edited, will be removed"	You edited an installed file that the plugin does not contain any more. Confirming deletes it.
"existing unmanaged file will be overwritten"	A file that Athenode did not install is at a path the plugin needs. Confirming replaces it.
"existing unmanaged server will be overwritten"	Your configuration has an MCP server with the same name as one of the plugin. Confirming replaces yours.

To keep an edit that the plan is about to overwrite, answer no, make the same change to the plugin in the web UI or with /atn:manage, and run athenode sync.

"Not installed" is where the differences between AI tools show. For Goose, Athenode installs local-command MCP servers, so HTTP and SSE servers of the plugin are listed here for Goose. An agent whose name collides with something of yours in a shared file is listed for that tool and installed for every other tool. The supported AI tools names the differences for each tool.

When the plan has blocking errors, init applies nothing. Fix or remove the file that each error names and run init again.

Plugin package or files for each AI tool

init installs the plugin as a plugin package for seven AI tools and as files for the other 23. A plugin package holds the plugin's skills, agents and MCP servers under the plugin's slug. The slug is the plugin package's name, and in Claude Code, Qoder, CodeBuddy Code and Mistral Vibe it is also the prefix of its commands, as in /atn:mindmap. Supported AI tools says for each tool which form it receives and how you run a skill in it.

AI tool	Where the plugin package is written	How the tool finds it
Claude Code	.athenode/plugins/claudecode/	.claude/settings.local.json
GitHub Copilot	.athenode/plugins/copilot/	.github/copilot/settings.local.json
Factory Droid	.athenode/plugins/factorydroid/<version>/	.factory/settings.local.json
Qoder	.athenode/plugins/qoder/<version>/	.qoder/settings.local.json
CodeBuddy Code	.athenode/plugins/codebuddy/<version>/	.codebuddy/settings.local.json
Mistral Vibe	.vibe/plugins/<slug>/	The tool reads its own plugin folder.
Google Antigravity	.agents/plugins/<slug>/	The tool reads its own plugin folder.

For the first five tools, init adds its entries to the tool's local settings file and leaves everything else in that file as it is. Two are written for every tool: extraKnownMarketplaces.athenode-local-<id>, which names the folder, and enabledPlugins, which turns on <slug>@athenode-local-<id>. In both names, <id> is eight characters that stand for the place of the project on your computer, so every project on one computer has a name of its own. For Claude Code and the slug atn, every install as a plugin package adds a third entry, which sets atn@athenode to false under enabledPlugins, so that the public Athenode plugin package of the same name stays off for this project. A local settings file belongs to one computer, so keep it out of version control.

Claude Code and GitHub Copilot selected together both receive a plugin package. Copilot CLI reads Claude Code's local settings file as well as its own, and its own file decides, so each tool loads its own plugin package. When GitHub Copilot receives files while Claude Code receives a plugin package, init adds one entry to .github/copilot/settings.local.json, which sets <slug>@athenode-local-<id> to false under enabledPlugins, so that Copilot CLI does not load Claude Code's plugin package. init removes the entry when it is no longer needed.

A tool that receives a plugin package receives no skill files and no agent files in its own folders. The rules are written as the Athenode rules block in the tool's rules file in both forms. An MCP server that the plugin package of a tool cannot hold is written to the tool's MCP configuration file, and the plan names it there with the reason.

When a tool that takes a plugin package receives files

init decides the form from the AI tools you selected and from the plugin's slug. No option of init changes the decision. A tool that takes a plugin package receives files in three cases.

Case	Tools that receive files	Why
Codex is selected together with Google Antigravity	Google Antigravity	Google Antigravity reads the folder .agents/skills, where Codex has its skills, and a plugin package would give it every skill twice.
One of Claude Code, Qoder, Command Code and CodeBuddy Code receives files	The others of the four	The four share the file .mcp.json, so all of them receive files or all of them receive plugin packages. Command Code always receives files.
The tool does not accept the slug as a plugin package name	That tool	Claude Code refuses the slugs claude, anthropic and anthropics and a slug that starts with claude-, anthropic-, anthropics- or cc-plugin-. Athenode refuses these slugs for a plugin, as Plugins lists, so this case applies to a plugin that already had such a slug.

The second case can follow from the third. With Claude Code and Qoder selected and a slug that Claude Code does not accept, Claude Code receives files because of the slug, and Qoder receives files because it shares .mcp.json with Claude Code.

The plan says which case applied. Under "Install formats:", a tool with a plugin package has a line such as "Claude Code: plugin, declared in .claude/settings.local.json" or "Mistral Vibe: plugin, in .vibe/plugins/atn/". A tool that receives files has "files", followed in brackets by the reason and the name of the tool that caused it, for example "Qoder: files (shares .mcp.json with Command Code, installed as files)".

When a selection changes the form for a tool, the next init removes what the earlier form wrote and installs the other one. In a tool that receives files, you run a skill in the way Supported AI tools gives for an install as files.

Keep or replace the public Athenode plugin package in Claude Code

Claude Code can have the public plugin package atn@athenode enabled for a project, in .claude/settings.local.json or in .claude/settings.json. That public plugin package has the name that your project's copy of the standard plugin takes as a plugin package, so init asks which of the two Claude Code should use before it shows the plan.

Answer	What init does for Claude Code
"Replace it", the suggested answer	Installs the plugin as a plugin package. The entry that sets atn@athenode to false in .claude/settings.local.json, which every plugin package install of the slug atn writes for Claude Code, turns the public plugin package off. .claude/settings.json is not changed.
"Keep the public plugin"	Writes the Athenode rules block and nothing else. The plan shows "Claude Code: the public plugin atn@athenode is kept (rules only)".

init asks on every run while the public plugin package is enabled, because the answer is not stored. Pass --public-plugin replace or --public-plugin keep to answer on the command line. With --yes, with --dry-run or without a terminal, init cannot ask. It then stops before the plan with an error whose code is PUBLIC_PLUGIN_CHOICE_REQUIRED, and you run it again with the option.

The question concerns the slug atn and Claude Code installed as a plugin package. /atn:manage does not ask and keep the public plugin package.

Check what init keeps in your repository

What init does to a file depends on whether the file is Athenode's alone or shared with you.

File	What init writes	What stays yours
Skill and agent files, such as .cursor/skills/<name>/SKILL.md	The whole file. The next install overwrites it.	Nothing. Change skills and agents in the plugin, not in these files.
Plugin package folders: .athenode/plugins/, .vibe/plugins/<slug>/ and .agents/plugins/<slug>/	Every file of the plugin package. The next install overwrites them.	Nothing. Change the plugin, not the plugin package.
Local settings files, such as .claude/settings.local.json	The entry extraKnownMarketplaces.athenode-local-<id> and the entries under enabledPlugins for the plugin's plugin package, which for Claude Code and the slug atn include "atn@athenode": false.	Every other setting in the file.
Rules files, such as AGENTS.md and CLAUDE.md	The Athenode rules block, between <!-- athenode:rules:start --> and <!-- athenode:rules:end -->.	Everything outside the block.
MCP configuration files, such as .mcp.json and .codex/config.toml	The MCP servers of the plugin.	Your own servers and every other setting in the file.
.gitignore	The line .athenode/ and, if you answered yes, a block that lists the installed files.	Every other line.

Athenode remembers what it installed in a directory, so a later run updates or removes its own files and entries only. Files that you or another tool created are never removed.

Rules files that hold your own text

If a rules file exists without an Athenode rules block, init adds the block at the top and keeps your text below it. If the block exists, init replaces it where it stands. Leave both marker lines in place and write your own rules outside them. When a marker is missing, duplicated or out of order, init stops and names the file, and you repair the markers before running it again. Cursor and Augment Code can receive a rules file that is Athenode's as a whole, .cursor/rules/athenode.mdc and .augment/rules/athenode.md. Rules in a plugin says which file each AI tool reads.

MCP configuration files with your own servers

Athenode merges the plugin's servers into the configuration file you have. A server of yours with the same name as one of the plugin is overwritten, and the plan warns you first. JSON files keep their comments. Athenode rewrites TOML and YAML configuration files when it changes them, and they may lose comments and formatting. The plan lists each such file under "Warnings" before you confirm.

The Athenode block in .gitignore

The block of installed files starts with # >>> athenode generated files >>> and ends with # <<< athenode generated files <<<. It lists the files that are Athenode's as a whole, one per line, and every later install keeps the list current. For a tool with a plugin package it also lists the tool's local settings file, and for Mistral Vibe the folder .vibe/plugin-data/<slug>/, where the tool keeps the plugin package's data. If you answered no, init prints a line that starts "Keep out of git" and names the local settings files it wrote. The plugin packages under .athenode/plugins/ are covered by the line .athenode/. Rules files with an Athenode rules block, MCP configuration files and the files that hold agents as entries are never listed, because they hold content of yours as well. A file that git already tracks stays tracked until you run git rm --cached on it. Answer no on a later run, or pass --no-gitignore, and init removes the block.

The binding file .athenode/config.json

.athenode/config.json stores the server and the project the directory is bound to, the installed plugin and the AI tools you selected. It holds no secret. Two of its values are yours to read and change: targets, the selected AI tools, and gitignoreGenerated, your .gitignore answer.

Files that are not installed

Plugin files, including the settings files under settings/, stay with the plugin in Athenode and are not written into your repository. Skills and agents read them from the installed plugin when they need them, so a change to a plugin file takes effect without another install.

Files installed per tool gives the exact paths for every AI tool and the files that several tools share.

Sync after the plugin changes

Only the athenode command writes files into your repository. Run athenode sync when the plugin changed in the web UI, when your agent changed it through the Athenode MCP server, when you updated your project's copy of the standard plugin, or when you updated a plugin from the plugin library. The Athenode MCP server answers a change of the installed plugin with a reminder to sync.

athenode sync

sync regenerates the files from the bound server and asks no question. The plan holds only what differs from the last install, and files that are the same are left untouched. When nothing differs, it prints "Already up to date" with the plugin's slug. After an install that changed something, it prints "Still to do in your tools:" again with the steps that apply.

Bring a changed plugin package into use

Each plugin package carries a version that changes whenever the plugin or the plugin package's files change, and stays the same otherwise. A tool that is running keeps the plugin package it loaded, so init prints for each tool with a changed plugin package the step that brings the changed plugin package into use. The CLI prints the step and does not perform it.

AI tool	Step
Claude Code, GitHub Copilot	Restart a running session.
Google Antigravity	Restart the tool.
Mistral Vibe	Run /reload-plugins in a running session, or start the next run.
Qoder	Start Qoder interactively in the project root.
Factory Droid	Start a new session in the project.
CodeBuddy Code	Start CodeBuddy Code in the project root.

Qoder, Factory Droid and CodeBuddy Code keep a copy of a plugin package of their own. For these three the version is part of the folder's path, so each of them takes the changed plugin package from the changed path when it starts.

A tool that receives files reads added or renamed skills, agents and MCP servers when it starts, so restart a running one after such an install.

Install a different plugin

Install a different plugin when a directory should do another job, for example a security review in place of the specification workflow. The plugin must belong to the project the directory is connected to. A directory holds one installed plugin, and each directory has its own, so a second working copy of the repository can hold a second plugin.

1. Run athenode init and choose the plugin at "Which plugin should Athenode install?". The installed one is marked (installed).
2. Read the line Warning: the installed plugin '<installed>' will be replaced by '<chosen>'., which names both plugins.
3. Read the plan. Under "Removed" it lists the files, the rules block and the MCP servers of the plugin you are leaving, and under "Added" those of the plugin you chose.
4. Answer "Apply this plan?".
5. Follow the steps under "Still to do in your tools:".

A plugin has its own slug, so a different plugin is a plugin package with a different name. init removes the plugin package of the plugin you are leaving, with its entries in the local settings files, and the skills are then run under the slug of the plugin you chose.

To name the plugin on the command line, pass its id or slug:

athenode init --plugin <id-or-slug>

The Plugins page of the web UI shows the slug of every plugin in the project. Add --dry-run to see the plan of the switch without making it. A plugin you added from the plugin library or created in the web UI is installed the same way.

Installing a different plugin changes this directory and nothing else. The plugins in your project and the installs in other directories stay as they are, and you return to the earlier plugin by choosing it in the same list.

Choose the AI tools to install for

Each AI tool you select receives the plugin's skills, agents, rules and MCP servers, as a plugin package or in its own files. Athenode supports 30 AI tools.

To change the selection, run init again and select or deselect tools at "Which AI coding tools should Athenode install into?". To set the selection on the command line, pass the ids of the tools, which the supported AI tools page lists:

athenode init --targets claudecode,cursor

The selection is stored as targets in .athenode/config.json, and every later install and every command that updates the installed plugin uses it. The order of the ids does not matter, and an unknown id stops init with the list of valid ids.

Deselecting a tool removes what was installed for it: its skill and agent files or its plugin package, its rules block and its MCP servers. For a plugin package, init also removes the entries it added to the tool's local settings file, and removes the file when nothing else is left in it. A local settings file that cannot be read stops the plan until you correct it. Copies of a plugin package that Factory Droid, Qoder and CodeBuddy Code keep in your home directory are theirs, and init leaves them where they are. A file that several tools share, such as AGENTS.md or the .mcp.json in the repository root, keeps Athenode's content while one of those tools remains selected. A rules file of yours that held nothing but the rules block is left empty.

Run init without questions

init takes every answer as an option, so a script or a CI job can install a plugin.

Option	What it does
--plugin <id-or-slug>	Installs this plugin without asking.
--targets <ids>	Installs for these AI tools, given as ids separated by commas, and stores the selection as targets in .athenode/config.json.
--gitignore	Lists the installed files in .gitignore without asking. Excludes --no-gitignore.
--no-gitignore	Leaves the installed files out of .gitignore and removes a list that an earlier run added. Excludes --gitignore.
--public-plugin <replace|keep>	Answers the question about the public plugin package atn@athenode in Claude Code: replace installs the plugin's plugin package in its place, and keep installs the rules only.
-y, --yes	Applies the plan without the confirmation question and without the other questions.
--dry-run	Prints the plan and writes nothing. No questions are asked.

athenode init --plugin <id-or-slug> --targets claudecode,codexcli --yes

The entry for athenode init in the Athenode CLI reference describes each option in full.

With --yes or --dry-run, or when init runs without a terminal, it asks nothing and takes each missing answer from the last install: the installed plugin, the stored AI tools and the stored .gitignore answer. The answer about the public plugin package is the exception. It is never stored, so init needs --public-plugin on each such run while Claude Code has atn@athenode enabled. In a directory without those, it installs your project's copy of the standard plugin for Claude Code and Codex and lists the installed files in .gitignore.

Without a terminal, --yes is required, because the plan cannot be confirmed. With --yes and no stored binding, init creates a project named after the directory.

Set the environment variables MCP servers need

An MCP server can refer to a value as ${VAR}, so that a token or key stays out of the plugin. After an install or a dry run, the CLI lists the environment variables that the installed MCP servers refer to and that are not set, grouped by server.

The CLI sees its own environment only. Set each variable in the environment where your AI tool runs, then restart the tool. MCP servers in a plugin covers ${VAR} references.