_   _                  ____          _
     / \ | |_ ___  _ __ ___ / ___|___   __| | ___
    / _ \| __/ _ \| '_ ` _ \ |   / _ \ / _` |/ _ \
   / ___ \ || (_) | | | | | | |__| (_) | (_| |  __/
  /_/   \_\__\___/|_| |_| |_|\____\___/ \__,_|\___|

Open-source terminal AI coding agent written in Rust

English · 简体中文

Install · Quick Start · Features · Architecture · Development · Contributing · Community

This project is 100% AI-generated. Every line of code, every architectural decision's implementation, and every commit was written by AI. The human developer serves solely as the decision-maker and product manager — defining what to build, not how to build it.

AtomCode is an AI coding agent that lives in your terminal. Give it a task in natural language, and it will read your codebase, edit files, run commands, and verify its work — autonomously.

Think of it as an open-source alternative to Claude Code / Cursor Agent, but running entirely in your terminal and connecting to any OpenAI-compatible API.

• Autonomous multi-step execution — reads files, edits code, runs tests, fixes errors, all in a loop
• Verification loop — automatically verifies edits via syntax checks before declaring success
• Dynamic step budget — scales with the number of edited files, capped per turn to bound cost
• Loop detection — detects and breaks out of repetitive tool-call patterns
• 3-layer JSON repair — recovers malformed tool-call arguments
• Turn-level datalog — structured per-turn logs for replay, debugging, and eval harnesses

• Plan / Build modes — /plan switches to read-only exploration (the agent investigates without touching files); /build switches back to full execution
• Goal mode — /goal <text> sets a completion condition and the agent loops autonomously, turn after turn, until the goal is met
• Code review — /review reviews your current changes, /review staged the staged diff, and /review <base> against a base ref
• Background sessions — /bg runs work in detached slots so you can keep using the TUI while a long task progresses

File & shell:

• read_file, write_file, edit_file, search_replace
• bash, grep, glob, list_directory, change_dir
• web_search, web_fetch

Code graph (language-aware code intelligence):

• list_symbols, read_symbol, find_references
• trace_callers, trace_callees, trace_chain
• file_deps, blast_radius

Automation:

• auto_fix — automatic lint/typecheck fix loop
• use_skill — invoke a user-defined skill

Connect to any LLM that supports OpenAI's function-calling API:

• Persistent sessions — every conversation is saved; continue the last session with atomcode --continue / -c, or resume/switch inside the TUI with /resume
• AtomGit OAuth login — /login (or atomcode login) pairs your CLI with your AtomGit account
• SSO login — /login-with-sso for GitCode internal users
• Headless mode — atomcode -p "..." runs a single prompt non-interactively and streams the reply on stdout (Claude Code -p style); approval-required bash calls are auto-approved, while other approval-required tools are denied
• Daemon mode — atomcode-daemon exposes an HTTP API for session history and SSE streaming chat

• Real-time streaming with markdown rendering and syntax highlighting
• Code blocks with language labels, line numbers, and base16-ocean.dark theme
• Multi-line input with Shift+Enter (or \ + Enter), auto-growing height, input history
• Task completion notifications — long-running tasks trigger terminal-native notifications first (kitty / WezTerm / iTerm2), falling back to OS-native alerts
• Text selection with mouse drag, auto-scroll, and clipboard copy
• Slash commands — /model, /provider, /resume, /bg, /diff, /undo, /cost, /clear, /compact, etc. (see table below)
• File attachment — paste file paths to attach content as context
• Bracketed paste — long paste content collapsed to a compact indicator
• Skills — user-defined commands loaded from your skill directory, invoked like any slash command

• /webui (in the TUI) or atomcode webui (CLI) launches a local browser UI as an alternative to the terminal interface — same agent, same sessions, rendered in your browser
• Loopback only — the server binds to 127.0.0.1 and uses a one-time token; nothing is exposed to the network
• /webui stop stops the in-process server (a later /webui restarts it)

