Athenode

Quickstart: your first specification

At the end of this quickstart you have Athenode running on your machine, your repository bound to a project and the Athenode workflow installed in your AI coding tool. You also have a first specification with the status Prepared, which you can open in the Athenode web UI. A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers.

The quickstart uses Claude Code. The steps are the same in every other AI tool, apart from the way you run a skill. The page on supported AI tools gives that form for each tool. Nothing in the quickstart needs an account.

Before you start

  • Node.js 22.16 or later. Check with node --version.
  • A supported AI coding tool, installed and working in your repository.
  • A local project directory, which is the root of the repository you want to work in. It may be empty.

1. Install Athenode

The athenode daemon is the local Athenode server that the athenode package installs: it keeps your projects on your machine and serves the web UI and the Athenode MCP server at http://127.0.0.1:3717. Install the package, then run the daemon as a service of your user:

npm i -g athenode
athenode service install

The service starts the daemon now and at every login. athenode service install waits until the daemon answers and prints "The daemon is running at" with its address. Install Athenode covers the service on each operating system, running the daemon in a terminal and updates.

2. Bind your repository with athenode init

athenode init binds your local project directory to a project of the daemon and installs the project's plugin. A project is the container of one specification tree, its ToDo cards and its plugins. A plugin is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and plugin files. A new project has one plugin, its own copy of the standard Athenode plugin.

A skill is a reusable set of instructions that an AI tool loads when it is relevant, usually run as a slash command such as /atn:mindmap. An agent is a specialist that an AI tool can hand work to (a subagent in most AI tools). Rules are the instructions every agent in a plugin follows.

  1. In a terminal, go to the root of your repository. Run the command there, because every later command looks for .athenode/config.json in the current directory.

  2. Run init:

    athenode init

  3. At "Which Athenode project should this repository use?", choose the first option, which creates a new project named after the directory. The CLI prints Created the project "<name>" (<id>)., and you can rename the project in the web UI later. A new project has one plugin, so init does not ask which plugin to install.

  4. At "Which AI coding tools should Athenode install into?", make sure Claude Code is selected and confirm. The CLI selects the tools whose files it finds in the directory. In a directory with none it selects Claude Code and Codex.

  5. At "Add the generated files to .gitignore?", keep the answer yes.

  6. At "Which modules should the Athenode MCP server give your AI tools?", keep every module selected. The workflow skills need the plugins module and the specifications module.

  7. If init says that Claude Code has the public plugin atn@athenode enabled, choose "Replace it". Without that plugin enabled, init does not ask.

  8. Read the plan. Under "Install formats:" it shows "Claude Code: plugin, declared in .claude/settings.local.json". Under "Added" it lists every file it will write, each marked +. A plan in a directory with files of its own can also have the parts "Changed", "Removed", "Not installed" and "Warnings".

  9. At "Apply this plan?", confirm.

The CLI prints Applied. Plugin 'atn' is installed.. Under "Still to do in your tools:" it lists what Claude Code needs before it uses the plugin: trusting the project folder, and restarting a running session so that the next start reads the plugin. Below that, it prints how to run /atn:settings in each selected tool.

For Claude Code, the plugin is installed as a plugin package named atn. A plugin package is the package that seven AI tools load a plugin from, named after the plugin's slug, with its commands written /<slug>:<skill>. The plugin package holds the skills, the agents and the athenode MCP server, which points at your project on the daemon, and is kept in .athenode/plugins/claudecode/. .claude/settings.local.json tells Claude Code where the plugin package is, and CLAUDE.md holds the Athenode rules block. .athenode/config.json records which project and which AI tools the directory uses, and init adds .athenode/ to .gitignore, so every clone of the repository runs its own init.

Note

Start Claude Code in the repository root before the next step, or restart a session that is running, and trust the project folder when Claude Code asks.

3. Choose your workflow settings

The workflow settings say how agents test, review and use git in this project. You choose them once with the /atn:settings skill.

  1. In Claude Code, run the skill:

    /atn:settings

  2. Answer the questions. The skill first looks at your repository without changing it, then asks about testing, methodology, code review and gitflow. Each question puts the recommended option first, with the reason for it.

  3. For this quickstart, choose the recommended option every time. You can run /atn:settings again whenever you want to change an answer.

The skill ends with a report of the settings you chose, in plain language. The settings are saved with the plugin in your project on the daemon, and no file is written to your repository.

4. Run your first mind map

A mind map is a session in which your AI agent asks rounds of questions and turns your answers into a specification. Describe something you want to build in one sentence. The example here is the checkout of a web shop.

  1. In Claude Code, run the skill with your subject:

    /atn:mindmap I want a checkout flow for my web shop: cart, payment and shipping

  2. Wait while the agent researches where the specification belongs in the specification tree, whether it is feasible in your codebase and which existing specifications it relates to. The specification tree is the hierarchy of a project's specifications. Any specification can have sub-specifications, to any depth.

  3. When the agent asks where to place the specification, choose "Yes, place it there". In an empty project the specification goes to the top level.

  4. Answer the first round of questions. A round has 3 to 8 questions on one topic, each with 2 to 5 options. You can type your own answer where no option fits.

  5. When the agent asks for the next topic, choose one of the three topics it proposes. Each choice starts another round.

  6. When the important decisions are covered, choose "Finish the mind map". The agent writes the title, the summary and the content from your answers, sets the status to Prepared and reports the specification's id.

  7. When the agent asks what to do next, choose "Nothing else".

The status Prepared means the specification is ready to be decomposed or implemented.

5. Open the specification in the web UI

  1. Open http://127.0.0.1:3717. The Projects page lists your project.
  2. Select the project, then open Specifications in the sidebar. The specification is there without a reload, because the page updates while your agent works.
  3. Select the specification in the tree and read the Content tab, which holds the text the agent wrote.
  4. Open the Questions tab, which holds every question the agent asked with the answer you gave.

The specification shows the status Prepared.

If a step of this quickstart fails, run athenode doctor. It checks Node.js, the data folder, the master key, the database and the port, and marks each check [ok], [warn] or [FAIL] with the reason. The troubleshooting page lists the messages you may see and their fixes.

Next steps after your first specification