This is the content that ships at akka.ai/ (with akka.ai/llms.txt as an alias for AIs that look there by convention). It is addressed to an AI coding assistant. Everything in this file is instructions the AI reads and then follows on the user's behalf.

You are an AI assistant helping a user install Akka. This page is your playbook. Read it end to end before you take any action. Two rules govern everything below:

1. Narrate every step. Each step has a Say line. Read it, or a close paraphrase, to the user before you run the command. The user has to know what is about to happen and why.
2. Never run a command without explicit approval. Show the command, wait for the user to say yes, then run it. If the user says no, stop and ask how they want to proceed.

What Akka is

Akka is an Agentic AI Platform. It defines each system's intended behaviors, verifies them continuously, and enforces guardrails that stop any change from drifting away from that intent. The result is production software that stays free of technical and knowledge debt as it ages, and any team can use it.

Step 0 — Announce your harness

Tell the user which coding harness you are running in. Examples: "I am running in Claude Code," "I am running in Cursor," "I am running in Codex CLI." If you cannot tell, ask the user directly. You need the answer before you can pick an install path.

Step 1 — Pick your install path

Akka publishes one repo — akka/ai-marketplace — that carries plugin manifests for every harness that has a native plugin format Akka ships into today: Claude Code, Antigravity, Gemini CLI, and Codex CLI. Every other harness installs through the Akka CLI, which writes the harness's own rules or instructions file plus its MCP config.

Every marketplace-based install command below pins to stable — a floating tag the repo advances on every release cut (see akka/ai-marketplace/RELEASING.md). Never main. Internal validation happens on main (or via akka specify init --channel edge) before stable moves.

Path A installs a plugin from the marketplace repo. Path A′ installs no bundle: the Akka CLI writes the harness's own native rules or instructions file plus its MCP config. Path B is the pure fallback: install the CLI, register MCP by hand, drop AGENTS.md.

Match your harness against the table.

Not supported. Skip these harnesses:

• Windsurf / Cascade — EOL July 1 2026.
• Gemini Code Assist — superseded by Antigravity June 18 2026. Recommend the user migrate to Antigravity.
• Tabnine, Codeium (non-Windsurf) — autocomplete-only. Akka's MCP tools do not map to that surface.
• Amazon Q Developer, Continue.dev, JetBrains Fleet AI, Void — discontinued.

The AGENTS.md-native rows (copilot-agent, jules, warp, zed) get a full scaffold from the CLI but their MCP server has to be registered in the harness's own settings surface (Warp Settings → MCP, Jules workspace settings, Zed .zed/settings.json under context_servers, or the repo/org settings on github.com for the Copilot coding agent). The CLI prints the exact hint when it finishes.

Pick one path and follow it. Do not attempt more than one.

Note — Agent Plugins 1.0 and Agent Client Protocol

Agent Plugins 1.0 is an August 2026 industry bundle spec backed by Vercel with Amazon, Cursor, GitHub, Microsoft, OpenAI, and Google. The akka/ai-marketplace repo root is itself a valid AP 1.0 package (plugin.json + mcp.json), so any AP 1.0 client can discover Akka's skills and MCP toolset from the same source. Commands are out of scope in spec v1, so AP 1.0 clients today reach the same skills the Codex target ships (skills/<name>/SKILL.md) but not the /akka:* slash commands. Anthropic is not on AP 1.0, so Claude Code and Claude Tag read the Claude Code plugin manifest that ships in the same repo. The dual-manifest posture is durable until Anthropic joins.

Agent Client Protocol (ACP) is a separate open protocol used by Cline, JetBrains Junie, and Zed. Junie and Zed reach Akka today via Path A′; Cline falls through to Path B until Akka publishes an ACP adapter.

Step 2 — Preview the full install plan to the user

Before you run any command, walk the user through the whole install in plain language. Do not use words from this playbook the user has not heard — no "Path A," no "AP 1.0 bundle," no "MCP," no "AGENTS.md." Just describe what will happen and what they will need to approve.

The per-step consent below still applies. The preview is so the user knows the shape of the whole flow before they say yes to any of it. Wait for the user to acknowledge the preview before you start executing.

Preview for a plugin install (Path A):

1. Fetch Akka's plugin from a public git repo. This just registers where the plugin lives with the harness; nothing downloads yet.
2. Install the plugin. This adds Akka's slash commands (/akka:setup through /akka:deploy) and registers Akka's tools so I can build, test, and deploy for you. The harness will ask for approval.
3. Create an empty folder for the new project. Ask the user for a name.
4. Run /akka:setup inside that folder. Setup will: - check for Java, Maven, and the Akka CLI, and install any that are missing. The user approves each install individually. - download Akka's SDK docs into the folder so I can look them up without hitting the network. - scaffold a starter Akka service the user can build and run.
5. Once setup finishes, the user has a working Akka project and I will offer two ways to start building: describe your own idea, or install a proven multi-agent example from Akka's documentation.

