Sessions & Undo

AtomCode persists every conversation by default, so you can restore, resume, clear, or compact at any time. A single /undo rewinds conversation memory back to any earlier turn.

Session lifecycle

Each atomcode launch creates a session. A session contains:

• Full message history (user prompts, AI replies, tool calls)
• The associated working directory
• The associated provider / model
• Token usage stats
• File-history snapshots of every file edit made in that session

Session data is persisted under ~/.atomcode/sessions/, grouped by project (working-directory hash).

Resuming sessions

Continue the last one from the CLI

atomcode -c        # or atomcode --continue

The most common case: pick up exactly where you left off yesterday.

Switch sessions inside the TUI

/resume

Opens the session picker. It lists this project's historical sessions newest-first; jump to any of them quickly. Each entry uses the most recent user prompt as its label for easy recognition.

While a turn runs, select another session in /resume or run /resume <id>. The current session keeps running in the background; the view switches only after the target is ready. A failed open leaves the current session intact. Returning to a background session in this process reuses its runtime instead of restarting the task. Use /bg list to inspect up to 16 background slots.

Switching remains restricted while awaiting approval or interactive input, reconfiguring, or sharing live sync with the WebUI. If all slots are full, stop an unneeded session with /bg drop <N>. This applies to the TUI; it does not add running-session switching to the WebUI.

Start a clean new session

/session

Spin up a fresh context without changing the working directory. Good for "the previous task is wrapped — onto something totally unrelated".

Background sessions (/background · /bg)

Need to juggle multiple tasks without losing the current conversation? /background (alias /bg; the two are equivalent) parks the current session in the background and opens a fresh foreground — switch back any time. Up to 16 concurrent background slots.

Session states

The state column in /bg list reflects what each background session is doing:

• running — the model loop is still executing; tool calls and output keep advancing in the background
• idle — the model turn finished; waiting for your next prompt
• done — the session was explicitly ended
• cancelled / error — interrupted, or the background run hit an error

So /bg isn't just "suspend" — the model actually keeps working in the background; when you switch back, the result is already there.

/background <task> — one-shot dispatch

If you don't want to swap foreground/background manually and just want to "have it look something up real quick", just pass a task (both names work) — /background <task> or /bg <task>:

/background list every unused dependency under src

It starts a one-shot task in a /bg slot (configured with a read-only tool subset by default so the main conversation context isn't polluted). When done, check /bg list, use /bg <N> to read the result, /bg drop <N> to discard.

Background lifetime and multiple processes

Background sessions depend on this AtomCode process. Exiting stops their runtimes; this is not process-independent execution. Saved conversations can be resumed, but their original tool processes are not guaranteed to keep running.

One installation is enough: run the same executable in multiple terminals with different sessions. Different sessions in the same project and home can run concurrently. An exclusive lease prevents two runtimes from writing the same session in the same storage bucket. Interactive resume may fork a session held by another process; check the notice. Config writes use a cross-process lock and atomic replacement, but settings remain shared.

Separate ATOMCODE_HOME values isolate configuration and session storage. Neither session leases nor separate homes protect project files. Use separate Git worktrees when agents edit concurrently to avoid conflicting file or Git operations.

Clear vs compact vs new session

Rewinding conversation memory with /undo

/undo rewinds conversation memory to before a given turn — removing that turn and everything after it — and drops the prompt you typed for that turn back into the input box so you can edit and resend it.

/undo      # rewind the last turn
/undo N    # rewind to turn N (1-based; counts only the prompts you actually typed)

The scrollback dividers for the removed turns are cleared too, and the session is saved immediately — so your next /resume reflects the rewound state.

Safe rollback with /rewind

/rewind lists recent user prompts and lets you choose the scope: conversation only, code only, or both conversation and code. Code rollback requires a Git worktree and is confirmed before it runs. For a simple one-turn conversation rollback, /undo remains the lighter option.

Recovery after an interrupted exit

AtomCode saves temporary progress while a turn is running. After a terminal crash or network interruption, /resume attempts to restore the last user prompt, generated response, and tool-call progress instead of falling back to the previous completed turn. Pending permissions and questions are never auto-approved.

Inspecting and managing token usage

/cost

Shows cumulative input / output tokens for the current session. When the number approaches the provider's context_window:

• Use /compact to compact history (early messages become a summary)
• Or just /session and start fresh
• To avoid keeping large tool-call results, tell the model in the prompt to "stop re-reading those big files"

Multi-project workflows

AtomCode groups sessions by working directory. Recommended ways to switch:

• From the CLI, specify with -C
• While running, use /cd; default_workdir is persisted automatically

Next steps

• Project Instructions — lock in per-project context with .atomcode.md