AO Code

1. What AO Code is

AO Code is a program you run in a terminal in the folder of your project. You describe a task in plain words, and AO Code reads the project files, answers and, with your consent, writes changes to the files.

AO Code is part of your AO Platform package. The model and its cost come from the package: you do not need a separate account with a model provider.

2. Before you start

You need two things.

1. A package with AO Code. AO Code works only when it is included in your company's package. If it is not, the program says so; contact platform support.

2. Working sign-in to the cabinet. You sign in to AO Code in the browser with the email of your account, the same way as to the cabinet. Only the account owner can connect a computer.

3. Download

Choose the file for your system. Each file holds a self-contained program: nothing else needs to be installed.

To check a downloaded file, compare its SHA-256 checksum with the one under the button: shasum -a 256 on Mac, sha256sum on Linux, Get-FileHash in PowerShell on Windows.

4. Installation

macOS

1. Download the Mac file above. It is saved to the Downloads folder.
2. Open Terminal and run the commands below one by one. They unpack the archive into the aocode folder in your home folder and add that folder to PATH.
3. Close Terminal and open it again.
4. Run aocode --version: the program prints its version number.
5. Keep the aocode folder whole: the aocode command in it picks the build for your processor, Apple Silicon or Intel, by itself.

cd ~/Downloads
tar -xzf aocode-*-macos.tar.gz
mv aocode-*-macos ~/aocode
echo 'export PATH="$HOME/aocode:$PATH"' >> ~/.zshrc

Windows

1. Download the Windows file above. It is saved to the Downloads folder.
2. Open the downloaded .zip file, open the folder inside it and copy aocode.exe.
3. Paste %LOCALAPPDATA%\Programs into the File Explorer address bar, create a folder named aocode there and paste aocode.exe into it.
4. Add this folder to PATH: open Start, type “environment variables”, choose “Edit environment variables for your account”, select Path, click Edit, then New, paste %LOCALAPPDATA%\Programs\aocode and click OK in both windows.
5. Open a new PowerShell window and run the command below: the program prints its version number.

aocode --version

Linux

1. Download the Linux file above. It is saved to the Downloads folder.
2. Run the commands below in a terminal. They unpack the archive and put the aocode program into ~/.local/bin.
3. If aocode --version answers “command not found”, add ~/.local/bin to PATH in your shell profile, for example ~/.bashrc, and open a new terminal.

cd ~/Downloads
tar -xzf aocode-*-linux-x64.tar.gz
mkdir -p ~/.local/bin
mv aocode-*-linux-x64/aocode ~/.local/bin/aocode
aocode --version

5. First launch and sign-in

1. Open a terminal in the folder of your project and type aocode.
2. AO Code opens your browser on the platform sign-in. If the browser does not open by itself, the terminal shows a link: open it yourself.
3. Sign in with the email of your account.
4. The page “Connect a machine to AO Code” shows the name of this computer. Click “Connect machine”.
5. Go back to the terminal. It says the machine is connected and the key is saved. Next time AO Code starts without this step.

The key of this computer is kept in the .aocode folder in your home folder. It opens AO Code only, not the cabinet. If you do not confirm in the browser in time, the sign-in attempt expires: run aocode again.

If macOS asks at first launch

AO Code has no paid Apple developer signature, so at first launch macOS may say that it cannot verify the developer of “aocode” and offer to move it to the Bin. Do not move it: click “Done”, then open System Settings → Privacy & Security, scroll down to the message about “aocode” and click “Open Anyway”. Run aocode again and confirm “Open”.

You can also remove the download mark from the whole folder at once with this command in Terminal:

xattr -dr com.apple.quarantine ~/aocode

If Windows asks at first launch

AO Code has no paid Windows signature, so Windows may show “Windows protected your PC”. Click “More info”, then “Run anyway”.

To avoid the question, before unpacking right-click the downloaded .zip file, choose Properties, tick “Unblock” and click OK.

6. How many computers

A company can connect no more than three computers to AO Code. Only the account owner connects them and works with AO Code.

The connected computers are listed in the cabinet under Security, in “AO Code machines”: the name, when it was connected, when it was last used and the program version. To connect a new computer when three are already connected, revoke one of them there with “Revoke”: the program on it stops working from its next request.

7. How to work

Open a terminal in the folder of your project and run aocode. You do not need to set up your stack: AO Code reads the project files itself.

At start the program tells whether it found the rules file aocode.md and how many agents are in .aocode/agents/, then asks you to type your question. Write the task in plain words and press Enter. The answer appears as it is written.

AO Code works only with the files of the project folder: it lists them, reads them and writes them. Before every write it shows the file name and size and waits for your “y”. AO Code does not run commands: you build and test the project yourself.

Ctrl+C stops the current answer. /exit or Ctrl+D quits the program.

8. Project rules

Put a file named aocode.md in the root of your project. AO Code reads it at launch and gives it to the model with every question. Write it in plain words: what the project is, how the code is laid out, how to work and what never to do. A changed file takes effect at the next launch.

The file stays in your project; the platform does not keep a copy. A complete example:

# Project: online store backend

## What this is
REST API of an online store. C# 12, ASP.NET Core 9, PostgreSQL, EF Core.

## Layout
- src/Shop.Api: endpoints
- src/Shop.Domain: entities and rules, no framework code
- src/Shop.Infrastructure: database and external services
- tests/: xUnit tests, one test class per class under test

## How to work
- Read the code next to the place you change and follow its style.
- Keep changes small: one task, one change.
- Every new rule gets a test.
- Answer in English; code comments in English.

