Skip to content
/
Tier A A10 Memory engine

Claudiomiro

claudiomiro · samuelfaj/claudiomiro · ★ 412 · last commit 2026-01-31

Fully autonomous parallel coding agent that decomposes prompts via DAG, executes tasks simultaneously with multi-provider support, learns from reflections, and commits tested production-ready code.

Best whenContext engineering — not prompt engineering — is the real lever: compress, index, and curate context so the AI sees exactly what matters and nothing else.
Skip ifBabysitting AI with 'continue' prompts (should run to completion autonomously), Sending full file contents when code symbols suffice (use code index)
vs seeds
claude-flowuses MCP tools while claudiomiro wraps AI CLIs as sub…
Primitive shape
No installable primitives
00

Summary

Claudiomiro — Summary

Claudiomiro (npm install -g claudiomiro) is a JavaScript/Node.js CLI tool that runs fully autonomous parallel task execution using AI coding agents (Claude, Codex, Gemini, DeepSeek, GLM), decomposes a user prompt into parallelizable sub-tasks via a DAG executor, executes them simultaneously, runs automated tests and code review, and commits production-ready code. At v2.6.91 with 412 stars (and 50 forks), it is the most sophisticated autonomous coding agent CLI in this batch. Its key innovations are: (1) Agentic Context Engineering (ACE) — a context cache, code index, and LLM-assisted context compression pipeline that reduces token consumption by 40-60%; (2) a Reflection Pipeline that analyzes completed tasks, extracts insights, and persists them as curated lessons for future runs; (3) a multi-executor architecture supporting 5 AI providers with local LLM co-pilot support via Ollama; and (4) multi-repository support (backend + frontend + legacy systems in one run). Compared to all seeds and other batch entries, Claudiomiro is closest to the "fully autonomous" end of the spectrum — it replaces the human development loop with an AI loop that iterates until the task is done, tests pass, and code is reviewed.

01

Overview

Claudiomiro — Overview

Origin

  • Author: Samuel Fajreldines (@samuelfaj)
  • Repo: https://github.com/samuelfaj/claudiomiro
  • Version: 2.6.91 (package.json)
  • License: None specified (ISC in package.json)
  • Stars: 412 | Forks: 50 | Contributors: 1 | Last commit: 2026-01-31

Philosophy

From the README:

"Send your prompt: It decomposes, codes, reviews, builds, tests, and commits, autonomously, in parallel and while economizing tokens."

"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."

"Claudiomiro breaks this cycle."

Core design principles:

  1. Intelligent Decomposition: breaks complex problems into parallelizable tasks
  2. Autonomous Execution: continuous loop until 100% task completion (no "continue" prompts)
  3. Parallel Execution: DAG executor runs independent tasks simultaneously
  4. Automatic Testing: executes and fixes failures automatically
  5. Automated Code Review: senior-level review before testing
  6. Production-ready Commits: tested, reviewed, and documented code

The AI Productivity Paradox framing

"The result is a productivity paradox: tools that speed up typing but slow down everything else. Claudiomiro breaks this cycle."

This positions Claudiomiro against Claude Code, Codex, and Cursor as an automation layer that completes the loop, not just the first draft.

Local LLM cost reduction

"Use Ollama to cut token costs even further — up to 90% additional savings."

The CLAUDIOMIRO_LOCAL_LLM=qwen2.5-coder:7b env var enables a local co-pilot for context summarization, reducing calls to the expensive frontier model.

02

Architecture

Claudiomiro — Architecture

Distribution

  • Type: npm package (CLI tool)
  • Install: npm install -g claudiomiro
  • Binary: claudiomiro
  • Required runtime: Node.js

Directory structure

