中文 |

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

• 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

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.

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

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"

After pip install, you can use the aacode command

# Install
pip install aacode

# Initialize configuration
aacode init

# Run
aacode run -p /your/project/path "your task"

If you prefer a graphical interface, try AACode Desktop:

The desktop client still requires Python and dependencies. See 👉 DESKTOP.md for full setup instructions.

# 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"

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)

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.

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

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

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

## 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"})

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

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

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

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

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

✅ 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"

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"

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

• 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
• Smart context management - 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

📁 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

• 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

• run_shell - Execute shell commands (safely)

• delegate_task - Delegate subtasks
• add_todo_item - Add todo item
• update_todo_item - Update todo item

• web_search - Search web content (currently supports searXNG; requires self-deployment and configuration of SEARCHXNG_URL environment variable)
• browse_web - Web browsing (future)

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

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

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

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]

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

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