Autonomous Coding Agent for code refactoring
npm install coderefactoragentAn autonomous coding agent for refactoring codebases using Claude AI.
This project implements an Orchestrator-Implementer pattern—a proven multi-agent architecture for long-running tasks that avoids context window exhaustion and maintains coherence across sessions.
```
┌─────────────────────────────────────────────────────────────────┐
│ CODE REFACTOR AGENT │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ ORCHESTRATOR │ │ IMPLEMENTER │ │
│ │ (First Run) │ │ (Iterative Sessions) │ │
│ ├─────────────────┤ ├─────────────────────────────┤ │
│ │ • Analyze code │ │ • Pick ONE pending task │ │
│ │ • Create tasks │ ──────► │ • Implement changes │ │
│ │ • Set rules │ │ • Validate & mark done │ │
│ │ • Init notes │ │ • Log session progress │ │
│ └─────────────────┘ └──────────┬──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ All tasks done? │ │
│ └────────┬─────────┘ │
│ No │ Yes │
│ │ └────► Complete! │
│ ▼ │
│ Next session │
│ │
└─────────────────────────────────────────────────────────────────┘
Modern LLM agent research (see Anthropic's context engineering guide and Azure's orchestration patterns) identifies key challenges for long-running tasks:
| Challenge | How This Architecture Solves It |
|-----------|--------------------------------|
| Context window exhaustion | Implementer starts fresh each session, focused on a single task |
| Context rot (degraded performance as tokens accumulate) | Clean context per task prevents quality degradation |
| Lost state between sessions | session_notes.txt maintains continuity and decisions |tasks.json
| Unclear progress | provides explicit tracking with status |
| Inconsistent validation | Rules defined upfront by orchestrator, applied consistently |
Runs once at project initialization to:
- Analyze codebase structure, tech stack, and patterns
- Decompose the refactoring goal into discrete, focused tasks
- Create project-specific validation rules (lint, build, test commands)
- Initialize session notes with architectural context
Runs iteratively until all tasks complete:
- Single-task focus: Picks exactly ONE pending task per session
- Full lifecycle: Implement → Validate → Update status → Log progress
- Context isolation: Each session starts with minimal context (notes + current task)
- Automatic continuation: Sessions chain automatically with progress tracking
All state persists in the .coderefactoragent/ directory:
``
.coderefactoragent/
├── refactor_goal.txt # Your refactoring objective (user-created)
├── tasks.json # Task list with status tracking
├── session_notes.txt # Cumulative log of all sessions
└── validation_rules.md # Project-specific validation commands
tasks.json - Structured task tracking:
`json`
[
{ "id": 1, "description": "Convert var to const in utils/", "status": "done" },
{ "id": 2, "description": "Update imports in components/", "status": "pending" }
]
session_notes.txt - Session-by-session progress log:
``
Session 3 completed Task #2
Changes: Updated 15 import statements in src/components/
Validation: npm run lint ✓, npm run build ✓
Next: Task #3 - Update test files
Progress displayed after each session:
``
Progress: 5/12 tasks completed (41.7%)
`bash`
npm install -g code-refactor-agent
Option 1: Claude Code (Recommended)
If you have a Claude subscription and are logged into Claude Code installed locally, no API key is needed. The agent will authenticate automatically.
Option 2: API Key
Set your Anthropic API key as an environment variable:
`bash`
export ANTHROPIC_API_KEY=your_api_key_here
Or create a .env file in your project root:
``
ANTHROPIC_API_KEY=your_api_key_here
1. Create a .coderefactoragent directory in your project root:
`bash`
mkdir -p .coderefactoragent
2. Create a refactor_goal.txt file with your refactoring goal:
`bash`
echo 'Convert all var declarations to const/let' > .coderefactoragent/refactor_goal.txt
3. Run the agent:
`bash`
code-refactor-agent
| Option | Description | Default |
|--------|-------------|---------|
| -d, --project-dir | Project directory to refactor | Current directory |-i, --max-iterations
| | Maximum number of iterations | Unlimited |-m, --model
| | Claude model to use | claude-haiku-4-5 |
`bashRun in current directory
code-refactor-agent
Development
$3
`bash
git clone
cd code-refactor-agent
npm install
`$3
`bash
npm run build
`$3
`bash
npm run dev
`$3
Link the package globally for local testing:
`bash
npm run build
npm run link
`Now you can use
code-refactor-agent anywhere on your system.To unlink:
`bash
npm run unlink
``ISC