samuelfaj/claudiomiro/
├── index.js                    # Entry point
├── src/
│   ├── commands/               # CLI command implementations
│   │   ├── config/
│   │   ├── fix-branch/
│   │   ├── fix-command/
│   │   ├── help/
│   │   ├── loop-fixes/
│   │   ├── task-executor/      # Main task execution logic
│   │   │   └── cli.js
│   │   ├── test-local-llm/
│   │   └── token-optimizer/
│   └── shared/
│       ├── config/             # Configuration management
│       ├── executors/          # AI provider executors
│       │   ├── claude-executor.js (+ test)
│       │   ├── codex-executor.js (+ test)
│       │   ├── gemini-executor.js (+ test)
│       │   ├── deep-seek-executor.js (+ test)
│       │   ├── glm-executor.js (+ test)
│       │   ├── parallel-state-manager.js (+ test)
│       │   └── index.js (+ test)
│       ├── services/
│       │   ├── code-index/     # Semantic code indexing
│       │   ├── context-cache/  # Context cache (.claudiomiro/cache/context-cache.json)
│       │   ├── diff-service.js
│       │   ├── git-commit.js
│       │   ├── git-detector.js
│       │   ├── git-manager.js
│       │   ├── git-status.js
│       │   ├── insights/       # Insight store (cross-run learnings)
│       │   ├── integration-verifier.js
│       │   ├── legacy-system/
│       │   ├── local-llm/      # Ollama local LLM integration
│       │   ├── prompt-reader.js
│       │   ├── reflection/     # Reflection pipeline
│       │   │   ├── reflector.js
│       │   │   └── reflection-hook.js
│       │   └── research-manager/
│       ├── templates/          # Prompt templates
│       └── utils/
├── .claude/
│   ├── settings.local.json     # Claude Code settings
├── CLAUDE.md                   # Development guide for Claude
└── docs/
    ├── agentic-context-engineering.md
    ├── basic-usage.md
    └── HOW-TO-*.md

Target AI tools

  • Claude Code / Anthropic Claude (primary)
  • Codex (OpenAI)
  • Gemini (Google)
  • DeepSeek
  • GLM
  • Local LLM via Ollama (co-pilot only)

Data directory

.claudiomiro/ — runtime cache and state:

  • .claudiomiro/cache/context-cache.json
  • .claudiomiro/cache/code-index.json
  • .claudiomiro/insights/reflections/<TASK>.json
03

Components

Claudiomiro — Components

CLI flags (primary interface)

Flag Purpose
claudiomiro Interactive mode
--prompt="..." One-shot task prompt
--claude / --codex / --gemini / --deep-seek / --glm Select AI provider
--fix-command="npm test" Run command, fix failures in loop
--loop-fixes Fix failures iteratively
--fix-branch Review and fix current branch before PR
--backend=./api --frontend=./web Multi-repository mode
--backend=./api --legacy=./legacy Legacy system support
--config Interactive configuration manager
--push=false Disable auto-push (review before pushing)
--limit=N Max cycles (default: 20)

Service modules

Module Purpose
parallel-state-manager.js Manages parallel task execution state
context-cache/ Incremental context cache with LLM summarization
code-index/ Semantic code symbol index for efficient prompting
insights/insight-store.js Cross-run curated learning store
reflection/reflector.js Iterative reflection pipeline
local-llm/ Ollama integration for local context summarization
legacy-system/ Legacy codebase detection and safe refactoring
integration-verifier.js Integration tests between repos
git-commit.js Automated commit creation
diff-service.js Diff analysis

Executor classes (5 AI providers)

Executor Provider
claude-executor.js Anthropic Claude
codex-executor.js OpenAI Codex
gemini-executor.js Google Gemini
deep-seek-executor.js DeepSeek
glm-executor.js GLM

Each executor has a corresponding logger (claude-logger.js, etc.) and test file.

DAG Executor (parallel task execution)

src/services/dag-executor.js — the core parallelism engine:

  • Decomposes tasks into a directed acyclic graph
  • Executes independent tasks simultaneously
  • Manages task dependencies and sequencing

Step system (src/commands/task-executor/)

Sequential step pipeline for each task:

  1. Step 4: Generate TODO (optimized context assembly)
  2. Step 5: Execute task (AI coding engine)
  3. Step 6: Curate insights (extract patterns from execution)
05

Prompts

Claudiomiro — Prompts

Excerpt 1: docs/agentic-context-engineering.md — ACE system description

# Agentic Context Engineering and Reflections in Claudiomiro

