Aluy CLI documentation

Installation

Install in one command, as your user, no sudo. The installer resolves the dependencies and puts aluy on the PATH; re-running updates it. The install lives in ~/.aluy.

Linux · macOS

Windows (PowerShell)

Requirements: Linux, macOS or Windows · Node ≥ 20 (the installer ensures it) · ~150 MB free · a connection for the first run.

First steps

On your first aluy, a wizard opens and asks, in this order, for provider, key and model.

• Provider — by default the CLI talks straight to your provider, with your own credential — you bring your own key: pick one and paste it, or point it at a local model. Switch later with /provider.
• Key — goes straight to the OS vault (Keychain on macOS, libsecret on Linux, Credential Manager on Windows). On a headless machine with no vault, it goes to an encrypted file instead. Never in plain text, never in the repo.
• Model — pick the tier with /model; tune the reasoning effort with /effort when you need to.

Then send the first task: open the session, describe the goal (or use a /command) and let the agent work. Every action that touches your files asks for permission.

How much the agent may do without stopping to ask is set when you launch it, and you can change it whenever you want. That is the next section.

Want to turn on long-term memory, more context headroom or local models? Run aluy bootstrap — see the Sidecars section.

Running aluy from your shell

There are three ways to start Aluy, and they answer three different needs.

You want to work with the agent

Type aluy inside your project folder. The session opens in the terminal and you talk to it. Put a goal in quotes and it starts on that instead of waiting for you.

The very first time you run it, the setup assistant opens first and asks for your language, provider, key and model. After that it goes straight to the session.

You want one answer, not a conversation

Use -p. Aluy runs the goal once, prints the result and exits. That is the form you put in a script or a CI job.

The goal can also arrive on stdin, and the output can come back as JSON when something downstream has to read it.

You want to manage the install, not the code

Those are the subcommands. Each does one job and exits without opening a session.

• aluy onboard — set up language, provider, key and model. This is step 2 right after the install, and you can run it again whenever you want to switch.
• aluy doctor — check that the install is healthy. The first thing to run when something is off.
• aluy mcp — connect external tools to the agent.
• aluy cron — schedule a task to run on its own, through your operating system's scheduler.
• aluy bootstrap — install the optional sidecars.

How much freedom the agent gets

This is the decision that matters most, and you make it when you launch.

By default the agent asks before every effect. It reads your project freely. It stops and waits before it writes a file or runs a command.

aluy --plan is stricter. The agent reads, analyzes and proposes, and nothing at all happens to your project. Use it when you want to see the plan before anything moves.

aluy --yolo is looser. The agent approves its own effects and keeps going, so you can walk away. Five command categories still stop and ask, no matter what: destructive commands, network commands, privilege escalation, package installs, and writing to a startup file. So does every tool that comes from an MCP server. Aluy also refuses to start as root.

If you pass both flags, --plan wins.

Picking up where you left off

Aluy saves every session. --continue reopens the last one from this folder. --resume lists what it has saved and lets you pick. --new ignores all of it and starts clean.

Choosing the model

You picked a provider and a model during setup, and that choice sticks. Override it for one run with --tier, or name an exact model with --model. Inside the session, /model does the same without restarting.

Neither flag carries a credential. Your key stays where you put it and is resolved on your machine.

The ceilings

Every session runs under limits, so nothing can loop all night on your budget. The token budget starts at one million, and the model-to-tool loop stops after 300 steps. When a run reaches a ceiling it pauses and asks whether to continue or stop.

You can raise or lower both, and you can change when Aluy compacts the conversation to keep it inside the model's window.

Talking to the session

Inside a running session, a line that starts with / is an order to Aluy itself, not a task for the agent. Type the slash and a menu opens; keep typing to filter it, then Tab or Enter to complete.

There are a few dozen of them. You will use about eight. Here is when you reach for each.

It changed a file you did not want changed

/undo steps the agent's last edit back, and /redo puts it forward again. If the whole conversation went off, /rewind — or Esc Esc — returns to an earlier checkpoint: the code, the conversation, or both.

The session got long and the answers got worse

That is the model's window filling up. /usage shows how full it is. /compact summarizes what is already behind you and frees space without losing the thread. /clear drops the context entirely and starts over.

It keeps making the same mistake

It does not know your project's rules yet. /init reads the repo and writes an ALUY.md with your build commands and conventions — you see the diff and confirm it. From then on, every session starts knowing them.

/memory is the other half. It shows what the agent has picked up on its own, and lets you keep what is right or drop what is wrong.

You want to change how it is running

/model switches the model without restarting. /permissions shows exactly what the agent may do without asking you. /add-dir lets it reach one folder outside the project, for this session only.

Something is broken

/doctor checks the install end to end and prints a fix hint next to whatever failed — see Doctor.

Memory

The agent remembers project decisions and context from one conversation to the next — global and per-project facts. You control all of it with /memory: see what it stored, pin what matters and forget what's no longer useful.

• Long-term memory depends on the mem0 sidecar; without it, only the current session's memory applies.
• /clear memory wipes everything the agent stored (asks for confirmation).

