Install a setup

Installing a setup writes its skills, agents, rules and MCP servers into a local project directory, in the files each of your AI coding tools reads. An agent setup is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and setup files. You install one with the init command of the Athenode CLI, and you run the same command again whenever the setup, your choice of setup or your choice of AI tools changes.

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

Install a setup for the first time

The first run connects a directory to your Athenode project and installs a setup there. You need Node.js 22.12 or later, a terminal you can type into and a project token, which is a personal access token that lets the Athenode CLI, and your AI agent through it, act on one project. A project token is created by an owner or an editor, so installing a setup needs one of those roles.

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:

   npx @athenode/cli init

3. At "Enter your athenode project token", paste the token. The CLI checks it, stores it in .athenode/config.json, adds .athenode/ to your .gitignore and prints "Token stored." with the id of the project.

4. If the project has more than one setup, choose one at "Which setup should Athenode install?". Your project's copy of the standard setup is first in the list and marked (project copy). A project with one setup 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. Restart your AI tool so that it loads the skills, the agents and the MCP servers.

The CLI prints Applied. Setup '<slug>' is installed., where the slug is the short name of the setup. When the setup 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.

Each member of a project installs separately. .athenode/config.json holds a personal token and stays out of version control, so every member creates a token of their own and runs init in their own local project directory.

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 setup", followed by the setup's slug and id, and then has up to six parts.

Part of the plan	What it lists
"Removed", marked -	Files, MCP servers and agents that Athenode installed earlier and the setup 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 setup.
"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. 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 setup's version.
"locally edited, will be removed"	You edited an installed file that the setup 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 setup needs. Confirming replaces it.
"existing unmanaged server will be overwritten"	Your configuration has an MCP server with the same name as one of the setup. Confirming replaces yours.

To keep an edit that the plan is about to overwrite, answer no, make the same change to the setup in the web app or with /atn-manage, and run init again.

"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 setup 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.

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 .claude/skills/<name>/SKILL.md	The whole file. The next install overwrites it.	Nothing. Change skills and agents in the setup, not in these files.
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 setup.	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 setup says which file each AI tool reads.

MCP configuration files with your own servers

Athenode merges the setup's servers into the configuration file you have. A server of yours with the same name as one of the setup 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. 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 connection file .athenode/config.json

.athenode/config.json stores your project token, the installed setup and the AI tools you selected. Two of its values are yours to read and change: targets, the selected AI tools, and gitignoreGenerated, your .gitignore answer. Keep the file out of version control, because the token in it is a secret.

Files that are not installed

Setup files, including the settings files under settings/, stay with the setup in Athenode and are not written into your repository. Skills and agents read them from the installed setup when they need them, so a change to a setup 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.

Install again after the setup changes

Run init again when the setup changed in the web app, when Athenode updated your project's copy of the standard setup, or when you updated a setup from the setup library. A setup changed with /atn-manage or with the CLI commands that edit the installed setup needs no second run, because those update the local files in the same step.

1. In the directory that holds .athenode/config.json, run npx @athenode/cli init.
2. At the question that starts "A project token is already stored" and ends "Replace it?", keep the suggested answer, no. Answer yes only to connect the directory with a different token.
3. Confirm the setup, the AI tools and the .gitignore answer. Each question opens on what you chose last time.
4. Read the plan and answer "Apply this plan?".

The plan holds only what differs from the last install, and files that are the same are left untouched. When nothing differs, init prints "Already up to date" with the setup's slug and asks nothing more.

Restart your AI tool after an install that added or renamed skills, agents or MCP servers.

Install a different setup

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

1. Run npx @athenode/cli init and choose the setup at "Which setup should Athenode install?". The installed one is marked (installed).
2. Read the line Warning: the installed setup '<installed>' will be replaced by '<chosen>'., which names both setups.
3. Read the plan. Under "Removed" it lists the files, the rules block and the MCP servers of the setup you are leaving, and under "Added" those of the setup you chose.
4. Answer "Apply this plan?".
5. Restart your AI tool.

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

npx @athenode/cli init --setup <id-or-slug>

athenode setups list prints the id and slug of every setup in the project. Add --dry-run to see the plan of the switch without making it. A setup you added from the setup library or created in the web app is installed the same way.

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

Choose the AI tools to install for

Each AI tool you select receives the setup's skills, agents, rules and MCP servers 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:

npx @athenode/cli 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 setup 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, its rules block and its MCP servers. 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 setup.

Option	What it does
--setup <id-or-slug>	Installs this setup 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.
-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.

npx @athenode/cli init --setup <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 setup, the stored AI tools and the stored .gitignore answer. In a directory without those, it installs your project's copy of the standard setup for Claude Code and Codex and lists the installed files in .gitignore.

Without a terminal, --yes is required, because the plan cannot be confirmed. The project token is always typed at a prompt, so the first init in a directory runs in a terminal you can type into, without --yes and --dry-run. Later runs reuse the stored token.

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 setup. 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 setup covers ${VAR} references.