- **Agentic Context Engineering** collects, compresses, and distributes only the most relevant information for every step (`src/shared/services/context-cache`).
- **Reflections** review each run to capture actionable insights (`src/shared/services/reflection`, `src/commands/task-executor/steps/step5/reflection-hook.js`).
- **Insights Service** is the shared memory for curated patterns and reflections (`insight-store.js`).

### Step-by-step data flow

1. **Step 4 – Generate TODO** — Calls `buildOptimizedContextAsync`, which blends:
   - the cached `AI_PROMPT.md` summary,
   - completed tasks with files/decisions,
   - relevant symbols from the code index,
   - curated insights from previous runs.
   The resulting prompt snippet keeps content short and lists only file references that the agent can open if needed.

2. **Step 5 – Execute Task** — After executing, writes `CONTEXT.md` and invokes `markTaskCompleted` to refresh the incremental cache. Execution metrics (attempts, errors, change size, complexity) drive the reflection trigger.

3. **Step 6 – Curate Insights** — Aggregates patterns from TODO/CONTEXT/CODE_REVIEW/REFLECTION. Persists the best entries with scope classification.

Technique: Structured 3-phase pipeline where each phase produces a specific artifact (AI_PROMPT.md → CONTEXT.md → REFLECTION.md → insights store). Context is compressed rather than expanded — only high-signal symbols and file references, not full file contents. Incremental cache prevents re-summarizing completed work.

Excerpt 2: CLAUDE.md — Development guide instructs Claude about the codebase

## Development Conventions

### 1. Code Language

**CRITICAL RULE**: All code, comments, variable names, function names, and documentation MUST be written in English.

### 2. File Naming Conventions

**CRITICAL RULE**: All `.md` files inside `src/steps/` MUST use lowercase names.

### 3. Test Structure

**FUNDAMENTAL RULE**: Every code file must have its corresponding test file created simultaneously.

Technique: CLAUDE.md as a development contract for Claude when working on the Claudiomiro codebase itself (meta: using Claude to develop the Claude-executor tool). Critical rules use bold **CRITICAL RULE** annotations. Naming conventions enforced via documentation rather than linter.

Prompting techniques observed

  1. Context engineering pipeline — multi-stage context assembly (cache + code index + insights) before each AI call
  2. Reflection loop — triggered by complexity/error metrics; produces structured REFLECTION.md
  3. Insight extraction — Claude prompted to extract actionable patterns from trajectory; stored and reused
  4. Local LLM optimization — Ollama summarizes context locally; only final prompt sent to frontier model
  5. @scope tagging — multi-repo tasks tagged @scope backend|frontend|integration for routing
  6. Critical rule annotations — **CRITICAL RULE** and **FUNDAMENTAL RULE** distinguish must-follow from guidance
09

Uniqueness

Claudiomiro — Uniqueness

differs_from_seeds

No seed closely matches Claudiomiro's architecture. The closest is claude-flow (multi-agent, SQLite state, continuous execution mode), but claude-flow uses an MCP toolserver and hive-mind consensus; Claudiomiro is a standalone CLI that wraps AI coding CLIs as subprocesses with a DAG parallel executor. The reflection + insights pipeline (cross-run learning, structured insight extraction, curated lessons injected into future context) has no equivalent in any seed — only ccmemory (Neo4j graph memory) and claude-flow (SQLite vector store) even attempt cross-run memory, but neither has an explicit reflection/learning loop. The local LLM co-pilot (Ollama for context compression) is also unique in this batch. Claudiomiro is the "fully autonomous" end of the spectrum — it is the only tool that explicitly aims to replace the human development loop entirely, running until the task is complete, tests pass, and code is committed.

What makes Claudiomiro unique

  1. Reflection pipeline — post-task reflection extracts structured insights; curated lessons injected into future task contexts (cross-run learning loop)
  2. Agentic Context Engineering — multi-stage context assembly (cache + code index + local LLM summarization) targeting 40-60% token reduction
  3. DAG parallel executor — explicit directed acyclic graph for task dependency management and parallel execution
  4. 5-provider multi-executor — Claude, Codex, Gemini, DeepSeek, GLM with per-provider executor and logger classes
  5. Local LLM co-pilot — Ollama model for context summarization without frontier API calls
  6. Multi-repository mode — backend + frontend + legacy systems in one invocation with @scope tagging
  7. --fix-command and --fix-branch modes — dedicated workflows for fixing test failures and reviewing branches
  8. Cross-run insight persistence — .claudiomiro/insights/reflections/ provides growing project intelligence

