Archai Join our Discord

A team of AI agents for Claude Code — not just one assistant, but a full development workflow.

Archai scaffolds a multi-agent system that plans before it codes, validates before it implements, and tests before it ships. One command sets it up. Claude Code does the rest.

Why archai?

Without structure, AI assistants jump straight to code — skipping analysis, missing edge cases, and producing work that needs reworking. archai fixes this with a three-phase workflow:

1. Planning Loop — Analyze the problem, validate the plan, design tests (2-4 iterations)
2. Implementation Loop — Code, test, review (only after you approve the plan)
3. Finalization — Quality checks, cleanup, commit, push, CI verification

Agents learn across sessions through a persistent knowledge base — decisions, constraints, patterns, and gotchas are recorded and searched before every new task.

You stay in control with approval gates between phases. Or use critical review mode to let a separate AI session review the plan automatically.

Quick Start

npm install -g @zik000/archai
cd your-project
archai init

That's it. archai detects your tech stack and creates everything you need. Now open Claude Code:

claude

And tell it what to build:

> Use task-prep for: add user authentication with JWT

After reviewing and approving the spec:

> Use maestro-agent for: the prepared task in .tasks/inbox/Task-AUTH-001.md

The agent system takes over — plans the work, waits for your approval, implements it, runs tests, and commits.

For small fixes

Skip the full workflow:

> Use quick-fix for: rename the userId variable to accountId

Shared knowledge across repos

Share decisions, patterns, and learnings between related projects:

archai knowledge create my-team       # Create a shared knowledge group
archai knowledge join my-team         # Link this project to the group

Agents automatically search shared knowledge before planning and write cross-cutting decisions back. Works across any number of repos.

For team sync via git:

archai knowledge remote my-team <git-url>   # Add remote
archai knowledge sync                       # Commit + pull + push

Optional setup wizards

archai setup-project     # Describe your project architecture
archai setup-config      # Configure commands, specialists, permissions
archai generate          # Generate project-specific specialist agents

How to Use

Step 0 (Optional): Prepare the Task

For vague or complex tasks, structure them first:

> Use task-prep for: add user authentication with JWT

The agent gathers project context, asks targeted clarifying questions, and produces a structured spec. After you approve, it saves to .tasks/inbox/ with a descriptive name like Task-AUTH-001.md.

Step 1: Define Your Task

Write a clear description of what you want done. Drop it into a task file:

.tasks/inbox/add-user-auth.md

Or just describe it directly in Claude Code. The more specific you are, the better the agents perform.

Step 2: Feed It to the Agent System

Open Claude Code and hand the task to maestro-agent:

> Use maestro-agent for: start working on the task .tasks/inbox/add-user-auth.md

That's it. The agent system takes over:

1. Planning — deep-analyst studies your codebase, plan-validator challenges the plan, tdd-designer writes tests first. This iterates 2-4 times until the plan is solid.
2. Your approval — The workflow stops and presents the plan. You APPROVE, REVISE, or REJECT.
3. Implementation — implementation-agent builds it, code-reviewer verifies it. Iterates until tests pass.
4. Finalization — finalization-agent runs quality checks, cleans up, commits, and pushes.

Critical Review Mode

For routine tasks where you trust the process, skip manual plan approval:

> Use maestro-agent with critical-review for: [your task]

A separate Claude session reviews the plan for blind spots. If it passes, implementation starts automatically. If issues are found, it falls back to asking you.

| Mode | When to use | Plan approval | |------|-------------|---------------| | Manual (default) | Learning, high-stakes, security-sensitive | You approve | | Critical review | Routine tasks, well-understood features | Auto if review passes |

Quick Fix

For small, obvious changes (typos, renames, config tweaks, 1-3 files):

> Use quick-fix for: [small change]

No planning docs, no approval gates. If the change turns out to be bigger than expected, it tells you to use maestro-agent instead.

Batch Tasks

For managing multiple tasks across an epic, drop them all into .tasks/inbox/ and run:

> Use task-orchestrator for: work through the tasks in .tasks/inbox/

It claims tasks one by one, creates branches, spawns the full workflow for each, and tracks progress.

