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

The prebuilt binary embeds its own Node runtime, so you do not need Node to use a release. Building or running from source requires Node.js 25.7.0 or newer (see Installing from source).

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, memory: manage state without an interactive session. update and uninstall manage the install itself.

Running atomic-agent with no arguments opens the TUI. The install script also adds atag as a short alias, so atag run works the same as atomic-agent run. atomic-agent --version prints the installed version, and atomic-agent help <command> shows a command’s help.

Quick start

Interactive chat

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

# Pin a working directory and a hard step ceiling for each task
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 failure, 2 on a usage error for run, skill, memory, update, uninstall and unknown commands. config, serve, trace, task, models and import return 1 for usage errors too, and trace replay returns 2 when it detects drift. The CLI reference has the full detail.

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: hard ceiling on steps for one task. Without it, the agent works in legs of agent.maxSteps (25) steps and keeps going automatically up to agent.task.maxSteps (1000) or 2 hours.
• --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. serve also runs any enabled Telegram and Discord channels in the same process. See the HTTP server reference 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]
                 [--onboarding] [--mouse | --no-mouse]

--onboarding runs first-time setup again (providers, keys, and sessions are kept). --no-mouse turns terminal mouse support off for one run, which restores the terminal’s own drag-to-select; --mouse forces it on. The TUI needs an interactive terminal; in scripts, use atomic-agent run.

models

Manage local llama.cpp models and the inference daemon. start and update need localModels.mode = 'managed'; in external mode (the shipped default) you point at a llama-server you run yourself. use <id> switches you to managed mode, and list, pull, remove, devices and status work in either mode.

atomic-agent models list                 # available chat models
atomic-agent models pull <id>            # download a GGUF model (resumes a partial)
atomic-agent models pull <id> --background  # keep downloading after the terminal closes
atomic-agent models pull <id> --mmproj   # also fetch the vision projector
atomic-agent models downloads            # background downloads; `cancel <id>` or `clear`
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

# Search your configured cloud providers' models (no local runtime needed)
atomic-agent models search claude vision
atomic-agent models search <query> [--provider ID] [--limit N] [--json] [--refresh]

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:

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

# macOS (BSD date)
atomic-agent task create --message "post the digest" \
  --at "$(date -j -u -f '%Y-%m-%dT%H:%M:%SZ' 2026-08-18T09:00:00Z +%s000)"

task run and task tick skip approvals

task run and task tick execute at approval level 5: every gated action (shell, file writes, HTTP) runs without asking, whatever agent.approvalLevel says. Only queue tasks you would be comfortable running unattended.

Note

task tick drains due tasks once and exits (recurring tasks are requeued for their next firing as usual). It is meant for cron jobs and manual ops and does not start the long-lived scheduler. For continuous background autonomy, leave the scheduler on (ATOMIC_AGENT_TASKS_SCHEDULER_ENABLED, on by default) with tui or serve running. Task settings are environment variables, not config.json keys.

config

Read and edit <stateDir>/config.json, one key at a time.

atomic-agent config get                  # whole file as JSON
atomic-agent config get <key>            # one value, e.g. log.level
atomic-agent config set <key> <value>    # one value, rest of the file untouched
atomic-agent config set '<json>'         # replace the whole file (missing keys get defaults)
atomic-agent config unset <key>          # restore one key to its default
atomic-agent config list                 # every key as key = value
atomic-agent config path                 # where config.json lives

For example, atomic-agent config set log.level debug or atomic-agent config set agent.approvalLevel 2. Values are typed and validated before anything is written. List-valued keys such as projects.roots need the whole-file form.

config set '<json>' replaces the whole file

With a JSON argument, config set resets every key you leave out, including your LLM providers, MCP servers, and an analytics opt-out. Use config set <key> <value> for single changes. See Configuration for details.

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> [--step N]   # 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 from another agent: Claude Code, Codex, Hermes, OpenClaw, Pi or Oh-My-Pi.

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]
atomic-agent import claude-code|codex [--source DIR] [--include a,b] [--exclude a,b]
                             [--migrate-secrets] [--limit N] [--overwrite] [--dry-run] [--yes]
atomic-agent import pi|oh-my-pi [--source DIR] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

Every subcommand takes --include / --exclude (comma-separated option names) to adjust what gets imported; the options differ per source (sessions, cron, skills, memory, MCP servers). Imports are idempotent and dry-run capable (--dry-run). Key migration is opt-in (--migrate-secrets, for Claude Code, Codex and Hermes). See the Import guide for what each source brings.

memory

Export the memory store (notes, lessons, procedures) into an Obsidian vault as Markdown files. The export is one-way and idempotent, and never touches files it did not write.

atomic-agent memory export --vault ~/Documents/MyVault [--folder NAME]

--vault defaults to $OBSIDIAN_VAULT_PATH; --folder defaults to atomic-agent.

update

Self-update the installed binary from GitHub Releases. The new version takes effect on the next launch.

atomic-agent update                    # install the latest release
atomic-agent update --check            # only report current vs latest
atomic-agent update --version v0.6.5   # install a specific release

uninstall

Remove Atomic Agent from this machine: the state directory (config, memory, sessions, tasks, traces, downloaded models), the binary and its atag alias, and the installer’s PATH line. It cannot be undone.

atomic-agent uninstall --dry-run       # show what would be removed
atomic-agent uninstall --keep-data     # remove the program, keep your data
atomic-agent uninstall [--keep-binary] [--keep-path] [--yes]

repl

A scaffolded debug REPL (atomic-agent repl), hidden from --help and 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 Claude Code, Codex, Hermes, OpenClaw, Pi or Oh-My-Pi
Integrations	Connect external services and store their tokens in .env
Swarm	Configure swarm bots
Privacy	Set your standing approval level and the analytics switch

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 (alias /run), /observe, /manage, /feed, /logs, /reasoning, /world, /debug
• Panels: /tasks, /task, /skills, /skill, /memory, /mcp, /integrations, /swarm, /telegram, /import, /llm, /privacy
• Model: /model (aliases /models, /local), /runmode, /mode
• Sessions: /sessions, /session, /new, /clear, /context, /window
• Turn control: /abort, /steer, /queue, /quit (alias /exit)
• Appearance: /theme, /expand, /collapse, /sidebar, /mouse, /dump
• Setup and help: /onboarding (alias /setup), /analytics, /tools, /report, /help, /uninstall

/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": 16384,      // 0 = no client-side cap
    "managed": { "modelId": null, "port": 19091, "device": "auto" }
  },
  "agent": {
    "maxSteps": 25,                    // steps per leg; --max-steps overrides agent.task.maxSteps
    "task": { "maxSteps": 1000, "maxDurationMs": 7200000, "autoContinue": true },
    "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, process kills, network git, publishing, and Fusion fan-out, and 5 approves everything, including reads outside the working directory and sending email. --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 <key> <value>, or live from the TUI’s Manage panels.

Config is a snapshot

The runtime freezes config at startup. Editing config.json while the agent is running, by hand or with config set, won’t take effect until the next launch. The TUI panels are the supported way to change settings live. Avoid HTTP PATCH /api/config in v0.6.5: it resets most of the file (see the HTTP server page).

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	Overrides localModels.completionMaxTokens (default 16384) for this process, clamped 64 to 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.