HomurAI

The time-looping AI that never forgets.

HomurAI is an autonomous multi-agent system that turns tickets into tested, reviewed pull requests. It loops through development cycles -- learning, refining, and building on the last -- until the code is perfect.

Like Homura Akemi, who loops through time while retaining every memory, HomurAI retains full context across every iteration. No context collapse. No forgotten decisions. No wasted cycles.

Quick Start

# Install globally
npm install -g homurai

# Initialize in your project
homurai init

# Analyze your codebase
homurai learn

# Ingest a requirements document into tickets
homurai ingest -f roadmap.md --prefix REQ

# Run the full pipeline on a ticket
homurai run -t REQ-1

That's it. HomurAI takes it from there: plan, design, implement, QA, review, PR.

How It Works

Ticket --> Plan --> Design --> Code --> QA --> Review --> PR
            |        |         |        |       |         |
            '--------'-------- '----- --'-------'---------'
              Context retained across every phase

HomurAI orchestrates a pipeline of specialized agents, each with full access to every decision made before it:

| Phase | What happens | | ---------- | ---------------------------------------------------------- | | Plan | Analyzes requirements, creates implementation strategy | | Design | Writes technical specification from plan | | Code | Implements according to spec with full context | | QA | Parallel validation -- lint, types, tests, build | | Review | Multi-perspective review -- quality, security, performance | | PR | Creates a pull request with all artifacts |

Key Features

Context Retention -- MCP-based persistent memory prevents the "dumb AI" problem. Every decision, every artifact, every lesson is retained across sessions.

Visual Testing -- Agents capture screenshots, analyze UI/UX, and compare against baselines using Playwright. They can see their work.

Parallel Execution -- QA runs 4 checks simultaneously. Review provides 6 perspectives at once. 50% faster than sequential.

Self-Improving -- HomurAI develops itself. Each version is built by the previous one. The system learns from its own Architecture Decision Records.

Queue Processing -- Batch multiple tickets for sequential processing. Perfect for overnight runs or CI/CD integration.

Webhook Integration -- Trigger workflows from GitHub Issues or Jira via webhooks with HMAC-SHA256 validation.

CLI Commands

| Command | Description | | ------------------- | --------------------------------------------------- | | homurai init | Initialize the agent system in your repository | | homurai learn | Analyze your project and build intelligence profile | | homurai ingest | Turn documents into actionable tickets | | homurai run | Execute the full agent pipeline on a ticket | | homurai queue | Process multiple tickets sequentially | | homurai status | View ticket and workflow status | | homurai mcp start | Start the MCP server for Claude Code integration |

Requirements

• Node.js >= 20.0.0
• Claude Code CLI installed and authenticated (download)
• Git repository

MCP Integration

HomurAI runs as an MCP server, giving Claude Code access to persistent memory, artifact management, visual testing, and code intelligence tools.

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "homurai": {
      "command": "npx",
      "args": ["homurai", "mcp", "start"],
      "env": {
        "AGENT_ROOT": "${PWD}"
      }
    }
  }
}

Documentation

Full documentation, guides, and examples:

homur.ai

• Quick Start Guide -- Get running in 5 minutes
• CLI Reference -- All commands and options
• Configuration -- Customize agent behavior
• Self-Hosted Runner -- CI/CD integration
• Webhook Integration -- GitHub/Jira automation

License

MIT -- see LICENSE

Links

• Website: homur.ai
• GitHub: github.com/mattweberio/homurai
• Issues: GitHub Issues
• Security: [email protected]