Aluy CLI v1.0.0-rc.180
EN PT
architecture

One point decides everything.

The Aluy CLI is one process in your terminal. It reads and edits files, runs commands, and keeps the session, the memory and your key on your machine. Between the model proposing an action and the action happening there is exactly one function — and no path goes around it.

the turn

What happens between enter and the answer.

The cycle of one turn in the Aluy CLI You type a goal. The context is assembled from memory, the project instructions and the tool list. The call goes out to the model, the only step outside your machine. The answer becomes a tool proposal, which passes through the permission gate. The gate denies, asks or allows. The tool runs and the result comes back to the model, closing the cycle. the result goes back into the context you type the goal or a !command — it goes the same way the context is assembled rebuilt each turn, never piled up project and global memory ALUY.md and the allowed roots the tool list of the moment the model call your provider, with your credential the only step off your machine the answer becomes a proposal a native tool call, or a block in the text both end at the same place THE GATE one point — five ways in, no way around denies asks allows the model is told, nothing changes waits for you. no human: it blocks the tool runs the file changes, the command runs

The !command you type at the prompt is not a shortcut: it builds the same tool proposal and goes through the same decision. Same for subagents, for hooks and for /init.

the gate

What it lets through, and what it stops.

The base rule is to deny. What gets through is written in code, not in the prompt — so there is no text that talks the model past it.

allow

goes straight through

Only what reads and changes nothing: read file, grep, glob and list. Plus writing a memory and speaking in a room.

ask

always asks

Running a command, editing and writing a file. And any tool it does not know — including every tool that comes from an MCP server.

deny

denies, does not ask

Reading ~/.ssh, ~/.aws, ~/.gnupg, private keys and certificates. And its own ~/.aluy/ folder — it may neither read it nor write to it.

what never loosens
Five categories, not even by config. Destructive commands, network commands, privilege escalation, package installs, and writing to a startup file.
MCP tools are locked apart. Every tool from an MCP server is its own locked category.
The panel touches only two. The /permissions panel can only touch two read tools — the rest shows up locked.
And the exception, in full.

--yolo returns allow before any of this. Under it the agent reaches its own ~/.aluy/ folder — the MCP config, the hooks, the undo journal and the credential vault. That is a deliberate decision of the mode, not a hole. Everywhere else, that rule holds.

the modules

Two halves, with a border the build enforces.

The component map of the Aluy CLI Three zones. Inside the aluy process live the TUI, the session and the core — the turn cycle, the context assembly, the native tools, memory, the encrypted journal, the MCP client and the gate — plus the ports. On your machine, in another process, live the mem0, headroom and ollama sidecars, the MCP servers and background services. Off your machine are your model provider, web search and Telegram. Only the ports cross outward. INSIDE THE aluy PROCESS one binary; none of this is a service the TUI terminal, panels, themes, the slash menu the session the state of what is going on THE CORE — does not know what a screen is the turn cycle the context assembly the native tools memory the encrypted journal (undo) the MCP client THE GATE decides everything that changes anything the ports shell · files · search · network · vault — everything that leaves goes through here ON YOUR MACHINE, ANOTHER PROCESS only if you install it; loopback, no credential mem0 long-term memory, in a sidecar headroom long conversations without losing the thread ollama models running on your own machine MCP servers · services child processes, standard input and output OFF YOUR MACHINE what crosses the network your model provider ten in the catalog, plus whatever you declare web search the search engine, and the web_fetch you approve Telegram · npm if you connect it; and the version check
what the drawing can’t show
The provider, pinned to the IP. The connection to your provider is pinned to the IP it resolved and refuses redirects.
Telegram, out of the model’s reach. The destination of a message is not an argument of the model, so an injected instruction cannot send anything elsewhere.
The update, by itself. The version check installs the update by itself until you turn it off with ALUY_AUTO_UPDATE=0.
the state

Where each thing lives.

All under ~/.aluy/, readable only by your own user account — no other account on the machine gets in. There is no database anywhere: the memory index is a Markdown file you can open and edit.

sessions/

session and transcript

One JSON per session, with the blocks of the conversation and what you ran.

undo/

undo journal

The previous state of each file, encrypted. The key belongs to the session and dies with the process — undo does not survive a restart.

memory/

memory

Markdown: one global, one per project. One fact per line, editable by hand.

keyring

credential

In the OS vault, or an encrypted file where there is none — with the key derived from the machine, never written down.

config.json

configuration

Theme, model, backend, profile, services. Plus the hooks and the MCP servers, each in its own file.

agents/ skills/

what you write

Agents, commands, skills, workflows and plugins: .md files you can put in version control.

Read the documentation →