██████╗ ███████╗███╗ ██╗████████╗ ██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝ ██║ ███╗█████╗ ██╔██╗ ██║ ██║ ██║ ██║██╔══╝ ██║╚██╗██║ ██║ ╚██████╔╝███████╗██║ ╚████║ ██║ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝**Autonomous AI Coding Assistant - Never Gives Up** [](https://www.python.org/downloads/) [](https://opensource.org/licenses/Apache-2.0) [](https://openrouter.ai) [](https://modelcontextprotocol.io/) [](http://makeapullrequest.com) **An AI agent that explores codebases, implements features, fixes bugs, and refactors code autonomously through natural language commands. Now with Model Context Protocol (MCP) for enhanced capabilities.** [Features](#-features) • [Quick Start](#-quick-start) • [MCP Integration](#-mcp-integration) • [Usage](#-usage) • [Examples](#-examples)
Unlike traditional coding assistants that just suggest code, CodeAgent is truly autonomous:
Implement → Test → Error? → Fix → Test → Success ✓
# Clone the repository
git clone https://github.com/mikeoller82/Gent.git
cd Gent
# Install with uv (recommended)
uv pip install -e .
# Or with pip
pip install -e .
# Install MCP dependencies
pip install mcp httpx
Create a .env file:
# Required
OPENROUTER_API_KEY=your-api-key-here
# Optional: Enable MCP servers (defaults to context7)
MCP_ENABLED_SERVERS=context7,playwright,markitdown
# Optional: Disable MCP entirely
# DISABLE_MCP=true
# Interactive mode
codeagent
# Single command
codeagent "list all Python files in this directory"
# Use MCP features
codeagent "How do I use Next.js 15 server actions? Use the latest docs."
CodeAgent integrates with the Model Context Protocol to provide enhanced capabilities beyond its core functionality.
| Server | Purpose | Status | Setup |
|---|---|---|---|
| context7 | Up-to-date library documentation | ✅ Default | No setup needed |
| playwright | Browser automation & testing | ⚙️ Optional | Installs on first use |
| markitdown | Convert documents to Markdown | ⚙️ Optional | Installs on first use |
| filesystem | Enhanced file operations | ⚙️ Optional | Installs on first use |
| github | GitHub API integration | ⚙️ Optional | Requires API token |
| brave-search | Web search | ⚙️ Optional | Requires API key |
Enable specific servers:
# In .env file
MCP_ENABLED_SERVERS=context7,playwright,markitdown
Disable MCP:
# In .env file
DISABLE_MCP=true
Get current documentation:
You: How do I use React 19 hooks? Use the latest documentation.
→ mcp_context7_resolve_library_id
→ mcp_context7_get_library_docs
✓ Returns current React 19 docs
Automate browser testing:
You: Test the login form on staging.myapp.com
→ mcp_playwright_navigate
→ mcp_playwright_fill
→ mcp_playwright_click
→ mcp_playwright_screenshot
✓ Automated test complete
Convert documents:
You: Convert this PDF to markdown: report.pdf
→ mcp_markitdown_convert_to_markdown
✓ PDF converted to Markdown
$ codeagent
╔══════════════════════════════════════════════════╗
║ AI-Powered Coding Agent ║
║ Working Directory: /home/user/myproject ║
╚══════════════════════════════════════════════════╝
🔌 MCP Servers: context7, playwright
You: fix the authentication bug
→ get_files_info
→ get_file_content
→ get_file_content
📝 Modifying auth.py
✓ Successfully wrote to "auth.py"
→ run_python_file
✓ Task Complete
You: exit
# Simple task
codeagent "add logging to all functions"
# Complex task with MCP
codeagent "refactor to use the latest Next.js 15 patterns"
# With verbose output
codeagent "implement rate limiting" --verbose
exit or quit - Exit the programclear - Clear the screen--verbose prefix - Enable detailed output for that request$ codeagent "Build a Next.js 15 app with server actions using latest best practices"
Starting task: Build a Next.js 15 app with server actions
→ mcp_context7_resolve_library_id
→ mcp_context7_get_library_docs
📄 Creating app/page.tsx
📄 Creating app/actions.ts
📄 Creating app/layout.tsx
✓ Task Complete
Built Next.js 15 app using current server actions patterns:
- App router with React Server Components
- Server actions for data mutations
- TypeScript with proper typing
- Latest Next.js 15 features
Modified files:
• app/page.tsx
• app/actions.ts
• app/layout.tsx
$ codeagent "find and fix the memory leak in the cache manager"
Starting task: find and fix the memory leak in the cache manager
→ get_files_info
→ get_file_content
→ get_file_content
→ get_file_content
📝 Modifying cache_manager.py
Changes:
--- cache_manager.py (before)
+++ cache_manager.py (after)
@@ -23,6 +23,7 @@
def set(self, key, value):
self.cache[key] = value
+ self._cleanup_old_entries()
✓ Successfully wrote to "cache_manager.py"
→ run_python_file
✓ Task Complete
$ codeagent "Test the signup flow on staging.example.com"
Starting task: Test the signup flow
→ mcp_playwright_navigate
→ mcp_playwright_fill
→ mcp_playwright_click
→ mcp_playwright_wait_for
→ mcp_playwright_screenshot
✓ Task Complete
Signup flow tested successfully:
- Navigated to staging.example.com/signup
- Filled email and password fields
- Clicked submit button
- Verified redirect to dashboard
- Screenshot saved: signup-test.png
All assertions passed ✓
$ codeagent "Convert the project requirements PDF to markdown"
Starting task: Convert requirements PDF
→ get_files_info
→ mcp_markitdown_convert_to_markdown
📄 Creating requirements.md
✓ Task Complete
Converted requirements.pdf to Markdown:
- Preserved document structure
- Extracted all sections
- Formatted tables correctly
- Maintained heading hierarchy
Output: requirements.md
┌─────────────────────────────────────────────────────┐
│ User Input: "Use latest React patterns" │
└────────────────────┬────────────────────────────────┘
│
▼
┌──────────────────────┐
│ 1. EXPLORE │
│ get_files_info() │
│ get_file_content() │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 2. RESEARCH (NEW) │
│ MCP: context7 │
│ Get current docs │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 3. ANALYZE │
│ Understand code │
│ Identify updates │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 4. IMPLEMENT │
│ write_file() │
│ Show diffs │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 5. VERIFY │
│ run_python_file() │
│ MCP: playwright │
└──────────┬───────────┘
│
Error?
┌─┴─┐
Yes No
│ │
┌────────┘ └─────────┐
│ │
▼ ▼
┌──────────────┐ ┌───────────────┐
│ 6. FIX │ │ 7. REPORT │
│ Analyze │ │ Success! │
│ Fix issue │ └───────────────┘
└──────┬───────┘
│
└──────────┐
│
▼
Back to step 5
| Function | Purpose | Type |
|---|---|---|
get_files_info(directory) |
List directory contents | Native |
get_file_content(file_path) |
Read file contents | Native |
write_file(file_path, content) |
Create/modify files | Native |
run_python_file(file_path, args) |
Execute Python scripts | Native |
mcp_context7_get_library_docs |
Get current documentation | MCP |
mcp_playwright_navigate |
Navigate browser | MCP |
mcp_markitdown_convert |
Convert documents | MCP |
| Feature | CodeAgent | GitHub Copilot | ChatGPT | Cursor |
|---|---|---|---|---|
| Autonomous exploration | ✅ | ❌ | ❌ | ⚠️ |
| Self-verification | ✅ | ❌ | ❌ | ❌ |
| Persistent until complete | ✅ | ❌ | ❌ | ❌ |
| Live diff display | ✅ | ❌ | ❌ | ✅ |
| CLI interface | ✅ | ❌ | ❌ | ❌ |
| Multi-file changes | ✅ | ⚠️ | ❌ | ✅ |
| Error correction loop | ✅ | ❌ | ❌ | ⚠️ |
| Current documentation (MCP) | ✅ | ❌ | ❌ | ⚠️ |
| Browser automation (MCP) | ✅ | ❌ | ❌ | ❌ |
| Document processing (MCP) | ✅ | ❌ | ❌ | ❌ |
Edit .env to enable/disable servers:
# Enable multiple servers
MCP_ENABLED_SERVERS=context7,playwright,markitdown,filesystem
# Context7 only (default)
MCP_ENABLED_SERVERS=context7
# Disable MCP completely
DISABLE_MCP=true
Edit codeagent/main.py to customize the agent’s behavior:
system_prompt = """
Your custom instructions here...
"""
Adjust safety limits in process_request():
max_iterations = 100 # Default: 100
✅ Operates only within the current working directory
✅ Shows all changes with diffs before applying
✅ Tracks all file modifications
✅ Provides detailed summaries
✅ Uses MCP servers safely (sandboxed)
✅ Review changes before committing
✅ Test in a separate branch first
✅ Use version control (git)
✅ Keep backups of important files
✅ Start with --verbose mode to understand behavior
✅ Review MCP server configurations before enabling
❌ Access files outside working directory
❌ Make unauthorized network requests
❌ Execute arbitrary system commands
❌ Modify system files
❌ Share data without permission
Contributions welcome! Here’s how:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-feature# Clone your fork
git clone https://github.com/mikeoller82/Gent.git
cd Gent
# Install in development mode
uv pip install -e ".[dev]"
# Install MCP dependencies
pip install mcp httpx
# Run tests
pytest
Issue: Agent keeps reading the same files
Solution: This is normal during exploration phase. Agent will eventually move to implementation.
Issue: Agent stops before completing
Solution: Check the error message. Often needs more context or has hit an edge case. Try rephrasing your request.
Issue: API errors
Solution: Verify your OPENROUTER_API_KEY is set correctly and has quota remaining.
Issue: “MCP SDK not installed”
Solution: Run pip install mcp httpx
Issue: MCP servers not connecting
Solution: Ensure Node.js 18+ is installed. First run downloads dependencies automatically.
Issue: “Unknown server” error
Solution: Check server name spelling in MCP_ENABLED_SERVERS. Available: context7, playwright, markitdown, filesystem, github, brave-search
Issue: Playwright fails to start
Solution: First run downloads browser binaries (~300MB). Requires internet connection.
Issue: Want to disable MCP
Solution: Set DISABLE_MCP=true in .env file. All native functions continue to work.
Apache 2.0 License - see LICENSE file for details.