CLI & TUI

Atomic Agent runs entirely from your terminal. There’s no web console to log into and no account to create — you type atomic-agent, and the agent works on your machine, against your files, with your local model.

This page covers the two ways you’ll drive it day to day: the interactive chat (atomic-agent run) for quick one-off tasks, and the TUI (atomic-agent tui) — a full-screen interface with tabs for watching the agent think and managing everything from tasks to models.

Developer Preview

Atomic Agent is a Developer Preview. Commands, flags, and config keys are still moving. Pin a release if you’re scripting against it.

Pick your surface

Interactive chat

atomic-agent run — a plain stdin/stdout chat loop. Fast to start, easy to script, diagnostics go to stderr.

Full-screen TUI

atomic-agent tui (or just atomic-agent) — chat plus live panels for feed, logs, tasks, memory, models, and more.

HTTP server

atomic-agent serve — an OpenAI-compatible API for apps and scripts. See the Serving guide.

One-shot ops

atomic-agent task, config, models, skill, trace — manage state without an interactive session.

Running atomic-agent with no arguments opens the TUI.

Quick start

Interactive chat

# Start a chat in the current directory
atomic-agent run

# Pin a working directory and a step budget
atomic-agent run --cwd ~/projects/site --max-steps 40

# Auto-approve dangerous tools (dev only — no prompts)
atomic-agent run --no-approval

TUI

# Launch the full-screen interface
atomic-agent tui

# Same flags as run
atomic-agent tui --cwd ~/projects/site --max-steps 40 --no-approval

# Skip the first-run llama setup wizard
atomic-agent tui --skip-llama-setup

In run mode you type a message, press Enter, and the agent replies on stdout. Replies are collapsed to a single line (newlines become spaces) so line-oriented drivers stay in sync — the full text lives in the trace.

Command reference

Every command is a subcommand of atomic-agent. Exit codes: 0 on success, 1 on a runtime or logic error, 2 on bad arguments.

run

Interactive agent in your terminal.

atomic-agent run [--cwd DIR] [--max-steps N] [--no-approval]

• --cwd DIR — working directory for file and shell tools (defaults to the current directory).
• --max-steps N — max LLM steps per turn before the agent stops.
• --no-approval — bypass the approval gate and auto-approve all dangerous tools.

When approval is on, dangerous tools (shell, file writes, HTTP requests, and others) pause and prompt over stdin before running.

serve

Start the OpenAI-compatible HTTP server.

atomic-agent serve [--host 127.0.0.1] [--port 8787] [--cwd DIR] [--api-key KEY] [--no-approval]

If --api-key is omitted, the server falls back to the ATOMIC_AGENT_API_KEY environment variable. See the Serving guide for endpoints and authentication.

tui

Launch the full-screen terminal interface (covered in detail below).

atomic-agent tui [--cwd DIR] [--max-steps N] [--no-approval] [--skip-llama-setup]

models

Manage local llama.cpp models and the inference daemon. These commands require localModels.mode = 'managed' in config — in external mode you point at a llama-server you run yourself.

atomic-agent models list                 # available chat models
atomic-agent models pull <id>            # download a GGUF model
atomic-agent models use <id>             # set the active model
atomic-agent models status               # daemon health
atomic-agent models start                # start the llama-server daemon
atomic-agent models stop                 # stop it
atomic-agent models update               # update the llama.cpp backend
atomic-agent models remove <id>          # delete a downloaded model

# GPU device selection
atomic-agent models devices              # enumerate GPUs
atomic-agent models use-device <auto|cpu|Vulkan0>

# Embedding models (for hybrid memory recall)
atomic-agent models list-embeddings
atomic-agent models pull-embedding <id>
atomic-agent models use-embedding <id>|--disable

The default chat model on a fresh install is qwen-3.5-4b; the default embedding model is nomic-embed-text-v1.5. The embedding daemon runs on a separate port — if it fails to start, chat keeps working and memory recall falls back to keyword (FTS5) search.

task

Durable, deferred, and recurring agent runs. See the Tasks guide for scheduling semantics.

