CodeAgent

Research-backed autonomous coding framework for Claude Code. Transforms Claude Code into an accuracy-optimized system with persistent memory, structured reasoning, and TDD enforcement.

Features

Feature	Description
Memory System	A-MEM brain-like memory with auto-linking and evolution
Tree-of-Thought	Explore multiple approaches before committing
TDD Enforcement	Strict test-first development workflow
MCP-First Integration	External services via code-execution sandbox
Self-Reflection	Learn from failures, improve over time
External Validation	Never self-review, always use tools

Install

curl -fsSL https://raw.githubusercontent.com/Questi0nM4rk/codeagent/main/install.sh | bash

Or clone manually:

git clone https://github.com/Questi0nM4rk/codeagent.git && cd codeagent && ./install.sh

Quick Start

codeagent start              # Start infrastructure
cd /your/project && codeagent init   # Initialize project

Requirements

• Docker with Docker Compose v2
• Node.js 18+ for MCP servers
• Python 3.10+ for custom MCPs
• Claude Code CLI (claude command)

Commands

CLI Commands

codeagent start     # Start Qdrant
codeagent stop      # Stop services
codeagent status    # Health check all services
codeagent config    # Configure API keys
codeagent init      # Initialize project for memory tagging

Slash Commands

Use in Claude Code conversations:

Command	Description
/scan	Build knowledge graph of codebase
/plan "task"	Research and design with Tree-of-Thought
/implement	TDD execution with quality gates
/integrate	Merge parallel work streams
/review	Validate with external tools

Skills

Six specialized skills auto-activate based on context:

Skill	Purpose
researcher	Memory-first context gathering
architect	Tree-of-Thought solution design
orchestrator	Parallel execution analysis
implementer	Strict TDD workflow
reviewer	External tool validation
learner	Pattern extraction

MCP Servers

Core MCPs

MCP	Purpose
context7	Up-to-date library documentation
code-execution	Sandboxed Python/CLI execution (Docker)

Custom MCPs

MCP	Backend	Purpose
reflection	Qdrant	Self-reflection and episodic memory (+21% accuracy)
amem	ChromaDB	Brain-like memory with auto-linking and evolution

Infrastructure

Service	Version	Ports	Purpose
Qdrant	v1.16.2	6333, 6334	Vector embeddings (reflection MCP)

Local Storage:

• A-MEM: ~/.codeagent/memory/ (brain-like memory)

Embedding Cost: ~$0.0001 per memory (gpt-4o-mini for metadata generation)

Configuration

API Keys

Configure with:

codeagent config

Keys stored in ~/.codeagent/.env:

Key	Required	Purpose
OPENAI_API_KEY	Yes	A-MEM metadata generation
GITHUB_TOKEN	No	GitHub MCP - repository, issues, PRs, code search
TAVILY_API_KEY	No	Web research

Hooks

CodeAgent configures automatic hooks:

Hook	Trigger	Purpose
dangerous-command-check	Pre-Bash	Block dangerous commands
pre-commit	Pre-git commit	Run pre-commit checks
pre-push	Pre-git push	Run pre-push checks
auto-format	Post-Write/Edit	Format code by file type
index-file	Post-Write/Edit	Track changed files for indexing
session-end	Stop	Cleanup temporary files

Installation Structure

Global

~/.claude/
├── CLAUDE.md           # Personality + instructions
├── settings.json       # Permissions, hooks
├── skills/             # 6 skill definitions
├── commands/           # 5 slash commands
└── hooks/              # Hook scripts

~/.codeagent/
├── bin/                # CLI tools
├── mcps/               # Custom MCP servers
├── templates/          # CLAUDE.md templates
├── infrastructure/     # docker-compose.yml
└── .env                # API keys

Per-Project

Created by codeagent init:

project/
├── .claude/
│   └── project-info    # Project metadata for memory tagging
└── docs/
    └── decisions/      # Architecture decision records

Workflow

# 1. Start infrastructure
codeagent start

# 2. Initialize project
cd /your/project
codeagent init

Then in Claude Code:

/scan                           # Build knowledge graph
/plan "Add authentication"      # Research + design
/implement                      # TDD implementation
/review                         # Validate

Update

cd ~/.codeagent
git pull
./install.sh

Uninstall

./uninstall.sh

Philosophy

CodeAgent treats Claude as a thinking partner, not an assistant:

Traditional	CodeAgent
"Sure, I'll implement that"	"Have you considered X?"
Guesses when uncertain	"I'm not confident about this"
Accepts all requests	"I'd push back because..."

Principles

1. Partner before tool - Challenge, discuss, collaborate
2. Uncertainty before confidence - Say "I don't know" when unsure
3. Memory-first - Query memory before external research
4. External validation - Never self-review code
5. TDD always - Test, fail, code, pass
6. Accuracy over speed - Spend tokens for correctness

Troubleshooting

Services not starting

codeagent status              # Check health
docker logs codeagent-qdrant  # View logs
codeagent stop && codeagent start

MCPs not connecting

claude mcp list
~/.codeagent/mcps/install-mcps.sh --force

A-MEM issues

# Check storage directory
ls -la ~/.codeagent/memory/

# Test MCP
~/.codeagent/venv/bin/python -c "from amem_mcp import server; print('OK')"

# Verify API key (needed for metadata generation)
grep OPENAI_API_KEY ~/.codeagent/.env

License

MIT