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.

Runtime requirement

Atomic Agent requires Node.js 25.7.0 or newer. Older runtimes fail at install time.

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

# Force approval level 5 — nothing asks (dev only)
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 — force approval level 5 (approve everything) for this process. The flag is one-directional: it can only lower strictness for one run, never raise it.

At the default approval level (1), dangerous tools (shell, file writes, HTTP requests, and others) pause and prompt over stdin before running.

Answering the approval prompt

The prompt takes four answers, not two:

Answer	Effect
y	Approve this one call.
s	Approve, and allow this whole category (file writes, HTTP, shell…) for the rest of the session.
a	Approve, and allow this shell command shape for the rest of the session.
N	Deny. Anything that isn’t y, yes, s, or a counts as a refusal.

s and a only show up when the request is grantable. Writes to the agent’s own trust config (config.json, .env) are never grantable — those only ever offer y/N, because a silent write there could raise the approval ladder for the next boot.

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 (the shipped default) 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

A fresh install has no active model: localModels.managed.modelId is null until you pull one. qwen-3.5-4b is what the first-run setup wizard suggests, not a preinstalled default. models use <id> sets the active model and flips localModels.mode to managed for you, so you don’t have to edit the mode by hand.

The managed chat daemon listens on port 19091 and the embedding daemon on 19092. If the embedding daemon 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] [--notify telegram] [--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

--notify telegram pings you over the Telegram channel when the task finishes; telegram is the only value it accepts. --tz is only valid together with --cron — passing it alongside --at, --every, or no schedule at all is an error.

--at takes epoch milliseconds only

--at is parsed with parseInt, so an ISO date string is not accepted — and it fails silently rather than loudly. --at 2026-08-18T09:00:00Z parses to the number 2026, a timestamp 56 years in the past, and the task fires immediately. Pass milliseconds since the Unix epoch:

atomic-agent task create --message "post the digest" \
  --at "$(date -d '2026-08-18T09:00:00Z' +%s000)"

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, leave the scheduler on (ATOMIC_AGENT_TASKS_SCHEDULER_ENABLED, on by default). Task settings are environment variables, not config.json keys.

config

Read and write <stateDir>/config.json.

atomic-agent config get
atomic-agent config set '<json>'        # REPLACES the whole file

config set takes the whole document

config set is a whole-document write, so pass a complete config rather than a fragment. Read, edit, write back:

atomic-agent config get > /tmp/config.json
# edit /tmp/config.json
atomic-agent config set "$(cat /tmp/config.json)"

skill

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

atomic-agent skill install <path|owner/repo[/path]|@owner/slug> [--force] [--acknowledge-risk]
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>

# Discover skills to install
atomic-agent skill browse [--source owner/repo]
atomic-agent skill search <query>
atomic-agent skill tap list|add <owner/repo>|remove <owner/repo>

install takes three kinds of source: a local directory, a GitHub tap (owner/repo, optionally with a path inside it), or a ClawHub slug (@owner/slug). browse and search cover ClawHub plus every configured tap; tap manages that tap list in config.json, which ships with anthropics/skills, openai/skills, and vercel-labs/agent-skills.

Caution

A remote skill is somebody else’s code and can carry runnable scripts. install scans a remote skill first and refuses anything it flags as suspicious; --acknowledge-risk is how you override that refusal. Read the SKILL.md and its scripts before you rely on it.

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   [--source DIR] [--preset default|full] [--include a,b] [--exclude a,b]
                             [--migrate-secrets] [--limit N] [--overwrite] [--dry-run] [--yes]
atomic-agent import openclaw [--source DIR] [--agent NAME] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

Both subcommands take --include / --exclude (comma-separated, sessions and cron) to adjust what gets imported. 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 you can switch focus into. The sidebar collapses automatically below 100 columns of terminal width, and focus snaps back to the editor so you never lose keyboard control.

The sidebar holds two panes, not one: Sessions (recent conversations) and Tasks. Tab cycles editor → Sessions → Tasks → editor, so a third press always returns you to typing. Inside the rail, Up / Down move the cursor within the focused pane, Enter activates the row — switching to that session, or, on a task row, opening it in the Tasks tab — and Esc or Ctrl+B drops focus back to the editor without cycling through the second pane.

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. For a second line without sending, press Alt+Enter (Shift+Enter and Ctrl+Enter work too), or end the line with a backslash.
• Scroll history with PageUp / PageDown. When the editor is empty, plain Up / Down scroll too; with text in the editor they walk your input history instead.
• 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.
• LLM logs — a live tail of llama-server.log, polled once a second while the tab is open. This is the first place to look when a local model won’t start: the daemon’s own startup errors land here, not in the Logs tab. L from the LLM tab jumps straight to it.

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
Up / Down	Scroll chat when the editor is empty; otherwise walk input history
Alt+Enter	Newline without sending (Shift+Enter, Ctrl+Enter, or a trailing \ also work)
Ctrl+A / Ctrl+E	Jump to start / end of the line
Ctrl+U / Ctrl+K	Delete to start / end of the line
Ctrl+W	Delete the word before the cursor
y / s / a / n	Approve once / allow this category this session / allow this command shape this session / deny (when the approval modal is up)
Ctrl+C (double-tap)	Quit — press twice within 1.5 seconds

The modal shows s and a only when the request is grantable. Session grants are never persisted — to raise your standing approval level, use the Privacy tab (/privacy), which writes agent.approvalLevel.

Tip

The approval modal claims y, s, a, 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://127.0.0.1:8080",   // llama-server endpoint
    "mode": "external",                // 'external' expects your own server; 'managed' runs the daemon
    "completionMaxTokens": 8192,
    "managed": { "modelId": null, "port": 19091, "device": "auto" }
  },
  "agent": {
    "maxSteps": 25,                    // default --max-steps
    "approvalLevel": 1,                // 1–5 ladder; 5 ≡ --no-approval
    "tokenBudget": 3000
  },
  "tui": { "theme": "auto" }
}

agent.approvalLevel replaced the old boolean agent.approvalRequired in schema v37. It runs 1 to 5, cumulatively: 1 asks about everything (the default), 2 stops asking about file writes inside your working directory, 3 adds writes anywhere under your home directory, moves to Trash, and HTTP requests, 4 adds shell commands, skill scripts, and process kills, and 5 approves everything. --no-approval forces 5 for one process.

Task settings are not in this file — the task queue is configured through ATOMIC_AGENT_TASKS_* environment variables only (see below).

Edit it by hand, with atomic-agent config set (which replaces the whole file), 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_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
ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP	Check for a newer release at startup (default true)

Task queue

The task queue has no config.json block — these variables are the only way to configure it.

Variable	Default	Purpose
ATOMIC_AGENT_TASKS_ENABLED	true	Master switch for the durable task queue
ATOMIC_AGENT_TASKS_MAX_ATTEMPTS	3	Default retry budget per task
ATOMIC_AGENT_TASKS_RUN_ON_CREATE	true	Run an unscheduled task immediately when created
ATOMIC_AGENT_TASKS_SCHEDULER_ENABLED	true	Run the long-lived background scheduler
ATOMIC_AGENT_TASKS_SCHEDULER_TICK_MS	5000	Scheduler poll interval
ATOMIC_AGENT_TASKS_MIN_INTERVAL_MS	1000	Floor on --every intervals

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.