• /app (in the TUI) enables mobile remote access — prints a QR code; scan it with the GitCode mobile app from any network to connect to your current session
• Any-network reachable — your PC connects to a public relay via a reverse WSS tunnel; the phone reaches your PC through the relay. No public IP, DDNS, or port forwarding required
• Bidirectional real-time sync — messages from either end appear on the other in real time (streaming replies, tool call cards, token usage)
• Remote commands — the phone can run /status, /cost, /diff, /whoami etc., which execute on the desktop and echo results back
• Switch projects / sessions — switch projects or open a history session on the phone, and the desktop follows immediately
• Model sync — switching models on either end keeps the other in sync
• /app stop disconnects remote access

• Destructive command detection — rm -rf, git push --force, DROP TABLE, etc. require explicit approval
• Path-aware confirmations — external reads, sensitive paths, and all writes outside the workspace can require confirmation depending on risk level
• Sensitive file protection — protected system paths, credential directories, shell configs, .env files, and key/cert files receive stronger confirmation rules
• Shell bypass protection — common shell file commands like cat, head, ls, cp, mv, and tee inherit the same path approval model as file tools
• Per-session permission grants — approve once per tool pattern, or always-allow
• Source file deletion requires approval — rm on code files is never auto-approved
• Undo — /undo rolls back the last turn's file edits via file-history snapshots

See Permission Model for the full design and current boundaries.

• 📊 Anonymous telemetry (opt-out) — see docs/telemetry.md

git clone https://atomgit.com/atomgit_atomcode/atomcode.git
cd atomcode
cargo install --path crates/atomcode-cli --locked

The binary will be generated at target/release/atomcode and installed to ~/.cargo/bin/atomcode for macOS / Linux / HarmonyOS PC and $env:USERPROFILE/.cargo/bin/atomcode.exe for Windows. Make sure that ~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows) is in your PATH.

To compile without installing, run:

cargo build --release

and the binary will be generated at target/release/atomcode.

AtomCode CLI can also be installed via the following package managers:

# Install using npm
npm install -g @atomgit.com/atomcode

# Install using Homebrew
brew install --cask atomcode

• Rust 1.88+ (for building; older Cargo versions cannot parse the current lockfile)
• An API key from any supported provider (or an AtomGit account for /login)

Run AtomCode as your normal user, never with sudo. AtomCode keeps its config, sessions, and logs under ~/.atomcode; running once as root leaves root-owned files there, so every later non-root start fails at engine init with:

engine v2 assemble failed: Permission denied (os error 13)

(the message may say prepare instead of assemble — same cause.) If you hit this, reclaim ownership and stop using sudo:

sudo chown -R "$(id -un):$(id -gn)" ~/.atomcode
atomcode        # start WITHOUT sudo

On a Linux guest, a working directory on a VirtualBox shared folder (/media/sf_*, owned by root:vboxsf) can also trigger permission errors — add yourself to the group with sudo usermod -aG vboxsf "$USER" and re-login, rather than using sudo.

Remove AtomCode and (optionally) its data:

atomcode uninstall                # interactive: per-group prompts
atomcode uninstall --keep-data    # only remove binary + PATH edit
atomcode uninstall --purge        # remove everything, including ~/.atomcode
atomcode uninstall --dry-run      # show plan, change nothing

If the binary is already broken or missing:

curl -fsSL https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/uninstall.sh | sh
# Windows:
irm https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/uninstall.ps1 | iex

By default credentials (auth.toml, mcp.json, config.toml, ATOMCODE.md) are kept; pass --purge to remove them too.

atomcode

On first run, a setup wizard will guide you through configuring your LLM provider:

Welcome to AtomCode! Let's set up your first provider.

Select provider:
  [1] Claude (Anthropic)
  [2] OpenAI
  [3] OpenAI Compatible (DeepSeek, Qwen, Zhipu, Moonshot...)
  [4] Ollama (local)

Config is stored at ~/.atomcode/config.toml. A minimal single-provider setup looks like this:

default_provider = "deepseek"

[providers.deepseek]
type           = "openai"
api_key        = "sk-..."
model          = "deepseek-chat"
base_url       = "https://api.deepseek.com/v1"
context_window = 64000

You can declare multiple providers and switch between them with /model or /provider. A complete reference covering Claude / OpenAI / OpenAI-compatible endpoints (DeepSeek, GLM, SiliconFlow, OpenRouter...) / Ollama, plus the [datalog] section, lives at docs/config.example.toml — copy and edit the bits you need.

