A comprehensive AI-powered coding assistant built on DeepAgents, featuring specialized subagents for code review, testing, documentation, debugging, and refactoring.
agent_demo.mp4
- Code Review: Analyzes code for quality, best practices, and potential issues
- Test Generation: Creates comprehensive unit tests with high coverage
- Documentation: Generates professional documentation including docstrings and READMEs
- Debugging: Identifies and resolves code errors with step-by-step guidance
- Refactoring: Suggests improvements for code structure, performance, and maintainability
- Human-in-the-Loop: Configurable approval workflow for file modifications and command execution
- Built on DeepAgents framework for agent orchestration
- Integrates with LangChain and LangGraph for advanced LLM capabilities
- Supports OpenAI and custom LLM models
- File system integration for working with codebases
- Terminal command execution with safety controls
- Extensible subagent architecture
- Human-in-the-loop approval system using LangChain HITL middleware
- uv: An extremely fast Python package and project manager, written in Rust.
-
Clone the repository:
git clone https://github.com/hzhaoy/deep-code-agent.git cd deep-code-agent -
Install dependencies:
uv sync
Create a .env file from the example template and configure your settings:
cp .env.example .envEdit .env with your configuration:
# OpenAI API Configuration
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
# LLM Model Configuration
MODEL_NAME=your-model-name-hereWARNING: This agent will directly modify files in the specified codebase directory. Please:
- Ensure you understand the changes it will make
- Back up your codebase before running the agent
- Consider running on a test/development branch first
- Review all changes thoroughly before merging to production
from deep_code_agent import create_code_agent
# Initialize the agent with your codebase directory
# By default, human-in-the-loop approvals are enabled for file and command operations
agent = create_code_agent("your-codebase-directory")
# Run the agent
state = {"messages": [{"role": "user", "content": "What are the main features of this project?"}]}
config={"configurable": {"thread_id": "1"}}
for step in agent.stream(state, config=config, stream_mode="values"):
step["messages"][-1].pretty_print()The agent supports configurable approval workflows for file modifications and command execution:
from deep_code_agent import create_code_agent, DEFAULT_INTERRUPT_ON
# Default - approvals enabled for all file and command operations
agent = create_code_agent("your-codebase-directory")
# Disable all approvals (run autonomously)
agent = create_code_agent("your-codebase-directory", interrupt_on=None)
# Custom - only approve file writes
agent = create_code_agent(
"your-codebase-directory",
interrupt_on={"write_file": True}
)
# Custom - approve file operations but auto-approve commands
agent = create_code_agent(
"your-codebase-directory",
interrupt_on={
"write_file": True,
"edit_file": True,
}
)Available approval options:
write_file- Approve file creation/overwritesedit_file- Approve file editsexecute- Approve shell commands (from FilesystemBackend)terminal- Approve terminal commands (custom tool)
# Run the agent (approvals enabled by default)
python -m deep_code_agent
# Show the installed CLI version
python -m deep_code_agent --versionWhen using the CLI, you'll be prompted for approval when the agent attempts to modify files or execute commands:
==================================================
⚠️ Action Requires Approval
==================================================
Tool: write_file
Arguments:
file_path: /path/to/file.py
content: def hello(): ...
Options:
(a)pprove - Execute as-is
(e)dit - Modify arguments before executing
(r)eject - Reject and provide feedback
(q)uit - Exit session
==================================================
Your choice:
Deep Code Agent can load DeepAgents-native skills from a local skills directory when using the filesystem backend. By default, it looks for project skills at:
<codebase_dir>/.agents/skills
Each skill is a directory with a SKILL.md file:
.agents/skills/
└── my-skill/
└── SKILL.md
SKILL.md must include YAML frontmatter with a skill name and description:
---
name: my-skill
description: Specialized workflow for a project task
---
# My Skill
Use these instructions when the task matches this workflow.To load explicit skill directories, pass --skills-dir. This option can be provided multiple times, and explicit directories replace the default auto-discovery path:
uv run deep-code-agent --backend-type filesystem --skills-dir .agents/skillsSkills currently require --backend-type filesystem; the state backend does not load local skill directories.
The Deep Code Agent includes specialized subagents that can be used independently or as part of the main workflow:
- code_reviewer: For code quality analysis
- test_writer: For generating unit tests
- documenter: For creating documentation
- debugger: For error resolution
- refactorer: For code improvements
-
Configure
.envwith required keys and model settings -
Update
server/agent.pyto setcodebase_dirto your target path -
Start the dev server:
cd server && uv run langgraph dev. If the server starts successfully, you will see output similar to the following:INFO:langgraph_api.cli: Welcome to ╦ ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬ ║ ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤ ╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴ ┴ ┴ - 🚀 API: http://127.0.0.1:2024 - 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 - 📚 API Docs: http://127.0.0.1:2024/docs This in-memory server is designed for development and testing. For production use, please use LangSmith Deployment. -
Visit the Agent Chat UI, input the Deployment URL with the API url show above (here is
http://127.0.0.1:2024) and Assistant / Graph ID (defined in langgraph.json, here isagent). Now you can start chatting with the agent for clicking continue.
deep-code-agent/
├── src/
│ └── deep_code_agent/
│ ├── __init__.py # Package initialization & CLI interrupt handling
│ ├── __main__.py # CLI entry point
│ ├── code_agent.py # Main agent implementation
│ ├── tools/
│ │ ├── __init__.py
│ │ └── terminal.py # Terminal command tool
│ └── models/
│ └── llms/
│ └── langchain_chat.py # LLM integration
├── tests/
│ ├── test_code_agent.py # Tests for code_agent module
│ └── test_interrupt_handling.py # Tests for interrupt handling
├── .env.example # Environment variables template
├── .gitignore # Git ignore rules
├── .python-version # Python version pin
├── LICENSE # License
├── README.md # Project documentation
├── pyproject.toml # Project configuration
└── uv.lock # Dependency lockfile
- Code Agent Core: The main orchestrator that manages the workflow
- Subagents: Specialized agents for specific tasks
- LLM Integration: Connects to language models via LangChain
- File System Backend: Interfaces with the codebase
- Terminal Tool: Executes commands safely
Each subagent has its own system prompt and tools, allowing for specialized behavior:
- Code Reviewer: Focuses on code quality and best practices
- Test Writer: Generates comprehensive test suites
- Documenter: Creates professional documentation
- Debugger: Identifies and fixes errors
- Refactorer: Improves code structure and performance
MIT License - see the LICENSE file for details.
- Built on DeepAgents framework
- Integrates with LangChain and LangGraph
- Inspired by modern AI coding assistants
For issues, questions, or feedback, please:
- Check the Issues page
- Create a new issue if needed
- Join our community discussions
Deep Code Agent - Empowering developers with AI-assisted coding excellence