mini-OpenCode

简体中文 | 繁體中文 | 日本語

mini-OpenCode is a lightweight, experimental AI Coding Agent inspired by Deer-Code and OpenCode. It demonstrates how Large Language Models (LLMs) can plan, reason, and iteratively write code with minimal infrastructure. Built on LangGraph, it serves as a hackable foundation for understanding and building agentic coding systems.

• 🤖 DeepAgents Powered: Built on create_deep_agent from the LangChain ecosystem, providing a robust foundation for agentic coding.
• 📝 Integrated Task Management: Built-in write_todos tool to manage and track complex, multi-step tasks effectively.
• 🛠️ Essential Toolset:
  • File Operations: Built-in tools for ls, read_file, write_file, edit_file, glob, and grep.
  • Shell Execution: Built-in execute tool for running shell commands safely.
  • Web Capabilities: Configurable web search and web crawling tools, with support for MCP (Model Context Protocol) extensions.
• 🧩 SubAgents Mechanism: Includes a default general-purpose SubAgent to handle auxiliary tasks.
• 🚀 Skills System: Automatically recognizes and utilizes user-defined Skills to enhance agent capabilities.
• 🧠 Intelligent Context Management:
  • AGENTS.md Injection: Automatically detects and injects AGENTS.md content into the context.
  • SummarizationMiddleware: Automatically summarizes conversation history when context limits are reached.
  • Large Output Handling: Automatically evicts large tool outputs to the file system to prevent context window saturation.
  • Robustness: Includes PatchToolCallsMiddleware to handle dangling tool calls gracefully.
• 🎨 Beautiful TUI: A polished Terminal User Interface based on Textual, featuring dark/light mode switching and streaming output.
• ⚡️ Slash Commands: Support for slash commands (e.g., /clear, /exit) for quick actions.
• ⚙️ Highly Configurable: Fully customizable models, tools, and behaviors via YAML configuration.

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Project Structure
• Contributing
• Acknowledgments
• Star History
• License

• Python 3.12 or higher
• uv package manager (highly recommended for dependency management)
• API Keys for LLM (DeepSeek, Doubao) and optional web tools (Tavily, Firecrawl)

1. Clone the repository

   git clone https://github.com/your-username/mini-opencode.git
   cd mini-opencode

2. Install dependencies

   uv sync
   # Or using make
   make install

1. Environment Variables Copy the example environment file and fill in your API keys:

   cp .example.env .env

   Edit .env:

   DEEPSEEK_API_KEY=your_key_here
   # Optional:
   KIMI_API_KEY=your_kimi_key
   TAVILY_API_KEY=your_tavily_key
   FIRECRAWL_API_KEY=your_firecrawl_key

2. Application Config Copy the example configuration file:

   cp config.example.yaml config.yaml

   Edit config.yaml to customize enabled tools, model parameters, and MCP servers.

3. LangGraph Config (Optional) If you plan to use LangGraph Studio to debug the agent, copy the example LangGraph configuration file:

   cp langgraph.example.json langgraph.json

Run the agent directly on a project directory:

uv run -m mini_opencode /absolute/path/to/target/project
# Or using python
python -m mini_opencode /absolute/path/to/target/project

Start the LangGraph development server to visualize and interact with the agent:

make dev

Then open https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 in your browser.

mini-opencode/
├── src/mini_opencode/
│   ├── agents/           # Agent creation logic (based on deepagents)
│   ├── cli/              # Terminal UI (Textual) components
│   ├── config/           # Configuration loading & validation
│   ├── models/           # LLM model factory & setup
│   ├── prompts/          # Prompt templates (Jinja2)
│   ├── tools/            # Additional tool implementations
│   │   ├── date/         # Date tool
│   │   ├── mcp/          # MCP tools integration
│   │   └── web/          # Web Search & Crawl
│   ├── main.py           # CLI entry point
│   └── project.py        # Project context manager
├── skills/               # Agent Skills (instructions, scripts, and references)
├── config.example.yaml   # Template configuration
├── langgraph.example.json# Template LangGraph config
├── Makefile              # Build & run commands
└── pyproject.toml        # Project dependencies & metadata

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (follow Semantic Commits, e.g., git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed development guidelines.

Special thanks to the developers of the following projects for their inspiration and architectural references:

• Deer-Code
• OpenCode

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ using LangGraph and Textual.