aacode

中文 |

🤖 AACode - CLI Programming Agent

🚀 AI Programming CLI Agent based on DeepSeek - A lightweight ReAct architecture that borrows and adopts advanced concepts from current popular Agents, 100% python.

Design Principles

• Less scaffolding, more trust in models: simple core logic, relying on model capabilities
• File-based context: dynamic discovery, Markdown files as primary storage
• Bash universal adapter: flexible system access through safety guardrails
• Context management: smart reduction strategies borrowed from Cursor and Manus
• Asynchronous design: all blocking operations are asynchronous
• Layered tool system: atomic tools, management tools, Skills three-layer architecture
• Safety guardrails: comprehensive command and path security checks
• Extensible architecture: support for custom tools and model backends

🎯 Quick Start

Operating System

This project is primarily developed and tested on Linux and MacOS. It is recommended to use Linux or MacOS. Windows users may encounter Python path issues; please configure accordingly.

One-Click Initialization

git clone https://github.com/kandada/aacode.git
cd aacode
python3 init.py  # Python 3.12 or higher is recommended
# Check if the .venv environment is activated; if not, run:
source .venv/bin/activate

Getting Started

Note: Before starting a task, you can create an init.md file in your task directory as a detailed task description file. The more detailed your design ideas, the better results you can get.

# Using the convenient startup script
./run.sh -p examples/my_project "Your task description"

# Or run manually
source .venv/bin/activate
export LLM_API_KEY="your-api-key"
export LLM_API_URL="your-api-url"
export LLM_MODEL_NAME="your-model-name"
python3 main.py -p examples/my_project "Your task description"

# Advanced Mode
## Plan-First Mode
python main.py -p examples/my_project "Complex task" --plan-first
## Interactive Continuous Conversation
python main.py -p examples/my_project "Initial task" --interactive
## Specify Session
python main.py --session session_20250128_123456_0 "Continue task"

Or pip Installation (Recommended)

After pip install, you can use the aacode command. The default workspace is the current directory — no need to specify -p unless you want a different location. It's recommended to wrap your task in quotes.

# Install
pip install aacode

# Initialize configuration
aacode init

# Enter interactive session mode (no task required)
aacode

# Run a single task in current directory
aacode "your task"

# Or explicitly with aacode run (same as above)
aacode run "your task"

# Specify a different project directory
aacode run -p /your/project/path "your task"

🖥️ Desktop Client

If you prefer a graphical interface, try AACode Desktop:

The desktop client still requires Python and dependencies (not required for the mobile app). See 👉 DESKTOP.md for full setup instructions.

📱 Mobile App

Android users outside mainland China can also install via Google Play.

🔧 Configuration

Large Language Model (supports deepseek, openai, etc., no pre-configuration required; users need to configure independently)

# OpenAI
export LLM_API_KEY="your-openai-key"
export LLM_API_URL="https://api.openai.com/v1"
export LLM_MODEL_NAME="gpt-4"
export LLM_GATEWAY="openai"
export LLM_MULTIMODAL="false"

# Other OpenAI API compatible models (deepseek, etc.)
export LLM_API_KEY="your-api-key"
export LLM_API_URL="https://your-api-endpoint/v1"
export LLM_MODEL_NAME="your-model-name"
export LLM_GATEWAY="openai"
export LLM_MULTIMODAL="false"

# Multimodal models (e.g., MiniMax, Kimi, etc.)
export LLM_API_KEY="your-kimi-key"
export LLM_API_URL="https://api.moonshot.cn/v1"
export LLM_MODEL_NAME="kimi-k2.5"
export LLM_GATEWAY="anthropic"
export LLM_MULTIMODAL="true"

Multimodal Models

Supports various multimodal models (e.g., Kimi K2.5, MiniMax M2.5, etc.). Configure in .env file or aacode_config.yaml:

• MULTIMODAL_API_KEY: Multimodal model API key
• MULTIMODAL_API_URL: Multimodal model API address (optional, defaults to model-specific address)

Search Engine

Currently only supports SearXNG. Users need to deploy their own and configure the URL in aacode_config.yaml, but it is recommended to configure via environment variable SEARCHXNG_URL.

MCP

• Users can configure MCP resources (supporting stdio and sse) in aacode_config.yaml

Adding/Removing Skills

Skills are placed under aacode/skills/ directory. No configuration file changes needed — auto-discovered on restart.

Directory Structure

aacode/skills/<skill_name>/
├── SKILL.md    # Skill description (fastclaw template format)
└── main.py     # Implementation (public functions auto-registered as tools, excluding _ prefix and main)