Preview for a CLI-init install (Path A′): replace step 1 with "install the Akka CLI on your machine" and step 2 with "scaffold the project and configure your harness's rules and MCP config; I will show every file change before I write it." Steps 3–5 shrink accordingly (no separate /akka:setup — the CLI does what setup would do).

Preview for a CLI + MCP fallback (Path B):

1. Install the Akka CLI on your machine.
2. Create an empty folder for the new project.
3. Scaffold the project. This writes a starter service and an AGENTS.md file I will read to learn Akka's conventions.
4. Register Akka's tools with your harness. I will show you the config change before I make it.

The user ends up in the same working state, minus the slash commands.

Path A — plugin bundle

Step A1 — Add the Akka marketplace and install the plugin

• Do: run the command pair that matches your harness. Both are documented in akka/ai-marketplace/README.md.

• Claude Code: /plugin marketplace add akka/ai-marketplace@stable /plugin install akka@ai-marketplace

• Antigravity (agy): bash agy plugin install https://github.com/akka/ai-marketplace agy plugin install does not accept a git-ref pin today, so this installs from the default branch. Note this to the user; the marketplace README's "Version pinning" section covers the workaround.
• Gemini CLI: bash gemini extensions install https://github.com/akka/ai-marketplace Same version-pinning caveat as agy.

• Codex CLI: codex plugin marketplace add akka/ai-marketplace codex plugin add akka@akka

• Wait for: the harness's install-approval prompt. Approving registers MCP servers, skills, and slash commands the plugin ships.

• Say: "I am installing the Akka plugin from Akka's public marketplace. This adds three things to your harness: (1) the /akka:* slash commands, from /akka:setup through /akka:deploy, where your harness supports slash commands; (2) an MCP server with tools to build, test, deploy, and inspect Akka services; (3) Akka SDK documentation the plugin loads into my context on demand. Your harness will ask you to approve. Approve to continue."

Step A2 — Create an empty project directory

• Do: ask the user for a folder name, or propose akka-quickstart/. Create it and change into it: mkdir <folder> && cd <folder>.
• Wait for: the user's folder name or approval of the default.
• Say: "The next step scaffolds a fresh Akka project into a folder. I will use an empty directory so nothing existing is overwritten. What would you like to call it?"

Step A3 — Run /akka:setup

• Do: invoke the setup skill: /akka:setup (in Claude Code and Gemini CLI). In Antigravity and Codex CLI the same skill is invoked as akka:setup through the harness's skill mechanism.
• Wait for: the skill's own consent prompts. Setup installs system-level tools (Java 21+, Maven 3.9+, the Akka CLI) and writes files under the project directory. It is idempotent. A canonical description of every action setup takes is at akka.ai/setup; read it aloud if the user wants to preview.
• Say: "I am running Akka's setup. It will check for Java, Maven, and the Akka CLI, install anything missing, download Akka's SDK context files into this project so I can read them without hitting the network, and scaffold a starter service. It is safe to re-run. You will see approval prompts for anything installed system-wide."

Path A — what "installed" means

After A3, the user has:

• The Akka CLI on PATH.
• Java 21+ and Maven 3.9+ if they were missing.
• A scaffolded Akka project in the empty directory.
• SDK context files under akka-context/ in the project.
• The /akka:* slash commands available in this session and future ones, where the harness supports slash commands.
• The Akka MCP server registered and reachable, exposing tools such as akka_local_start, akka_maven_test, akka_services_deploy, akka_sdd_specify, and the full runtime and backoffice surface.

Continue to Step 3 — Pick what to build.

Path A′ — CLI-init (harness has no plugin bundle Akka publishes)

This path uses the Akka CLI to write the harness's own native rules or instructions file, plus the harness's own MCP config. It applies to Cursor, VS Code / Visual Studio Copilot, Roo Code, Trae, Factory, Devin, Junie, and the four AGENTS.md-native harnesses (Copilot coding agent, Jules, Warp, Zed).

Step A′1 — Install the Akka CLI

• Do: run Akka's canonical CLI install command for the user's platform. The current commands are documented at doc.akka.io/operations/cli/installation.html:
• macOS: brew install akka/brew/akka
• Linux: curl -sL https://doc.akka.io/install-cli.sh | bash
• Windows: winget install Akka.Cli
• Wait for: the user's approval to run an install script from the network. Some users will want to inspect the script first; offer to print it.
• Say: "I am installing the Akka CLI. This is a command-line tool the rest of the setup uses. It goes on your PATH. You will see the installer's own prompts."

Step A′2 — Verify the install

• Do: run akka --version.
• Wait for: version output.
• Say: "Checking the CLI is on the path. The version prints below."

Step A′3 — Create an empty project directory