atomic-agent task list [--session ID] [--status CSV] [--limit N]
atomic-agent task show <id>
atomic-agent task create --message TEXT [--at MS|--cron EXPR|--every SEC] [--tz IANA] [--max-attempts N] [--max-steps N]
atomic-agent task cancel <id>
atomic-agent task run <id>|--all-pending [--session ID]
atomic-agent task tick [--limit N]      # one-shot drain of due tasks

Caution

task tick drains due tasks once and is meant for cron jobs and manual ops — it does not start the long-lived scheduler. For continuous background autonomy, run the scheduler (enabled via tasks.schedulerEnabled).

config

Read and write <stateDir>/config.json.

atomic-agent config get
atomic-agent config set '<json>'        # merge-write a JSON fragment

skill

Manage installed skills (local playbooks the agent can load and run).

atomic-agent skill install <path> [--force]
atomic-agent skill uninstall <name>
atomic-agent skill list
atomic-agent skill show <name>
atomic-agent skill enable <name>        # mutates skills.disabled in config.json
atomic-agent skill disable <name>

trace

Inspect append-only NDJSON session traces for post-mortem analysis.

atomic-agent trace list [--limit N]
atomic-agent trace show <sessionId> [--step N] [--raw]
atomic-agent trace export <sessionId> [--format ndjson|json]
atomic-agent trace replay <sessionId>   # detect prompt-stack drift

trace replay rebuilds the stable prompt prefix with your current tools, capabilities, and skills, then compares hashes against what was recorded. It flags drift — useful after upgrading a model or changing your skill set. It exits 0 when no drift is found, 2 when drift is detected.

import

Migrate sessions and scheduled tasks from a legacy agent.

atomic-agent import hermes [options]
atomic-agent import openclaw [options]

Imports are idempotent and dry-run capable (--dry-run). Secrets migration is opt-in (--migrate-secrets, Hermes only). See the Import guide.

repl

A scaffolded debug REPL (atomic-agent repl), reserved for future expansion.

The TUI

The TUI is a long-lived React/Ink application. The runtime, model daemon, and panels survive across turns and sessions — only the session state swaps when you start a new chat. Sessions are created lazily on your first message, so opening the TUI just to glance at settings won’t clutter your session store.

The layout has three sections — Run, Observe, and Manage — and a sidebar of recent sessions you can switch between. The sidebar collapses automatically below 100 columns of terminal width, and focus snaps back to the editor so you never lose keyboard control.

flowchart TD
    A["atomic-agent tui"] -->|parse flags, detect theme| B["TuiApp"]
    B -->|keyboard| C["handleAppKey / tab handlers"]
    B -->|submit message| D["ChatOrchestrator"]
    D -->|runtime.runTurn| E["AgentRuntime"]
    E -->|AgentLoopEvent| F["TuiEventBus"]
    F -->|dispatch action| G["reduceTuiState"]
    G -->|re-render| B
    B --> H["Run section: chat"]
    B --> I["Observe section"]
    B --> J["Manage section"]
    I --> I1["Feed · Logs · Reasoning · World"]
    J --> J1["Tasks · Skills · Memory · MCP"]
    J --> J2["Providers · Local Models · Telegram · Import"]

Run — chat

The default view. Type, press Enter, watch the agent reply. This is where you do the actual work.

• Submit a message with Enter.
• Scroll history with PageUp / PageDown or j / k.
• Esc from a scrolled position snaps you back to the bottom before doing anything else.

Observe — watch the agent think

The Observe tabs surface what’s happening inside each turn, driven live by the agent loop’s event stream:

• Feed — the high-level step-by-step activity: tool calls, results, replies.
• Logs — structured runtime log records.
• Reasoning — the model’s <think> blocks (for reasoning-capable models).
• World — the compressed browser/ARIA snapshot from the last navigation.

Manage — control everything else

The Manage tabs are full panels, each with its own state and keybindings:

Panel	What you do here
Tasks	View, create, and cancel scheduled/recurring tasks
Skills	Toggle skills on/off (writes skills.disabled), inspect bodies
Memory	Browse profile facts, notes, lessons, and procedures (read-only)
MCP	Add, remove, restart, and enable MCP servers live
Providers	Configure and reload LLM providers
Local Models	Pull, start, stop, and switch managed models and GPU devices
Telegram	Pair an owner, set token, toggle the remote-control channel
Import	Migrate from Hermes or OpenClaw

Changes in these panels apply live where possible — installing a skill or adding an MCP server rebuilds the agent’s tool catalog without restarting the process.

Slash commands

Type / in the editor to open the slash palette. While it’s open, navigation keys route to the palette so up/down/enter work for selection.

Common commands:

• Navigation: /chat, /observe, /manage, /feed, /logs, /reasoning, /world, /debug
• Panels: /tasks, /task, /skills, /skill, /memory, /mcp, /telegram, /import, /llm, /models
• Sessions: /sessions, /new, /clear
• Turn control: /abort, /quit
• Appearance: /theme, /expand, /collapse, /dump
• Help: /help

/theme opens a live preview — moving through the picker repaints the whole UI; Esc reverts to your original theme.

Keyboard shortcuts

Key	Action
Enter	Submit message
Esc	Abort turn / close modal / snap to bottom / quit (context-dependent)
Tab / Shift+Tab	Navigate between tabs and elements
Ctrl+B	Forward navigation
PageUp / PageDown	Scroll chat
j / k	Scroll line by line
y / n	Approve / deny a pending tool (when the approval modal is up)
Ctrl+C (double-tap)	Quit — press twice within 1.5 seconds

Tip

The approval modal claims y, n, and Esc, but other keys still fall through — so Ctrl+C to quit always works, even mid-approval.

Themes

Set a theme in config (tui.theme), or use 'auto' to detect your terminal’s background and pick a matching palette at startup. /theme lets you preview and switch interactively.

Configuration

The CLI and TUI read from <stateDir>/config.json (default ~/.atomic-agent, overridable with ATOMIC_AGENT_STATE_DIR). Keys you’ll touch most from these surfaces:

{
  "localModels": {
    "url": "http://localhost:8000",   // llama-server endpoint
    "mode": "managed",                 // 'managed' runs the daemon; 'external' expects your own
    "managed": { "modelId": "qwen-3.5-4b", "port": 8000, "device": "auto" }
  },
  "agent": {
    "maxSteps": 25,                    // default --max-steps
    "approvalRequired": true,          // false ≡ --no-approval
    "tokenBudget": 3000
  },
  "tui": { "theme": "auto" },
  "tasks": { "schedulerEnabled": true, "schedulerTickMs": 5000 }
}

Edit it by hand, with atomic-agent config set, or live from the TUI’s Manage panels.

Config is a snapshot

The runtime freezes config at startup. Hand-editing config.json while the agent is running won’t take effect until the next launch — the TUI and HTTP API are the supported ways to change settings live. After a config set from a script, the next process picks up the change.

Useful environment variables

Variable	Purpose
ATOMIC_AGENT_STATE_DIR	State + config + traces + tasks directory (default ~/.atomic-agent)
ATOMIC_AGENT_LLAMA_URL	llama-server connection string
ATOMIC_AGENT_LLAMA_API_KEY	Bearer token for llama-server (optional)
ATOMIC_AGENT_LLAMA_MAX_TOKENS	Max new tokens per completion (default 4096, clamped 64–131072)
ATOMIC_AGENT_API_KEY	Fallback bearer token for serve
ATOMIC_AGENT_RG_PATH	Override the bundled ripgrep binary
ATOMIC_AGENT_BROWSER_CHANNEL	chrome | msedge | chromium (default chrome)
ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP	Skip the first-run model setup wizard

Where to go next

Serving an API

atomic-agent serve — OpenAI-compatible endpoints, auth, and webhooks.

Tasks & scheduling

Defer work, run cron jobs, and drive background autonomy.

Local models

Pull GGUF models, pick a GPU, and tune the managed daemon.

Skills

Install playbooks that teach the agent domain-specific workflows.