Using the CLI

Launching

andromeda                         # full-screen TUI; the current directory is the workspace
andromeda --plain                 # line REPL (automatic when stdin/stdout isn't a terminal)
andromeda --model qwen3:8b        # a different model for this session
andromeda --add-dir ~/notes       # let tools also use another folder
andromeda --listen                # start in hands-free voice mode
andromeda setup                   # model setup and recommendations again (it runs once on first launch)
andromeda whatsapp link           # chat from WhatsApp (see below)

Without the symlink, run scripts/andromeda from the repository or uv run python main.py. Every option is listed under Command-line flags.

MCP servers, the knowledge graph and other slow services connect in the background after the UI opens, so you can start typing straight away. /doctor checks the configured model server and reports model capabilities.

The terminal UI

The TUI is a scrolling transcript with • replies and tool calls, a Working (12s • esc to interrupt) status line and a › composer. Tool calls show what they do: a red/green diff with line numbers for edits, the start of a new file, the command for shell calls. When they finish, a one-line summary replaces the raw output, such as "Read 120 lines", "Updated app.py · +3 −1" or "Found 14 matches".

Set OLLAMA_CONTEXT_WINDOW to your server's context size to see context-used percentages. At 90% the conversation is summarized automatically and the turn continues; see Context compaction.

Permission modes

The mode decides which tool calls need your approval. Switch with Shift+Tab or /permissions auto|plan|ask, and set the default with agent.permission_mode.

In every mode, the CLI asks before a destructive or outward-facing shell command (rm, sudo, git push, git reset --hard, curl … | sh, DROP TABLE, …) and before creating or running a tool the model wrote. Answering always approves only that exact command or tool for the rest of the session. Turn this off with agent.confirm_destructive: false.

Plan, review, then build

1. Switch to plan and describe the change. The agent reads and searches, writes a plan with update_plan and summarizes it, leaving the steps open.
2. Read it with /plan (or open the Markdown file under .andromeda/plans/), edit it if you like, and ask for changes until it's right.
3. Switch back to auto and say "go ahead". The agent carries the saved plan out step by step, and a turn can't end with steps left undone.

See Planning & verification for how plans and the verifier work.

Slash commands

Read-only commands (/status, /context, /usage, /diff, /plan, …) run immediately, even while a turn is in progress. Others queue behind it.

Session and model

Conversations and context

Working on code

Tools, agents and media

Learning

Shell & teach mode

Start a line with ! to run a shell command in the workspace yourself. The output is shown and sent along with your next message, so you can say "fix this" after a failing test run:

› !python -m unittest tests.test_calc
› the divide test fails, fix it

Teach mode turns a task you do yourself into a reusable skill:

› /teach release-notes write release notes from git
› !git log --oneline v1.2..HEAD
› /teach note fixes go before features
  … edit files in your editor …
› /teach stop          # shows the drafted SKILL.md
› /teach save          # keeps it under skills/learned/ (or /teach discard)

Only ! commands and file changes inside the workspace are recorded; nothing watches in the background. /teach cancel stops without drafting.

Command-line flags

scripts/andromeda adds two launcher flags: --kokoro-tts (default environment, Kokoro active) and --qwen-tts (the .venv-qwen environment, Qwen active). Everything else is passed on to main.py.

Managing MCP servers

Add Model Context Protocol servers the same way as claude mcp or codex mcp. Servers connect the next time Andromeda starts.

# stdio: everything after -- is the command line
andromeda mcp add playwright -- npx -y @playwright/mcp@latest
andromeda mcp add -e API_KEY='${MY_KEY}' myserver -- uvx my-mcp-server

# remote (Streamable HTTP by default; --transport sse for legacy servers)
andromeda mcp add --transport http postman https://mcp.postman.com/minimal \
    --header 'Authorization: Bearer ${POSTMAN_API_KEY}'

andromeda mcp list            # connects to each server and reports ✓/✗
andromeda mcp get postman
andromeda mcp remove postman

Put single quotes around ${VAR} so your shell doesn't expand it; the config then stores the reference, not the secret. Other options: --scope project|user, --description, --always-loaded and --force. See MCP servers for the config files and per-server options.

Chat from WhatsApp

Message Andromeda from your phone. It links to your own account like WhatsApp Web, using an unofficial client (Baileys) that needs Bun.

andromeda whatsapp link      # scan the QR code: WhatsApp → Settings → Linked devices
andromeda whatsapp status
andromeda whatsapp unlink

Then set whatsapp.enabled: true in andromeda.yml, start Andromeda, and message yourself:

whatsapp:
  enabled: true
  
  allowed: []        # other numbers, digits with country code, e.g. ["447700900123"]
  notify: true       # also send schedule results and check-ins to your own chat
  reply_prefix: "🤖 "

• Who it answers: your own "Message yourself" chat and the numbers in allowed. Everyone else is ignored.
• Conversations: each chat is its own thread, sharing long-term memory with the terminal. Replies start with the prefix so you can tell them apart in your own chat.
• Approvals: anything that needs approval is asked in the chat; reply yes, always or no (no answer in five minutes means no).
• Text only for now; voice notes and images get a short reply saying so. The session is stored in the project's .andromeda/whatsapp/.