SKILL.md Format

## Description
Skill description. Required imports auto-injected.

## Parameters
- param1: Parameter 1 description
- param2: Parameter 2 description

## Example
run_skills("skill_name", {"param1": "value1", "param2": "value2"})

Examples

See skills/pandas/, skills/numpy/, skills/playwright/.

📋 Usage Examples

Example 1: Create Hello World

./run.sh -p examples/hello_demo "Create a hello.py file with content print('Hello, World!')"

Example 2: Develop Calculator

./run.sh -p examples/calculator "Create a calculator program supporting addition, subtraction, multiplication, and division with test cases"

Example 3: Web Application Development

./run.sh -p examples/web_app "Create a simple Flask web application with home and about pages"

Example 4: Data Processing

./run.sh -p examples/data_analysis "Create a data analysis script that reads CSV files in the project directory and generates statistical charts"

🎯 Best Practices

1. Clear Task Descriptions

✅ Good description:

"Create a Python program that uses the requests library to fetch weather API data
and saves the results to a weather.json file"

❌ Poor description:

"Make a weather program"

2. Execute Complex Tasks in Steps

For complex projects, execute in multiple steps:

# Step 1: Create basic structure
python3 main.py -p examples/app "Create Flask application basic structure"

# Step 2: Add features
python3 main.py -p examples/app "Add user authentication features"

# Step 3: Test
python3 main.py -p examples/app "Write tests for all features"

3. Use Project Guidelines

Edit the init.md file and add project-specific rules:

# Project Guidelines

## Code Style
- Use PEP 8 standards
- Function names use snake_case
- Class names use PascalCase

## Testing Requirements
- Every feature must have unit tests
- Test coverage must be at least 80%

## Documentation Requirements
- All public functions must have docstrings
- README.md must include usage examples

🏗️ Architecture Design

📁 Core Architecture
├── 🤖 MainAgent          # Main controller, task decomposition and coordination
├── 🔄 ReActLoop          # Intelligent thinking-action loop
├── 📚 ContextManager     # File-based context management
├── 🛠️ AtomicTools       # Atomic toolset (files, commands, search)
├── 💻 CodeTools          # Code toolset (execute, test, debug)
├── 🛡️ SafetyGuard       # Comprehensive safety guardrail system
└── 🔧 ConfigManager      # Flexible configuration management

📊 Performance Metrics

🔒 Security Features

• Path security checks - Restrict file access within project directory
• Command security verification - Block dangerous system command execution
• Code security scanning - Python code AST security checks
• Sandbox isolation - All operations performed in secure sandbox environment
• User confirmation mechanism - Dangerous operations require user confirmation

🎯 Core Capabilities

• Shell Execution — Safely execute any shell command as the universal adapter
• File Operations — Read, write, and modify files in the project workspace
• Web Search & Fetch — Search the web (SearXNG, Brave, Google, Bing, SerpAPI) and fetch URL content
• Task Management — Todo lists with add/mark/update/summary, historical tracking
• Session Management — Create, switch, continue, list, and delete conversation sessions
• Sub-Agent Delegation — Delegate tasks to specialized sub-agents (code, test, research)
• Multimodal Understanding — Analyze images, videos, and UI design drafts
• MCP Protocol — Connect to external MCP servers for extended tool capabilities
• Extensible Skills — Built-in skills for pandas, numpy, playwright; add custom skills via aacode/skills/

📈 Project Status

• ✅ Core Features Complete - All main features implemented and tested
• ✅ Production Ready - Validated through complex tasks, usable for actual development
• ✅ Documentation Complete - Detailed usage guides and API documentation
• ✅ Secure and Reliable - Comprehensive security testing and validation
• 🔄 Continuous Optimization - Constant improvements and new features

🤝 Contributing

Contributions of code, bug reports, or suggestions are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Join WeChat Group

Scan the QR code below to join our WeChat group and discuss with other developers:

📄 License

Copyright (c) 2024-2026 xiefujin 490021684@qq.com. All rights reserved.

This project is initiated and developed by xiefujin (github: kandada, email: 490021684@qq.com) as the first version, licensed under GPL3.0. All derivative works must also be open source under GPL. [license][https://github.com/kandada/aacode/blob/main/LICENSE]

🙏 Acknowledgments

• Thanks to DeepSeek for providing powerful AI model support
• Borrowed some advanced concepts from [Cursor] and [Manus]
• Thanks to all open-source community contributors

📞 Contact

• Official Website: https://aacode-ai.com
• Project Home: xiefujin
• Issue Reporting: Issues
• Feature Suggestions: Discussions

---