Observable failure modes

  1. Single developer: 1 contributor (samuelfaj); high bus factor
  2. No isolation: DAG tasks can conflict on shared files if dependencies are wrong
  3. Brazilian Portuguese codebase: CLAUDE.md explicitly requires English, suggesting some code/comments may be in Portuguese
  4. Proprietary state format: .claudiomiro/ cache format undocumented; upgrade path unclear
  5. Max 20 cycles: aggressive cycle limit may cut off complex tasks before completion
  6. ISC license: no license file in repo; license field in package.json is "ISC" but no LICENSE file committed

Positioning

Claudiomiro is the "full autonomy" answer to the question "what if Claude Code ran in a loop until it was done?" It targets developers who want zero babysitting — send a prompt, return to find committed, tested code. It competes with Devin and SWE-agent for the autonomous coding agent niche, not with Claude Code plugins.

04

Workflow

Claudiomiro — Workflow

Primary workflow: task execution

claudiomiro --prompt="Add user authentication with JWT"

1. Intelligent Decomposition
   └─ Breaks prompt into parallelizable sub-tasks
   └─ Builds dependency graph (DAG)

2. Parallel Execution (DAG Executor)
   └─ Independent tasks run simultaneously
   └─ Each task: Step 4 (context) → Step 5 (execute) → Step 6 (reflect)

3. Automated Code Review
   └─ Senior-level review before testing

4. Test + Fix Loop
   └─ Run tests; fix failures automatically
   └─ Max 20 cycles (configurable via --limit=N)

5. Production-ready Commit
   └─ Tested, reviewed, documented code committed

Fix-command workflow

claudiomiro --fix-command="npm test"
  • Runs npm test
  • If tests fail, feeds failure output to AI for fixing
  • Loops until all tests pass or limit reached
  • Critical bug detection before commit

Fix-branch workflow

claudiomiro --fix-branch
  • Reviews current branch's changes
  • Fixes issues found before PR creation

Multi-repository workflow

claudiomiro --backend=./api --frontend=./web --prompt="Add user auth with JWT"
  • Auto-detects monorepo vs. separate repos
  • Scope-aware task decomposition (@scope backend|frontend|integration)
  • Integration verification between codebases
  • Coordinated commits across repos

Safety limits

  • Max cycles: 20 (customizable: --limit=N)
  • Critical bug detection: blocks commit if critical bugs found
  • Push control: --push=false to review before pushing

Reflection-based learning

After high-complexity tasks or repeated errors, the reflection pipeline runs:

  1. Assemble trajectory (TODO + CONTEXT + RESEARCH + CODE_REVIEW)
  2. Iterative reflection via Claude — extract structured insights
  3. Store insights in .claudiomiro/insights/reflections/<TASK>.json
  4. Curate lessons for Step 4 context on future runs
06

Memory Context

Claudiomiro — Memory & Context

Context cache (.claudiomiro/cache/context-cache.json)

The Agentic Context Engineering (ACE) system maintains an incremental context cache:

  • Only tasks marked "Fully implemented: YES" contribute to the consolidated context
  • Changing AI_PROMPT.md invalidates the summary automatically
  • LLM-assisted optimization (Ollama) can score relevance and produce targeted summaries
  • Reduces token consumption by 40-60% via compression

Code index (.claudiomiro/cache/code-index.json)

Semantic symbol index:

  • Functions, components, hooks indexed for quick reference
  • Built via CodeIndex.build() with semantic search (Ollama) or keyword fallback
  • Provides high-signal code references instead of full file embeddings
  • Can be force-rebuilt: CodeIndex.build(..., { forceRebuild: true })

Insights store (.claudiomiro/insights/reflections/<TASK>.json)