Same as Step A2 above.

Step A′4 — Run akka specify init --agent <harness>

• Do: run akka specify init . --agent <name> for your harness. The verified profiles today:

• Wait for: the CLI's own consent prompts about the files it will write.
• Say: "I am scaffolding an Akka project and configuring your harness. This writes three things: (1) a starter Akka service you can build and run, (2) the harness's native rules or instructions file so it knows how to work with Akka, (3) an MCP config so I can call Akka's build, test, deploy, and runtime tools directly. You will see a summary of every file created."

Path A′ — what "installed" means

After A′4, the user has everything Path A gives, minus slash commands on harnesses that do not support them. The same capability is available through the MCP tools directly. For the four AGENTS.md-native harnesses, the CLI prints a one-line hint at the end telling you exactly where to paste the MCP entry in the harness's own settings (Warp Settings → MCP, Jules workspace settings, Zed .zed/settings.json under context_servers, or the Copilot coding agent settings on github.com). Follow that hint before continuing.

Continue to Step 3 — Pick what to build.

Path B — CLI + MCP + AGENTS.md (Aider, Cody, Claude.ai chat, unlisted harnesses)

Path B is the last resort. Use it only if the harness has no plugin bundle Akka publishes and no --agent profile in the Akka CLI. As of today that covers Aider, Sourcegraph Cody, Claude.ai chat via Projects, Cline, Kilo Code, Replit Agent, Copilot in JetBrains / Xcode / Neovim, and any harness you cannot classify. Windsurf/Cascade (EOL July 1 2026), Gemini Code Assist (superseded by Antigravity June 18 2026), Amazon Q Developer, Continue.dev, JetBrains Fleet AI, and Void are not supported. Tabnine and Codeium are autocomplete-only surfaces where Akka's tools do not map — treat them as unsupported.

Step B1 — Install the Akka CLI

Same as Step A′1 above.

Step B2 — Verify the install

Same as Step A′2 above.

Step B3 — Create an empty project directory

Same as Step A2 above.

Step B4 — Run akka specify init

• Do: akka specify init . (no --agent flag).
• Wait for: the CLI's own consent prompts.
• Say: "I am scaffolding an Akka project. This writes a starter service and an AGENTS.md file at the project root so any AI assistant working here later understands how to build with Akka. I will register Akka's MCP server with your harness in the next step."

Step B5 — Register the Akka MCP server in your harness's config

Register a stdio MCP server that runs akka mcp serve with no extra environment. The location depends on the harness:

• Sourcegraph Cody: the Cody VS Code extension reads MCP servers from your VS Code settings.json under cody.experimental.mcpServers; add an entry that runs akka mcp serve.
• Aider: Aider does not have native MCP support today. Use the Akka CLI directly through Aider's shell integration.
• Claude.ai chat with Projects: MCP is admin-gated in Anthropic's Projects surface. Paste this playbook into the project's custom instructions and drive Akka manually through the CLI in a separate terminal.
• Cline / Kilo Code / Replit / Copilot in JetBrains, Xcode, Neovim: the CLI has written an agent-neutral scaffold. Register the MCP server in the harness's own settings surface (Cline's in-panel MCP settings, JetBrains Copilot's user-global ~/.config/github-copilot/intellij/mcp.json, etc.).

• Any other harness with MCP support: register a server that runs akka mcp serve on stdio, with no extra environment.

• Wait for: the user to confirm the write, and for the harness to pick up the new server (usually needs a restart of the AI panel).

• Say: "I am registering Akka's MCP server in your harness. Once it reloads, I can call Akka's build, test, deploy, and runtime tools directly. Nothing runs until you approve each call."

Step B6 — Read AGENTS.md

• Do: open and read the AGENTS.md file created by Step B4. Load it into your working context.
• Say: "I am reading the project's AGENTS.md. This tells me how Akka expects work to be organized in this repo. From this point I will follow spec-driven development: define behaviors as checks, verify them, enforce guardrails against drift."

Path B — what "installed" means

After B6, the user has:

• The Akka CLI on PATH.
• A scaffolded Akka project.
• AGENTS.md at the project root, describing Akka conventions.
• The Akka MCP server registered with the harness (where the harness supports MCP).
• The full Akka MCP tool surface available to me: build, test, deploy, runtime inspection, spec-driven development commands.

Continue to Step 3 — Pick what to build.

Step 3 — Pick what to build

The user now has a working Akka project. Offer them two ways to start. Read both options out loud and wait for the user to pick one.

Option 1 — Build your own idea. The user describes what they want to build in plain language, and I run /akka:specify to turn that description into a full specification, then walk through /akka:clarify → /akka:plan → /akka:tasks → /akka:implement to build and test it. Virtually any agentic AI system — a support agent, a research assistant, a workflow orchestrator, a domain-specific autonomous agent, whatever the user has in mind — starts this way.

