仓库 →

Basic Usage

Get fluent with CLI flags, how to phrase tasks, how to give the model context, and how to move between several tasks.

Launching

# Launch the TUI in the current directory
atomcode

# Specify a working directory
atomcode -C /path/to/project

# Override provider / model for this run only
atomcode --provider claude --model claude-sonnet-4-6

# Continue the previous session
atomcode -c
atomcode --continue

# Use a specific config file
atomcode --config ./custom.toml

# Skip all permission prompts, auto-approve every tool call
atomcode -y
atomcode --dangerously-skip-permissions

CLI flag reference

FlagShortPurpose
--dir PATH-CWorking directory; defaults to the current directory
--continue-cContinue the previous session instead of starting a new one
--provider NAME—Override the default provider
--model NAME—Override the current provider's model
--config PATH—Use the given config file
--prompt TEXT-pNon-interactive mode: one-shot execution, reply to stdout
--prompt-file PATH—Read prompt from file (useful for long input; mutually exclusive with -p)
--verbose-vIn non-interactive mode, print tool calls and token usage to stderr
--max-turns N—Cap the number of agent loop iterations; prevents runaway loops
--disable-tools LIST—Comma-separated tools to disable, e.g. --disable-tools bash,web_fetch
--dangerously-skip-permissions-ySkip all permission prompts — auto-approve every tool call (bash, file edits, MCP, etc.). A ⚠ BYPASS badge is shown in the TUI status bar while active
Tip

--disable-tools makes disabled tools completely invisible to the model (they don't appear in the schemas), so the model won't keep trying to call them. Useful for sandbox evals, offline environments, and CI without network.

Warning

-y / --dangerously-skip-permissions bypasses all permission prompts, including bash execution, file writes, and MCP tool calls. The agent can execute arbitrary actions without confirmation. Only use this flag when:

  • Running in CI/CD pipelines or other automated environments
  • Executing benchmarks inside a sandbox or container
  • Working on non-critical projects where you trust the agent's built-in safety constraints

How to phrase tasks

AtomCode's agent loop is only as good as the task description you provide. A few rules of thumb:

Example tasks

# Bug fix
> Fix the bug where users are redirected to 404 after OAuth callback; restore the original path after callback.

# New feature
> Add a dark mode toggle to the settings page using Tailwind's dark: prefix, persisted in localStorage.

# Refactor
> Refactor src/db/*.ts to use a connection pool while keeping the public API unchanged; run npm test after.

# Tests
> Write unit tests for src/payment/processor.ts, covering all exception branches.

# Code understanding
> Briefly explain this repo's directory layout, build entry point, and the responsibilities of the core modules.

Multiline input

In the TUI:

@ file references

Type @ in the input (preceded by whitespace or line start) to pop up a menu of files and directories in the project. This is the fastest way to point the model at a specific path — you handle locating, the model decides via read_file what to expand and how much to read.

Interaction

Where candidates come from

What it means for the model

On submit, @crates/atomcode-cli/src/main.rs is sent to the model as literal text — AtomCode does not read and inline the file content in the frontend. The model sees the path and decides to call the built-in read_file tool as needed. Benefits:

Tip

If you want to force a file's contents into the conversation directly (e.g. a tight code review where you don't want another read_file round trip), use paste — drop the content into the input. Bracketed paste collapses it to an [paste #N] placeholder and ships the full payload on submit.

Limits

Pasting long text

AtomCode supports bracketed paste. When you paste a chunky block (e.g. a wall of logs), the TUI collapses it to a compact [paste #N · 132 lines] indicator so the input doesn't blow up. The full payload is sent on submit.

Image attachments / screenshots

Beyond text, you can also drop images into the conversation — error screenshots, UI mocks, whiteboard photos. AtomCode offers three entry points:

On a successful attach, an [Image #N] marker is inserted in the input; the bytes ride along with the message on submit. The status bar also shows Image in clipboard · ctrl+v to paste when an unpasted image is sitting in the clipboard.

How non-vision models handle images

When the active provider can't take image input (text-only models like DeepSeek-V3 / Kimi), AtomCode doesn't refuse — it routes the image to a separate VL preprocessor (a vision model like Qwen3-VL / GLM-4V) for OCR + description, then splices the result into the user message as text before sending to the main model. So you can "drop a screenshot and ask" regardless of the main model.

Tip

If the current model supports vision (Claude 3+ / GPT-4o / Gemini / Qwen-VL, etc.), the raw image bytes are sent directly — the preprocessor is skipped.

Switching sessions and directories

Full behaviour at Sessions & Undo.

Inspecting cost and diff

Next steps