## Never
- Never edit files in src/Shop.Infrastructure/Migrations by hand.
- Never put passwords, keys or tokens into code or config files.
- Never delete a test to make the build pass.

9. Agents

An agent is a file with instructions for one kind of task. Put agents as .md files into the .aocode/agents folder of your project; the file name without .md is the agent's name. AO Code reads all agents at launch and gives them to the model together with the rules.

To use an agent, name it in your question, for example: “reviewer: check the changes in src/Shop.Api”. An example agent, the file .aocode/agents/reviewer.md:

# reviewer
You review code changes before they go further.
Read the files the question names and the code around them.
List the problems first: bugs, missing tests, broken rules of aocode.md.
For every problem name the file, the place and the fix.
Do not change files yourself: only describe the fix.

• Line 1, “# reviewer”, is the title: it repeats the file name, so it is clear which agent this is.
• Line 2 gives the role: what the agent is for.
• Line 3 says what to read before answering.
• Line 4 says what to look for and in what order.
• Line 5 sets the form of the answer.
• Line 6 sets a limit: what the agent must not do.

Ready agents for common tasks

Tests: the file .aocode/agents/tests.md

# tests
You write tests for the code the question names.
Read the code under test and the tests next to it, and follow their style.
Cover the normal case, the edge cases and the errors.
One test checks one thing; the test name says what it checks.
Do not change the code under test: if it has a bug, describe it.

Documentation: the file .aocode/agents/docs.md

# docs
You keep the project documentation in line with the code.
Read the code the question names and the documents that describe it.
Find the places where a document says something the code no longer does.
Propose new text for each such place, short and in plain words.
Do not touch the code.

Bug fix: the file .aocode/agents/bugfix.md

# bugfix
You find and fix the bug the question describes.
First find the cause: read the code along the path of the error.
Explain the cause in two or three sentences before changing anything.
Make the smallest change that fixes the cause, not the symptom.
Propose a test that fails without the fix and passes with it.

10. Spending and limit

AO Code spends the AI budget of your package, the same budget as the rest of the cabinet. There is one limit: the package budget.

You see how much is used in the cabinet, in the “AI budget” block: two bars, for the week and for the month, as a percentage used.

When the budget is used up, AO Code stops sending requests and prints: “The cabinet's AI budget is used up. The request was not sent.” Work continues when the budget renews or is topped up in the cabinet.

11. If something does not work

AO Code prints the platform's message word for word. Find it below and do what it says.

Only the cabinet owner can connect a machine to AO Code and work with it.

Sign in in the browser with the email of the account owner. Other users of the company cannot work with AO Code.

This cabinet already has 3 of 3 machines connected. Revoke one under Security to connect a new one.

In the cabinet open Security → “AO Code machines”, revoke a computer you no longer use and run aocode again.

AO Code is not enabled for this cabinet: the module is not in its package. Contact platform support to enable it.

Your package does not include AO Code. Contact platform support.

The machine connection request was not found.The connection request has expired. Start signing in from the program again.This connection request has already been used.The connection code is invalid or has expired. Start signing in from the program again.

Run aocode again and confirm the sign-in in the browser right away.

This machine was revoked by the cabinet owner. Sign in from the program again to keep working.The program access key is not recognised. Sign in from the program again.

Run aocode again: the program removes the old key of this computer and starts a new sign-in. If three computers are already connected, revoke one first.

The cabinet's AI budget is used up. The request was not sent.

Wait until the budget renews or top it up in the cabinet.

The cabinet has no active package with an AI budget. The request was not sent.

Check in the cabinet that your package is active and paid.

The model provider did not answer or answered with an error. Try again later.

Ask again in a minute. Nothing else is needed.

The request was interrupted before the model answered.

The answer was stopped before the model replied, for example with Ctrl+C. Ask the question again.

The program sent incomplete machine details.The program sent a malformed request.

Download the latest version from this page and install it over the old one.

The platform address is not configured, so there is no sign-in page to open.The cabinet's package has no agent with the "AO Code · model" capability. Contact platform support.Several agents in the cabinet's package hold the "AO Code · model" capability, so it is unclear which one pays. Contact platform support.No model is chosen for the "AO Code · model" capability, or the chosen one is switched off. Contact platform support.The model has no price yet, so the request was not sent and nothing was charged.The cost cannot be estimated right now: a platform setting is missing. The request was not sent.The model provider is not connected to the platform. The request was not sent and nothing was charged.

This is a setting on the platform side. Contact platform support and quote the message.

12. Boundaries

Your code stays with you. AO Code works in the project folder on your computer. There is no sandbox: nothing runs on our side, and the platform keeps no copy of your project. With each question the model receives the rules, the agents and the files AO Code has read for that question.

We do not store the bodies of requests and answers.

You cannot work with your own model provider key: requests go only through the platform and are paid from the package budget.

AO Code reaches only the files inside the project folder. Files outside it, and the .aocode folder with the key, are closed to it. It does not run commands.

No more than three computers per company; only the account owner connects them.

13. Versions and updates

AO Code does not update itself. When a newer version is out, the program prints one line at launch, “Version X.Y.Z is available — please update.”, and keeps working.

To update, download the new file from this page and install it the same way. On Mac remove the old folder first: rm -rf ~/aocode. On Windows replace aocode.exe in the same folder. On Linux the commands above replace the program in ~/.local/bin.

The computer stays connected after an update: its key is kept in the .aocode folder in your home folder.

aocode --version shows the version installed on your computer.

All versions

• AO Code 0.1.0 · 10/26/2026 Windows · Mac · Linux