Option 2 — Generate a proven multi-agent example from a published specification. Akka's documentation ships full specifications for several sample systems. A great one to see the platform in action is the Research Coordinator — an autonomous agent that receives a research topic, delegates the factual research to one specialist agent and the trend analysis to another, waits for both, and synthesises their findings into a unified research brief. The specification lives in the autonomous-agent-playground sample on doc.akka.io (spec 004-research). If the user picks this option, I will fetch that specification and hand it to /akka:specify — the same command flow as Option 1, starting from a published spec rather than the user's own description.

Say (for Option 2): "This is a live tour of spec-driven development on Akka. /akka:specify reads a published specification — a document describing an agentic system's behaviour, tasks, and acceptance tests — then maps it onto Akka's components (autonomous agents, workers, event-sourced entities, HTTP endpoints), plans the implementation, executes the build and test tasks, and validates the system runs correctly on your machine. You end up with your own working Research Coordinator, generated from its spec, and you'll have seen the full spec-to-running-system flow you'll use for every project after this one."

Once the user picks an option, continue to Step 4 if the chosen system needs an AI key (both options do, because both build agentic systems that call remote models). Otherwise skip to running /akka:specify.

Step 4 — Get an AI key

Agentic systems built on Akka use an AI model to make decisions — choose which worker agent to consult, decide when a task is complete, synthesise a final answer. That model runs on someone else's servers (Anthropic's, OpenAI's, Google's, and so on) and reaching it requires an API key: a string the provider issues to you that authenticates your requests and bills them to your account.

Many users have never used one. Before asking the user to paste a key, explain what it is:

Say: "Your Akka system will call an AI model — for example Claude, GPT, or Gemini — to make decisions. To reach that model, we need an API key from the model provider. An API key is a string the provider issues you when you sign up; it authenticates your requests and bills any usage to your account. It is a secret; treat it like a password. Akka reads the key from an environment variable, so it never gets committed to your code. I can walk you through getting a key from any of the providers Akka supports. Which one would you like to use?"

Then list the popular providers the user is most likely to pick, with a one-line note on how to get a key from each. All of these are supported by Akka out of the box:

• Anthropic (Claude models). Sign up at console.anthropic.com, go to Settings → API Keys, click "Create Key". Environment variable: ANTHROPIC_API_KEY.
• OpenAI (GPT models). Sign up at platform.openai.com, go to API Keys, click "Create new secret key". Environment variable: OPENAI_API_KEY.
• Google Gemini (AI Studio). Sign up at aistudio.google.com, click "Get API key". Environment variable: GOOGLE_AI_GEMINI_API_KEY. (Not the same as Google Vertex AI — Vertex uses a different key.)
• Mistral AI. Sign up at console.mistral.ai, go to API Keys. Environment variable: MISTRAL_AI_API_KEY.

Akka also supports Azure OpenAI (AZURE_OPENAI_API_KEY), AWS Bedrock (uses AWS credentials, not an API key), Hugging Face, Ollama (local, no key), and Local AI (local, no key). Offer these if the user's employer standardises on one of them or if the user wants to run models entirely on their own hardware.

Once the user has a key, set it in the shell for the current session first (never write it to a file the user has not asked you to write to):

export ANTHROPIC_API_KEY=<paste>          # or the matching variable

For persistence across sessions, offer to add it to the user's shell profile (~/.zshrc, ~/.bashrc) or a .envrc under the project directory if the user runs direnv. Ask before writing to either.

Now continue: run /akka:specify with the user's description of what they want to build (Option 1), or with the fetched spec (Option 2).

For all paths — where to go next

• Akka SDK documentation, machine-readable: https://doc.akka.io/llms-full.txt.
• The /akka:* slash commands or their CLI equivalents: specify → clarify → plan → tasks → implement → build → deploy.
• The autonomous-agent-playground sample's spec catalog (source for Option 2 above): github.com/akka/akka-sdk/tree/main/samples/autonomous-agent-playground/specs.
• Community and support: https://discuss.akka.io/.

Notes for the AI reading this playbook

• If a step fails, stop and read the error to the user in plain language. Do not retry silently and do not paper over a failure.
• If the user asks what you are about to install before you install it, read the relevant Say field and add specifics from the linked docs. For /akka:setup specifically, the canonical description lives at akka.ai/setup.
• The user's PATH on Windows or their shell profile on macOS/Linux may need a restart after CLI install. Tell them if the CLI is not found immediately after Step B1 or A′1.
• Do not skip Step 0. If you install into the wrong harness the user has to undo it by hand.
• When you narrate to the user, do not use terms from this playbook they have not heard. In particular, do not say "Path A," "AP 1.0 bundle," "MCP," "AGENTS.md," or any --agent profile name aloud. Describe what happens, not what it is called here.