Angy

Product Introduction

1. Definition: Angy is an open-source multi-agent fleet manager, scheduler, and specialized Integrated Development Environment (IDE) built specifically for the Claude Code CLI. It functions as an orchestration layer that wraps the Claude executable, transforming a single-agent chat interface into a deterministic, automated production line for software engineering.

2. Core Value Proposition: Angy exists to solve the "integration failure" problem inherent in single-pass AI code generation. By implementing a deterministic TypeScript state machine, it orchestrates multiple specialized Claude agents through a rigorous Plan → Build → Test pipeline. The primary goal is to allow developers to ship verified, full-stack features autonomously while eliminating manual intervention and AI hallucinations through adversarial verification and isolated Git worktrees.

Main Features

1. Deterministic Multi-Phase Pipeline: Unlike standard AI tools that rely on the LLM to decide the next step, Angy utilizes a hard-coded TypeScript state machine (PipelineRunner). This pipeline enforces a strict sequence: Architect (Planning) → Builder (Incremental Implementation) → Tester (Verification) → Counterpart (Adversarial Review). The system communicates with the Claude CLI via Tauri’s shell plugin using structured JSON streaming (stream-json), ensuring high-reliability data extraction for state transitions.

2. Adversarial Counterpart Verification: Angy introduces a persistent "Counterpart" agent that acts as a built-in skeptic. This agent independently audits the Architect's plans and the Builder's code. It categorizes issues as CRITICAL, MAJOR, or NIT and has the authority to block pipeline progression. If the Counterpart rejects a build, it generates structured "fix-todos" that feed back into the implementation phase for up to five iterative cycles of refinement.

3. Parallel Execution via Git Worktrees: To bypass repository locks and branch conflicts common in multi-agent environments, Angy leverages Git worktrees. Each "Epic" (a task or feature) is assigned a dedicated directory within .angy-worktrees/. This allows multiple agents to work on the same repository simultaneously in total isolation. Once a task is complete, the scheduler manages the cleanup or hands the worktree off to a sequential successor.

4. Autonomous Scheduler and Dependency Graph: The Angy engine includes a background scheduler that ticks every 30 seconds to prioritize tasks based on a complex scoring algorithm (priority, age, complexity, and dependency depth). It supports advanced epic chaining via dependsOn (prerequisite gates) and runAfter (sequential continuation with branch inheritance), ensuring that large-scale features are built in the correct architectural order.

Problems Solved

1. Pain Point: Integration and System-Level Bugs: AI agents often produce code that works in isolation but fails when integrated (e.g., schema mismatches between frontend and backend or incorrect Docker configurations). Angy’s incremental build-and-test approach catches these "blast radius" errors early by verifying each small chunk of code before proceeding.

2. Target Audience:

• Full-Stack Developers: Seeking to automate the creation of complex features across multiple layers of the stack.
• Software Architects: Who need to define high-level plans and have them executed with adversarial oversight.
• DevOps Engineers: Managing complex deployments and local environment setups like Docker Compose.
• Open Source Contributors: Looking for a localized, high-orchestration alternative to commercial AI IDEs.

3. Use Cases:

• Greenfield Feature Development: Building entire subsystems from a single specification (e.g., creating 12+ database tables and corresponding API endpoints).
• Automated Bug Fixing: Using the "Fix" pipeline to diagnose and resolve issues with context-aware feedback from previous failures.
• Codebase Investigation: Running read-only "Investigate" epics to generate findings and evidence regarding complex legacy code.
• Parallel Refactoring: Executing multiple architectural changes across different modules simultaneously without manual merge conflict resolution.

Unique Advantages

1. Differentiation: Most AI coding tools (like Cursor or basic Claude Code) focus on "Conversation-Driven Development." Angy shifts the paradigm to "Orchestration-Driven Development." It treats the LLM as a raw compute resource (a "specialist process") rather than a chat partner, removing the unpredictability of LLM-based routing.

2. Key Innovation: Incremental Build Logic: Instead of generating 50 files in one pass, Angy’s "Splitter" logic breaks a plan into 4–8 sequential increments. By verifying each increment with a dedicated "Tester" agent before moving to the next, it prevents cascading errors where a single wrong field name in a data model breaks every downstream component.

Frequently Asked Questions (FAQ)

1. How does Angy differ from using Claude Code directly? While Claude Code is a powerful CLI for single-agent tasks, Angy acts as a fleet manager for it. Angy spawns multiple Claude processes, manages their state, enforces a deterministic pipeline, provides a GUI for tracking progress, and uses Git worktrees to allow those agents to work in parallel—capabilities not natively present in the standard Claude CLI.

2. What is an "Adversarial Counterpart" in Angy? The Counterpart is a secondary, persistent AI session designed to find flaws in the primary agent's work. It performs code reviews, runs tests independently, and rejects any code that doesn't meet the project's standards. This "skeptical" layer is what allows Angy to ship verified code with significantly higher reliability than single-agent systems.

3. Can Angy handle multiple projects and repositories at once? Yes. Angy features a multi-project Kanban board and a global scheduler. It can manage independent branches and worktrees across different repositories simultaneously, enforcing global and per-project concurrency limits and API cost budgets to prevent overages.

4. Is Angy's pipeline controlled by the AI? No. The pipeline is a coded TypeScript state machine. This ensures that the flow from Planning to Building to Testing is strictly followed. The AI provides the content and performs the tasks within those stages, but the logic governing "what happens next" is deterministic and human-defined, which prevents the agent from getting stuck in "thought loops."

5. How do I fix the macOS "not notarized" error when installing Angy? Because Angy is a high-performance developer tool, users may need to clear the extended attributes after downloading the DMG. This is done by running xattr -cr ~/Downloads/angy_*.dmg in the terminal, which allows the app to bypass macOS Gatekeeper restrictions for non-notarized open-source software.