Themes

The session comes in three themes — light, dark and slate — so you can set it to whatever you like looking at all day. Switch with /theme aluy-dark | aluy-light | aluy-slate; your choice is saved.

All three themes share the same spacing and type, so switching does not move anything around.

/cycle — run until done

With /cycle, you describe the task and the agent works in cycles on its own until it's done. You do not have to sit and watch it.

It comes with a handbrake: hard ceilings on time and steps, and an automatic stop if something goes off the rails.

• Good for: fixing tests, mass sweeps, repetitive migrations, long tasks with a clear "done" criterion.
• Every effect that touches your files still passes through the permission gate.

Subagents

Each subagent is a profile (.md file) with its own focus. You ask for the specialist and the agent itself creates the subagent for you — describe what you need ("a security reviewer", "an E2E QA") and it generates the profile with the role, tone and limits. You don't write the .md by hand (but you can edit or create one if you want).

They work in parallel, without mixing contexts: each subagent has its own dedicated sub-session.

Rooms

Rooms (/rooms) put multiple agents talking to each other about the same problem — debating, splitting and combining the work. You follow the conversation in real time and step in when it makes sense.

Telegram — the agent on your phone

Connect a bot and the agent reaches you outside the terminal: it reports when the work ends, asks when it needs a decision from you, and warns when it pauses. You answer from the phone and it carries on.

• Only your chats. The allowlist is closed by default; allow and deny manage the chat ids, and what comes from outside it never becomes an instruction.
• The token lives in the vault, never in a file. aluy telegram logout removes it.
• The destination is not the model's choice. The send tool always answers in the current chat, so an injected message cannot redirect the reply somewhere else.
• What arrives is classified as instruction, data or discard, with a rate limit on the way out and a guard against bot loops.
• It is also how a service reaches you when it needs a decision while you are away.

/telegram does the same from inside a session.

Services — an agent with a routine

Some work does not need you in the room. The test suite should run before you sit down. The dependency report should land on Monday. A service is an agent that does exactly that: it wakes on a schedule, works inside a budget you set, reports on a channel you chose, and goes back to sleep.

Describe what it should do

You do not write the definition by hand. Run /service create and Aluy interviews you — when it should run, what it should do, when to stop, where to report — and writes the draft for you to read.

Read it before you start it

Creating a service does not start it. Starting is a separate, explicit step, and Aluy shows you the whole contract first — the schedule, the budget, the channel, how much it may do on its own, and anything it would run on your machine. Then it asks.

The same care applies to a service someone else wrote. Installing one copies in a directory or clones a repository, shows you everything it declares, and waits for your answer.

Watch it, and talk to it

A running service is not a black box. aluy service attach puts you inside it: you see what it is doing right now, and you can type a line to steer it. Ctrl+C leaves without stopping it. If you only want the output, aluy service logs follows the log.

What keeps it in bounds

Each service lives in its own directory and sees only what is in there — its own agents, skills, commands, rules and connectors. Nothing from your other projects leaks in.

The limits you set are enforced by Aluy itself, not asked of the model. A budget is a budget whether or not the agent agrees.

When a service needs a decision from you while you are away, it asks on the channel you gave it — see Telegram.

Teaching the project

The agent starts every session knowing nothing about your repository. You fix that once, in plain Markdown files, and every session after that starts informed.

You do not need all of them. Start at the top and stop when the agent stops surprising you.

The project's rules — ALUY.md

Put the things you would tell a new teammate on day one: how to build, how to test, what the conventions are, what not to touch. The file sits at the root of your repository and is read into every session.

Do not write it by hand the first time. Run /init and the agent reads the repo and drafts it; you review the diff and confirm.

If your repo already has an AGENTS.md from Codex or a CLAUDE.md from Claude Code, Aluy reads those too, so you do not have to move anything. All the files that are present are composed together, in this order:

A prompt you keep retyping — commands/

When you catch yourself typing the same instruction every week, put it in a file under .aluy/commands/. The filename becomes the command: review.md gives you /review.

Whatever you type after the command is substituted into the text — $1, $2 for each word, or $ARGUMENTS for all of it. With no placeholder, your words are appended at the end.

A specialist — agents/

A subagent is a second agent with a narrower job and its own separate context, so a long review does not crowd out the work you were doing. One file per specialist, in .aluy/agents/.

You usually do not write these by hand either. Ask the agent for the specialist you want — "a security reviewer", "an end-to-end QA" — and it drafts the profile for you. Edit it afterwards if you disagree.

Two things are worth setting yourself. Which tools it may use: a reviewer that can only read cannot accidentally write. Which model it runs on: a cheap one is enough for a summarizer. Leave the tools out and it inherits yours; the body of the file is its instructions.

A procedure with files attached — skills/

A skill is a folder, not a file, because it carries resources alongside the instructions — a template, a schema, a checklist. The agent loads it only when the skill is needed, so ten skills cost nothing until you use one.

The folder name is the skill name, and SKILL.md holds the instructions.

A sequence that always runs the same way — workflows/