Cross-run curated learnings:

  • Reflection pipeline extracts actionable patterns from completed tasks
  • Persisted per-task in JSON format
  • Loaded by Step 4 for future tasks via getCuratedInsightsForTask()
  • Action items from reflections appear in CURATED INSIGHTS TO CONSIDER section of subsequent TODOs

Per-task artifacts (in project directory)

File Contents
AI_PROMPT.md Optimized context summary (cached)
TODO.md Current task decomposition
CONTEXT.md Execution results and decisions
CODE_REVIEW.md Code review findings
RESEARCH.md Research results
REFLECTION.md Reflection output (latest iteration)

Memory persistence scope

  • Project-scoped (.claudiomiro/ in working directory)
  • Cross-run — insights and context cache persist between claudiomiro invocations
  • Multi-repository — @scope tagging ensures context isolation between repos

Cross-session handoff

Yes — context cache and insights store enable rich cross-session state. This is the most sophisticated memory system in the batch (only claudiomiro and ccmemory have explicit cross-run learning mechanisms).

07

Orchestration

Claudiomiro — Orchestration

Multi-agent

Yes — parallel task execution via DAG executor. Multiple AI provider instances can run simultaneously for independent tasks.

Orchestration pattern

Parallel-fan-out — the DAG executor decomposes the input prompt into a dependency graph, then executes independent task nodes simultaneously. Dependent nodes wait for their prerequisites.

Multi-model

Yes — the tool supports 5 AI providers simultaneously. In multi-repository mode, different scopes can potentially use different executors. The local LLM co-pilot (Ollama) is always a separate model from the main executor.

Model role mapping:

  • Main executor: Claude / Codex / Gemini / DeepSeek / GLM (user selects)
  • Co-pilot: local Ollama model (for context summarization, topic detection)
  • Reflection: Claude (for insight extraction from execution trajectories)

Isolation mechanism

No git worktrees. Multi-repository mode provides scope isolation via @scope backend|frontend|integration tagging, but tasks within a repo can conflict if they touch the same files.

Execution mode

Continuous loop — runs until all tasks are complete (or --limit hit). The main loop executes tasks, runs tests, fixes failures, and commits without returning to the user. The closest to a "background daemon" in this batch.

Crash recovery

Implicit — context cache and TODO.md state preservation. If the loop is interrupted, the next run can load the cached context and continue. Not a formal checkpoint system.

Reflection trigger heuristics

Reflection runs when:

  • attempts >= 2
  • Repeated errors
  • codeChangeSize > 500 lines
  • TODO marked as high complexity

Max iterations

Default: 20 cycles. Configurable via --limit=N.

Consensus

None — single-agent loop (one executor per task, though multiple tasks run in parallel).

08

Ui Cli Surface

Claudiomiro — UI & CLI Surface

Dedicated CLI binary

Yes — claudiomiro.

Flag / Mode Purpose
claudiomiro Interactive mode
claudiomiro --prompt="..." One-shot autonomous mode
claudiomiro --fix-command="npm test" Fix-until-pass loop
claudiomiro --loop-fixes Iterative fix loop
claudiomiro --fix-branch Branch review and fix
claudiomiro --backend=... --frontend=... Multi-repository mode
claudiomiro --config [KEY=VALUE] Configuration management
claudiomiro --claude/--codex/--gemini/--deep-seek/--glm Provider selection
claudiomiro --push=false Disable auto-push
claudiomiro --limit=N Cycle limit

Local UI

None — terminal output only. The tool uses boxen, chalk, gradient-string for styled terminal output, but no TUI or web dashboard.

IDE integration

None — standalone CLI. The repo contains a .claude/settings.local.json for using Claude Code when developing claudiomiro itself, but this is for the developer, not users.

Observability

  • Terminal output: styled progress via chalk/boxen/gradient-string
  • TODO.md: current task decomposition visible in project directory
  • CONTEXT.md: execution results per task
  • REFLECTION.md: reflection output
  • insights store: .claudiomiro/insights/ for cross-run learnings

Configuration persistence

claudiomiro --config CLAUDIOMIRO_LOCAL_LLM=qwen2.5-coder:7b  # set globally
claudiomiro --config  # interactive configuration manager

Configuration stored globally, loaded at startup.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k
A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k
A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…