After editing config.toml by hand, run /reload inside atomcode to pick up the changes without restarting.

# Open in your project directory
cd your-project
atomcode

# Or specify directory
atomcode -C /path/to/project

# Or specify model
atomcode --model gpt-4o

# Headless (single prompt, reply on stdout)
atomcode -p "Explain the agent loop in this repo"

# Read prompt from file
atomcode --prompt-file task.md

In headless mode, approval-required bash calls are auto-approved and logged to stderr; other approval-required tools are denied.

Then just type what you want:

> Fix the login bug where users get redirected to 404 after OAuth callback

> Add a dark mode toggle to the settings page

> Refactor the database module to use connection pooling

> Write tests for the payment processing module

Terminal compatibility for newline chords:

• Shift+Enter, Ctrl+Enter, and Ctrl+J all need a terminal that speaks the Kitty keyboard protocol — kitty, WezTerm, Alacritty, iTerm2 ≥3.5, Windows Terminal ≥1.21. Older terminals collapse them to plain Enter (which sends the message).
• Alt+Enter works at the byte level on most terminals, but Windows Terminal binds it to "toggle full screen" by default — remove that binding under Settings → Actions to free it up.
• Xshell does not support the Kitty protocol; in its keymap settings, map a free chord to send ESC, Enter (\x1b\r) to get the same effect, or paste multi-line text via the clipboard (bracketed paste is enabled).

Pasting images on Windows: Windows Terminal and conhost bind Ctrl+V to their own paste action, which only forwards CF_UNICODETEXT from the clipboard — an image-only clipboard sends nothing, so the in-app Ctrl+V handler never fires. Two ways out:

1. Use /paste — the slash command pulls the clipboard image and attaches it as [Image #N]. Works in every terminal, including Windows Terminal, PowerShell 7, conhost, and git bash. The TUI's bottom-right hint on Windows says Image in clipboard · /paste automatically.
2. If you want Ctrl+V muscle memory: open Windows Terminal settings.json (Ctrl+, → "Open JSON file") and either delete the { "command": "paste", "keys": "ctrl+v" } entry under "actions", or rebind it to ctrl+shift+v. After a restart, Ctrl+V passes through to atomcode.

Git Bash (MinTTY) doesn't intercept Ctrl+V, so it works there out of the box.

Type / in the TUI to browse the full list with live completion; /help shows commands and shortcuts.

Sessions & workspace

Modes, autonomy & review

Providers & account

Files, edits & context

Memory

Extensions

Project & system

Plugin commands. Beyond the built-ins above, plugins can register their own slash commands. For example, install the official channel plugin to get /wechat (shows the AtomCode WeChat community group QR code):

/plugin marketplace add https://atomgit.com/atomgit_atomcode/AtomCode-Channel
/plugin install weixin@atomcode-channel

AtomCode is a Rust workspace with four crates:

atomcode/
  crates/
    atomcode-core/     # Headless library — no TUI dependency
      agent/           # AgentLoop: autonomous tool-use loop
      turn/            # TurnRunner, datalog, permission decider
      config/          # Config loading, provider configs
      conversation/    # Message types, windowed context
      provider/        # LlmProvider trait + OpenAI/Claude/Ollama
      tool/            # Tool trait + built-in tool implementations
      session/         # Persistent sessions
      skill.rs         # User-defined skills

    atomcode-tuix/     # Terminal UI — retained-mode renderer (CC-style normal mode)
      event_loop/      # App state machine, command dispatch
      render/          # Cell-based renderer, diff, retained-mode frame loop
      modals/          # Picker UIs (dir, model, session, provider, issue)

    atomcode-cli/      # Binary entry point (TUI + headless -p mode)
      main.rs          # CLI args, first-run wizard, launch
      auth/            # AtomGit OAuth client

    atomcode-daemon/   # HTTP/SSE API server over atomcode-core

1. Tech-stack agnostic — never hardcodes language-specific logic. Detects project type dynamically from descriptor files (package.json, Cargo.toml, pyproject.toml, pom.xml, etc.).

2. Decoupled agent — AgentLoop runs as an independent async task, communicating with the TUI via channels (AgentCommand / AgentEvent). The core library has zero TUI dependencies, which is also what makes the daemon possible.

3. Tool safety — all destructive operations require explicit user approval. Tool failures become LLM observations, never panics.

4. Context-aware — token-budget-aware conversation windowing, project file-tree injection, and per-turn system reminders keep the model focused without exceeding context limits.

Create a .atomcode.md file in your project root to give AtomCode persistent context:

# Project Instructions

This is a Vue 3 + TypeScript project using Pinia for state management.

- Always use Composition API with `<script setup>`
- Use TailwindCSS for styling, no inline styles
- Run `npm run lint` after editing .vue/.ts files

AtomCode reads this file automatically and includes it in the system prompt. AtomCode also supports AGENTS.md (the open standard for AI coding agents) as an alternative — if both files exist, .atomcode.md takes priority.

• Rust 1.88+ — install via rustup
• Git
• A supported LLM provider API key (for runtime testing)

git clone https://atomgit.com/atomgit_atomcode/atomcode.git
cd atomcode

# Debug build (fast compilation, slower runtime)
cargo build

# Release build (slower compilation, optimized binary)
cargo build --release

# Run the TUI directly (debug mode)
cargo run -p atomcode-cli

# With arguments
cargo run -p atomcode-cli -- -C /path/to/project
cargo run -p atomcode-cli -- --model gpt-4o

# Headless mode
cargo run -p atomcode-cli -- -p "summarize this repo"

# Daemon (HTTP API)
cargo run -p atomcode-daemon

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p atomcode-core
cargo test -p atomcode-tuix

# Run a specific test
cargo test -p atomcode-core test_name

# Check compilation without building
cargo check

# Format code
cargo fmt

# Run linter
cargo clippy

# Build and install to ~/.cargo/bin
cargo install --path crates/atomcode-cli

Contributions are welcome! AtomCode is in active development.

1. Fork the repository on AtomGit
2. Clone your fork locally:

   git clone https://atomgit.com/<your-username>/atomcode.git
   cd atomcode

3. Create a branch for your change:

   git checkout -b feat/your-feature
   # or
   git checkout -b fix/your-bugfix

4. Make your changes, ensure the project builds and tests pass:

   cargo build && cargo test && cargo clippy

5. Commit with a clear message:

   git commit -m "feat: add xxx support"

6. Push and open a Pull Request against main

• Follow the project's core principles — especially tech-stack neutrality (no language/framework-specific logic in the core engine; detect via probes like package.json / Cargo.toml / pom.xml and route through adapters)
• All tool failures must be graceful — return the error as an observation to the LLM, never panic
• Destructive operations must require user approval
• Keep the system prompt compact (~1.5K tokens)
• Run cargo fmt and cargo clippy before submitting

• Add a new tool — implement the Tool trait in crates/atomcode-core/src/tool/
• Add a new provider — implement LlmProvider in crates/atomcode-core/src/provider/
• Improve the UI — rendering lives in crates/atomcode-tuix/src/render/
• Fix bugs — check Issues for open bugs

Don't know Rust? No problem! There are many ways to contribute without writing Rust code:

• 📝 Documentation — Improve the README, fix typos, enhance the official docs site, or add examples. Docs live in the root docs/ directory, site/docs/, and the main README files.
• 🌐 Localization & Translation — Help translate the docs site, README, or UI strings into more languages. Check site/docs/ for existing translations.
• 🧩 Skills & Plugins — Create new skills (Markdown + JSON, no Rust needed) that extend AtomCode's capabilities. Skills are loaded from ~/.atomcode/skills/.
• 🐛 Bug Reports — Found a bug? Open an Issue with clear reproduction steps, screenshots, and environment info. High-quality bug reports are invaluable.
• 🧪 Test Cases & Examples — Add test scenarios, example projects, or usage demos that help validate features and onboard new users.
• 💬 Community Support — Help answer questions in the community group, write tutorials, or create video guides.

Every contribution, code or not, makes AtomCode better for everyone. When in doubt, open an Issue or start a Discussion!

Scan the QR code below with WeChat to join the AtomCode community group — share feedback, report issues, and talk to other users and maintainers:

☕ AtomCode is free, and the Coding Plan is free too. If it's saved you a bit of time, consider buying the author a coffee — it keeps us motivated to keep making it better.

MIT License. See LICENSE for details.

Built with Rust, ratatui, and a lot of late nights.