English | 简体中文

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

AutoCode

A cross-platform, extensible terminal AI coding agent with tool support

AutoCode provides streaming multi-turn conversations, project-aware context, tool calling, MCP, Skills, context compaction, and controlled sub-agents directly in your terminal. It is a TUI/CLI application with no PyQt, Tkinter, or browser interface.

Important

AutoCode does not bundle, migrate, or read the developer's API key. After the first launch, you must configure your own model provider manually with /model.

Features

• OpenAI Chat Completions and Anthropic Messages compatible protocols
• Think, ReAct, and Plan-then-Execute execution modes
• Streaming model text, token usage, tool status, and agent status
• Persistent multi-turn sessions, session recovery, and context compaction
• Workspace-scoped file, search, patch, and command tools
• Filesystem, Git, GitHub, Fetch, Playwright, and Memory MCP presets
• Project Skills and controlled parallel sub-agents
• Ctrl+C cancellation that keeps the TUI running
• Source execution and PyInstaller packaging on Windows, Linux, and macOS

Requirements

• Git
• Conda through Miniconda, Anaconda, or Miniforge
• Windows 10/11, a mainstream Linux distribution, or macOS
• An OpenAI- or Anthropic-compatible model API

The project uses a Conda environment named codeagent.

Installation

git clone https://github.com/SipengShen01/AutoCode.git
cd AutoCode
conda env create -f environment.yml
conda activate codeagent

If the codeagent environment already exists:

conda activate codeagent
python -m pip install -e ".[dev]"

Verify the installation:

codeagent --help

Quick Start

1. Start AutoCode

Run AutoCode from the project you want the agent to work on:

codeagent

You can also select the workspace explicitly:

codeagent --project "/path/to/project"

Windows PowerShell example:

codeagent --project "F:\work\demo"

2. Configure a Model Manually

Enter the following command in the TUI:

/model

The setup wizard asks for:

1. Protocol: openai or anthropic
2. Base URL
3. API key, hidden in an interactive terminal
4. Primary model
5. Optional small model

Press Enter to keep the current value. Enter - to clear the API key or small model. AutoCode validates and saves the configuration atomically without writing secrets to the project or session files.

OpenAI-compatible example:

Protocol: openai
Base URL: https://api.openai.com/v1
Primary model: gpt-4.1-mini

Anthropic example:

Protocol: anthropic
Base URL: https://api.anthropic.com
Primary model: claude-sonnet-4-5

3. Run a Task

You > Read this project and fix the failing tests

Follow-up questions in the same session automatically reuse the conversation history. Model deltas append to one AI > line, and each turn ends with a single token-usage line.

TUI Commands

Command	Description
/help	Show available commands
/model	Configure the model protocol, Base URL, API key, and models
/project [path]	Switch the agent workspace
/new	Create a new session
/sessions	List sessions in the current project
/resume <session-id>	Restore a previous session
/mode think|react|plan	Change the execution mode
/compact	Compact the current context
/status	Show project, session, mode, model, and MCP status
/clear	Clear the terminal without deleting the session
/skill <name> ...	Load a project Skill
/exit, /quit	Exit normally

/project accepts absolute paths, relative paths, spaces, and non-ASCII characters. Relative paths are resolved from the current workspace. If the candidate project cannot be loaded, AutoCode keeps the current Runtime.

Ctrl+C and Exiting

• At the input prompt, Ctrl+C clears the current input.
• During model generation, tool execution, MCP calls, or compaction, Ctrl+C cancels the current task and returns to the prompt.
• During interactive commands such as /model, Ctrl+C aborts the current operation and returns to the prompt.
• Ctrl+C does not exit AutoCode. Use /exit or /quit for a normal shutdown.

Task cancellation combines cooperative cancellation with async Task cancellation, so AutoCode does not need to wait for the model or tool to emit another event.

Configuration and Local Data

The community release uses an isolated configuration namespace and does not read legacy development configuration:

Platform	Default global configuration
Windows	%APPDATA%\AutoCode\community-v1\settings.json
macOS	~/Library/Application Support/AutoCode/community-v1/settings.json
Linux	${XDG_CONFIG_HOME:-~/.config}/autocode/community-v1/settings.json

Use AUTOCODE_CONFIG_HOME to select a custom global configuration directory:

$env:AUTOCODE_CONFIG_HOME = "D:\private\autocode-config"
codeagent

AUTOCODE_CONFIG_HOME="$HOME/.config/autocode-work" codeagent

Project-local data is stored under:

<project>/
├── autocode.md              # User-owned project instructions; empty by default
└── .autocode/
    ├── config.json          # Non-sensitive project settings
    ├── sessions/            # Session JSONL files
    ├── skills/              # Project Skills
    └── tool-results/        # Large tool results

Do not commit .autocode/, autocode.md, .env, or any credential files. The repository .gitignore excludes these paths by default.

Non-Interactive CLI

Scripts and CI jobs can submit one task through standard input and consume JSONL events:

printf "Check the project tests\n" | codeagent run --project "/path/to/project" --mode react

PowerShell:

"Check the project tests" | codeagent run --project "F:\work\demo" --mode react

codeagent run also supports --session and --cancel-file. The task is read from standard input instead of appearing in the process command line.

Development

conda activate codeagent
python -m pip install -e ".[dev]"
ruff check .
mypy src
python -m pytest --cov=autocode --cov-report=term-missing

You can run the same checks without activating the environment:

conda run -n codeagent ruff check .
conda run -n codeagent mypy src
conda run -n codeagent python -m pytest --cov=autocode --cov-report=term-missing

Packaging

Run PyInstaller from the repository root:

conda activate codeagent
python -m PyInstaller --clean --noconfirm packaging/autocode.spec

Or:

conda run -n codeagent python -m PyInstaller --clean --noconfirm packaging/autocode.spec

Output:

dist/CodeAgent.exe    # Windows
dist/CodeAgent        # Linux/macOS

The package contains the Python runtime, AutoCode source, and required dependencies. It does not contain user configuration, API keys, project state, internal specs, or validation reports.

Project Structure

.
├── .github/workflows/   # CI and release workflows
├── packaging/           # PyInstaller configuration
├── src/autocode/
│   ├── agent/           # Agent loop and sub-agents
│   ├── api/             # OpenAI and Anthropic protocol adapters
│   ├── cli/             # JSONL automation entry point
│   ├── context/         # Context budgeting and compaction
│   ├── memory/          # Sessions and project memory
│   ├── tools/           # Built-in tools and MCP
│   └── tui/             # Interactive terminal
├── tests/               # Unit, integration, and end-to-end tests
├── environment.yml      # Conda environment
└── pyproject.toml       # Package, tooling, and entry-point configuration

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing.

Do not open a public issue for a security vulnerability. See SECURITY.md for the private reporting process.

License

AutoCode is available under the MIT License.