A workflow is a numbered list of steps, each one optionally handed to a subagent. Use it when the order matters and you do not want to restate it every time.

What it learned by itself — memory/

This one you do not author. The agent stores facts as it goes, and you curate them from inside the session with /memory — see Memory. Memory is always recalled as data, never as instruction.

Where everything lives

Aluy keeps two homes. The project one is the instruction file at your repo root plus an optional .aluy/ folder — both belong in version control, so your team shares them.

The global one is ~/.aluy/: the install itself, your config, your sessions and the memory that crosses projects. Aluy's own path rules forbid the agent from reading, editing or running anything in there.

MCP — connect tools

Through MCP (the open connector standard), the agent talks to external tools and integrations — databases, APIs, services. That is the difference between an agent that can query your database and one that can only describe how to query it.

Sidecars — memory, headroom and local models

Aluy works without sidecars. They are three optional programs that run on your own machine and give the agent things one process cannot do alone.

mem0 gives the agent memory that outlives the session. Without it, what you explained today is gone tomorrow.

headroom condenses the conversation as it grows, so a long session keeps fitting in the model's window instead of degrading.

ollama runs small models locally for Aluy's own internal work — judging and embedding — so those calls never leave your machine.

All three listen on 127.0.0.1 and nothing else, and none of them starts unless you asked for it. The setup assistant calls the two choices turbo (install them) and leve (install none); you can change your mind later.

Turning them on

One command. It offers each sidecar and you choose.

By default Aluy installs them through its own agent: it works out your operating system, installs the missing prerequisites and handles problems as it goes. Because you asked for this software, that run approves its own steps — choosing turbo is the consent.

That path needs a working model to think with. If you do not have one yet — a brand-new machine, or the model it would use is the very one you are about to install — take the direct path instead. It is deterministic, uses no model at all, and needs Python already present.

When one of them is down

Run /doctor. It tells you which sidecar is not answering. Then run /doctor fix and hand the repair to the agent: it reads the logs, runs the bootstrap again, installs what is missing and retries until all three are green.

If you would rather look yourself, each sidecar writes its own log under ~/.aluy/logs/. The files are truncated on every boot, so what you see is from this run.

Doctor

Run it whenever something stops behaving: after an install, after changing provider, or the first time a session refuses to start.

/doctor is the read-only diagnostic of your install: it checks model, key, connection, MCP and config — and points to a fix hint when something is out of place. It changes nothing, only reads.

FAQ

Does my data go to the cloud?

Your code and your files do not. The session, the history, the project files and the memory stay on your machine. What does open a connection is listed in full on the architecture page: the model call, web search, a web_fetch you approve, the MCP servers you turn on, Telegram if you connect it, and the version check on npm.

Where does my key live?

In the OS vault (Keychain, libsecret, Credential Manager). On a server with no vault, your provider key goes to an encrypted file instead — AES-256-GCM, with the key derived from the machine, so a copy of the directory is useless anywhere else. Either way: never in plain text, never in the repo. Aluy shows the model tier, never the credential.

How does Aluy talk to the model?

By default the CLI talks straight to your own provider, with your own credential (API key, OAuth or a local model): it is your usage, under your control, with no middleman and no metering. A central backend is optional and not available today.

Is there a cost?

Not for Aluy itself — it is free and open source. You pay your model provider for what you use, on your own account and at their prices. The sidecars run on your machine and cost nothing.

Is it safe to leave /cycle running on its own?

/cycle has hard ceilings on time and steps, and an automatic stop. And every action that touches your files passes through the permission gate.

Can I read and modify the code?

The code is public on GitHub under the MIT License: read it, audit it, fork it and open issues. If it runs on your machine, you should be able to read it. Aluy is in beta; expect rough edges and fast iteration.

Architecture

Under the hood, the Aluy CLI is a single process in your terminal — one program, no background server. The terminal interface talks to the core, the engine that reads and edits files, runs commands and decides the next steps. Between the agent and your project sits the permission gate: the single point every effect passes through before it happens.

The state lives on your machine: the session memory (and the long-term one via mem0), your key in the OS vault, your files and your shell. Sidecars are optional local boosters that listen on 127.0.0.1 only.

• What leaves your machine, the whole list: the model call, web search, a web_fetch you approve, the MCP servers you turn on, the sidecars (which only your own machine can reach), Telegram if you connect it, and the version check on npm — which installs the update by itself until you turn that off with ALUY_AUTO_UPDATE=0 — the architecture page lists them in full.

Compatibility — Codex & Claude Code

Already using Codex or Claude Code? Point Aluy at your project and it reads the same instruction and configuration files you already keep, so there is nothing to reconfigure.

Project instruction files

• ALUY.md — the Aluy native file (what /init writes).
• AGENTS.md — the same file Codex (OpenAI) uses.
• CLAUDE.md — the same file Claude Code uses.

When more than one is present they are all read — see Teaching the project for the order.

The same layout

• .md agents accept the Claude Code tool names — mapped to the native ones.
• Hooks in the Claude Code settings.json format, and user commands in .md.
• /rewind and checkpoints work the way they do in Claude Code.