nami alpha Docs

Agents

Let an AI agent such as Claude install apps and change your setup, and ask before it changes the computer.

An agent works with nami the way you do: it runs nami as you. Your own setup, ~/user.nami, is yours to change, so the agent can change it too. The computer’s file, /etc/nami/computer.nami, takes an administrator’s password, which stays with you. For that, the agent asks, and you decide.

Add nami to Claude Code

nami mcp serves nami’s tools to an agent over MCP, on its standard input and output. It opens no network port.

claude mcp add nami -- nami mcp

Any other app that speaks MCP over stdio takes the same command. In Claude Desktop and Cursor, it’s an entry in the app’s MCP settings file:

mcp.json
{  "mcpServers": {    "nami": { "command": "nami", "args": ["mcp"] }  }}

What the agent can do

ToolWhat it does
search, infoFind apps and tools in the catalog
get, check, showRead your file or the computer’s, find mistakes, see the whole computer
history, diffLook back at earlier changes
install, removeInstall or remove your apps, in ~/user.nami
config, apply, undoChange your ~/user.nami, apply it, go back
propose, proposalAsk to change computer.nami, then see the decision

Changes to your own file need no approval, as when you run nami install yourself. Each apply is a change you can undo.

When the agent asks to change the computer

Apps for everyone, services, drivers, the firewall and the people on the computer are in computer.nami. The agent proposes a change, with a reason:

nami propose '[
  {"add": {"path": ["packages"], "value": "docker"}},
  {"add": {"path": ["services"], "value": "docker.socket"}}
]' --by Claude --reason "You asked me to set up Docker for your projects."
proposal 3f9c2a71: waiting for approval
computer.nami
  Apps
    + docker
  Services
    + docker.socket
Review it in Settings, or:
  nami proposals show 3f9c2a71

nami checks the change first, as nami check does, and refuses one that leaves a mistake in the file. Nothing changes yet.

On namiOS, a notification says Claude wants to change your computer. Click Review and Settings opens at Requests. You see the reason, the change in words, and the lines it changes:

/etc/nami/computer.nami
packages:  - firefox  - dockerservices:  - docker.socket

Apply asks for an administrator’s password, then changes the file and applies it. Don’t Allow discards the request. Either way, the agent is told.

Decide in a terminal

nami proposals list            # what's waiting
nami proposals show 3f9c2a71   # the reason, the words, the lines
nami proposals apply 3f9c2a71  # asks for the password, then applies
nami proposals reject 3f9c2a71

An agent that wants the answer before going on adds --wait, and gets it as JSON:

nami propose '{"add": {"path": ["packages"], "value": "docker"}}' \
  --reason "Docker runs the project's test database." --by Claude --wait
{"id": "3f9c2a71", "status": "applied", "by": "Claude", "message": "computer.nami was changed and applied."}

The status is applied, rejected, stale, failed, or pending if --timeout ran out first.

What keeps it safe

  • Only you approve. A request is only a note in your ~/.local/state/nami/proposals. Applying it asks for an administrator’s password, there and then.
  • It’s checked twice. At apply time, nami checks the change again, against the file as it is then.
  • Stale requests are refused. If computer.nami changed after the agent asked, Apply refuses: “computer.nami changed since Claude asked: nothing was changed. Ask for the change again.”
  • You apply what you saw. If the request changes after Settings showed it, Apply refuses it.
  • No secrets. A request can’t carry a secret. Add one yourself, as in Secrets.

Something wrong or missing here? nami report tells us, or Report a problem in the nami window.