## Claudiomiro: Autonomous AI-Powered Development Agent

Turn complex development into a fully automated process without sacrificing production-grade code quality.

Send your prompt:

It **decomposes, codes, reviews, builds, tests, and commits**, autonomously, in parallel and while economizing tokens.

🔥 [Use Ollama](./docs/HOW-TO-USE-OLLAMA.md) to cut token costs even further — **up to 90% additional savings**.

![Claudiomiro Terminal](https://github.com/samuelfaj/claudiomiro/blob/main/docs/assets/readme-reference.jpg?raw=true)

------

## The AI Poductivity Paradox

Today’s AI coding assistants are powerful, but **still fundamentally unfinished**. 

They generate promising first drafts, then hand the burden back to you — forcing manual review, debugging, and cleanup.

The result is a **productivity paradox**: tools that speed up typing but slow down everything else.

**Claudiomiro breaks this cycle**.

Give Claudiomiro a task and it will:

1. Break it into smaller, parallelizable tasks
2. Execute tasks simultaneously using AI agents
3. Review the code
4. Run tests and fix failures automatically
5. Create production-ready commits and pull request

## Documentation

- [Basic Usage Guide](./docs/basic-usage.md) - Complete guide from installation to your first task
- [Commands Reference](./docs/commands/README.md) - All available commands and options
- [Model Configuration](./docs/model-configuration.md) - AI model selection and cost optimization
- [ACE](./docs/agentic-context-engineering.md) - Agentic Context Engineering and Reflections in Claudiomiro

### Examples

```bash
# Install
npm install -g claudiomiro

# Interactive mode
claudiomiro

# Basic usage with a prompt
claudiomiro --prompt="Add user authentication with JWT"

# Run in a specific directory
claudiomiro /path/to/project --prompt="Refactor payment processing"

# Fix failing tests automatically
claudiomiro --fix-command="npm test"

# Security audit with iterative fixes
claudiomiro --loop-fixes --prompt="Find and fix security vulnerabilities"

# Review and fix current branch before PR
claudiomiro --fix-branch
```

## Supported AI Models

```bash
claudiomiro --claude      # Anthropic Claude
claudiomiro --codex       # OpenAI Codex
claudiomiro --gemini      # Google Gemini
claudiomiro --deep-seek   # DeepSeek
claudiomiro --glm         # GLM
```

- [DeepSeek Setup](./docs/HOW-TO-RUN-WITH-DEEPSEEK.md)
- [GLM Setup](./docs/HOW-TO-RUN-WITH-GLM.md)

### Smart Model Selection

Claudiomiro automatically selects the optimal model for each step to balance cost and performance:

| Model | Maps To | Use Case |
|-------|---------|----------|
| `fast` | Haiku | Simple tasks, commits, quick operations |
| `medium` | Sonnet | Standard features, balanced performance |
| `hard` | Opus | Complex reasoning, architectural decisions |

```bash
# Force a specific model for all steps
CLAUDIOMIRO_MODEL=fast claudiomiro --prompt="Simple README update"

# Override model for specific step
CLAUDIOMIRO_STEP5_MODEL=hard claudiomiro --prompt="Complex refactoring"
```

Tasks can declare their complexity with `@difficulty` tags in BLUEPRINT.md:

```markdown
@difficulty fast    # Simple bug fix → uses Haiku
@difficulty medium  # Standard feature → uses Sonnet
@difficulty hard    # Architectural change → uses Opus
```

See [Model Configuration Guide](./docs/model-configuration.md) for details.

### Multi-Repository Mode

Work across backend and frontend repositories simultaneously:

```bash
# Monorepo or separate repos - Claudiomiro auto-detects
claudiomiro --backend=./api --frontend=./web --prompt="Add user authentication with JWT"
```

Features:
- Automatic git configuration detection (monorepo vs separate repos)
- Scope-aware task decomposition (`@scope backend|frontend|integration`)
- Integration verification between codebases
- Coordinated commits across repositories

### Legacy Systems Support

Claudiomiro handles complex multi-repository environments with legacy systems:

```bash
# Include legacy systems in your workflow
claudiomiro --backend=./api --legacy=./legacy-service --frontend=./web --prompt="Add feature across stack"

# Legacy backend with modern frontend
claudiomiro --legacy-backend=./legacy-api --frontend=./web --prompt="Modernize frontend integration"

# Legacy frontend with modern backend
claudiomiro --backend=./api --legacy-frontend=./legacy-ui --prompt="Update legacy UI components"

# Multiple legacy systems with migration path
claudiomiro --legacy-backend=./old-api --legacy-frontend=./old-ui --backend=./api --frontend=./web --prompt="Migrate features to new stack"
```

Capabilities for legacy codebases:
- Automatic legacy codebase detection and analysis
- Preservation of existing patterns and conventions
- Safe refactoring with minimal disruption
- Integration tests between modern and legacy systems
- Gradual migration support without breaking changes
- Parallel support for legacy and modern stacks

See [Multi-Repository Mode Guide](./docs/multi-repository-mode.md) for details.

### Local LLM Co-Pilot (Optional)

Reduce token consumption and latency by running a local LLM alongside the main AI:

```bash
# Enable local LLM co-pilot with Ollama
CLAUDIOMIRO_LOCAL_LLM=qwen2.5-coder:7b claudiomiro --prompt="Add authentication"
```

- [Local LLM Setup Guide](./docs/HOW-TO-RUN-WITH-LOCAL-LLM.md)

### Configuration

Manage persistent configuration interactively:

```bash
# Open interactive configuration manager
claudiomiro --config

# Quick set a value
claudiomiro --config CLAUDIOMIRO_LOCAL_LLM=qwen2.5-coder:7b
```

Configuration is stored globally and loaded automatically on startup.

## Requirements

For best results, your project should have:
- Linting (ESLint, Pylint, etc.)
- Unit tests

These create a feedback loop that lets Claudiomiro validate and fix its own work.

## Safety

- Max 20 cycles per task (customize with `--limit=N`)
- Critical bug detection before commit
- Use `--push=false` to review before pushing