Standalone Agents

You can use any agent directly:

| Agent | Use for | |-------|---------| | deep-analyst | Understanding code, analyzing a problem | | tdd-designer | Designing test suites | | cleanup-agent | Cleaning temp files before committing |

Agents (14 Core)

| Agent | Phase | Role | |-------|-------|------| | task-prep | Preparation | Architect-level task structuring and scoping | | maestro-agent | Orchestrator | Manages all three phases with iteration limits | | boss-agent | Orchestrator | Scans inbox, builds queue, dispatches tasks sequentially | | deep-analyst | Planning | Deep analysis and implementation planning | | plan-validator | Planning | Adversarial plan review — finds gaps | | tdd-designer | Planning | Designs tests before code, with concrete values | | critical-reviewer | Planning | Blind review via separate SDK session | | implementation-agent | Implementation | Autonomous execution of approved plan | | code-reviewer | Implementation | Verifies against acceptance criteria | | cleanup-agent | Finalization | Removes temp files, archives state | | finalization-agent | Finalization | Quality checks, commit, push, CI/CD | | git-coordinator | Finalization | Git coordination, merging, conflict resolution | | task-orchestrator | Workflow | Epic/task lifecycle management | | quick-fix | Standalone | Fast single-pass for small changes |

Specialist agents are generated from your config with archai generate — they understand your specific tech stack, file paths, and conventions.

Commands

| Command | Purpose | |---------|---------| | archai init | Initialize archai in your project (smart — handles existing setups) | | archai update | Update agents/templates with smart file comparison | | archai generate | Generate specialist agents from your config | | archai setup-project | Interactive wizard for project description | | archai setup-config | Interactive wizard for config, commands, permissions | | archai doctor | Validate your setup | | archai rollback | Restore from automatic backup | | archai cleanup | Remove deprecated files and old backups | | archai setup | Auto-configure git and MCP integrations | | archai knowledge create | Create a shared knowledge group | | archai knowledge join | Link project to a knowledge group | | archai knowledge leave | Unlink project from a knowledge group | | archai knowledge list | List all knowledge groups | | archai knowledge sync | Sync knowledge group with git remote | | archai knowledge info | Show knowledge group status | | archai uninstall | Remove archai from your project |

All commands support --dry-run to preview changes and -y for non-interactive CI mode.

Key flags

archai init --skip-wizard    # Use detected defaults
archai init --force          # Re-initialize with file comparison
archai update --all          # Force update all files
archai rollback --list       # Show available backups
archai cleanup --all         # Remove deprecated files + prune backups

Permission Presets

archai configures Claude Code permissions via .claude/settings.local.json:

| Preset | Description | |--------|-------------| | Permissive (default) | Allows most operations. Blocks destructive actions: rm -rf, git push --force, sudo, credential access, database drops. | | Strict | Read-only + controlled writes. No network, no push, no publish. Good for production environments. | | Custom | Define your own allow/deny lists via the wizard. |

Project Structure

your-project/
├── .claude/
│   ├── agents/          # Core + specialist agent definitions
│   ├── plans/           # Approved implementation plans
│   ├── state/           # Working state (gitignored)
│   └── version.json     # Version tracking for smart updates
├── .knowledge/          # Persistent knowledge base (decisions, constraints, patterns, learnings)
├── .tasks/              # Task inbox, epics, review, done
├── archai.config.md     # Project configuration
├── CLAUDE.md            # Agentic behavior guidelines (auto-generated)
└── PROMPTS.md           # Quick reference for all prompts

Requirements

• Node.js 18+
• Claude Code CLI — claude.ai/code

Troubleshooting

Agent not following instructions? Make sure agent file content is being passed and output locations are specified.

Planning keeps iterating? After 4 iterations, it stops automatically. If requirements are unclear, it escalates to you.

Implementation failing? After 5 fix attempts on the same step, it reports BLOCKED and stops. Check if the plan was specific enough.

Tests too shallow? Verify tdd-designer used concrete values and covered edge cases, not just happy paths.

License

MIT

Contributing

Contributions welcome! Join the Discord to discuss ideas.