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

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

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
• 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

• 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.

• 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)

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://atomgit.com/atomgit_atomcode/atomcode/raw/main/uninstall.sh | sh
# Windows:
irm https://atomgit.com/atomgit_atomcode/atomcode/raw/main/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.

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.

• 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

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

MIT License. See LICENSE for details.

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