"The Loa are pragmatic entities... They're not worshipped for salvation—they're worked with for practical results."
Loa is an agent-driven development framework for Claude Code (Anthropic's official CLI). It adds 17 specialized AI agents, quality gates, persistent memory, and structured workflows on top of Claude Code. Works on macOS and Linux. Created by @janitooor at The Honey Jar.
In William Gibson's Sprawl trilogy (Neuromancer, Count Zero), Loa are AI entities that "ride" humans through neural interfaces — a metaphor Gibson adapted from Haitian Vodou via the anthropological work of Robert Tallant and (likely) Maya Deren. These agents don't replace you — they ride with you, channeling expertise through the interface. See docs/ecosystem-architecture.md for the full naming lineage.
Prerequisites: Claude Code (Anthropic's CLI for Claude), Git, jq, yq v4+. See INSTALLATION.md for full details.
# Install (one command, any existing repo — adds Loa as git submodule)
curl -fsSL https://raw.githubusercontent.com/0xHoneyJar/loa/main/.claude/scripts/mount-loa.sh | bash
# Or pin to a specific version
curl -fsSL https://raw.githubusercontent.com/0xHoneyJar/loa/main/.claude/scripts/mount-loa.sh | bash -s -- --tag v1.39.0
# Start Claude Code
claude
# These are slash commands typed inside Claude Code, not your terminal.
# 5 commands. Full development cycle.
/plan # Requirements -> Architecture -> Sprints
/build # Implement the current sprint
/review # Code review + security audit
/ship # Deploy and archiveAfter install, you should see .loa/ (submodule), .claude/ (symlinks), grimoires/loa/, and .loa.config.yaml in your repo. Run /loa doctor inside Claude Code to verify everything is healthy.
Three ways to install: Submodule mode (default, recommended for existing projects), clone template (new projects), or vendored mode (legacy — no symlink support). See INSTALLATION.md for the full comparison.
Not sure where you are? /loa shows your current state, health, and next step.
New project? See INSTALLATION.md to clone the template. For detailed setup, optional tools (beads, ck), and configuration, start there too.
The problem: AI coding assistants are powerful but unstructured. Without guardrails, you get ad-hoc code with no traceability, no security review, and no memory across sessions.
The solution: Loa adds structure without ceremony. Each phase produces a traceable artifact (PRD, SDD, Sprint Plan, Code, Review, Audit) using specialized AI agents. Your code gets reviewed by a Tech Lead agent and a Security Auditor agent before it ships.
Key differentiators:
- Multi-agent orchestration: 17 specialized skills, not one general-purpose prompt
- Quality gates: Two-phase review (code + security) prevents unreviewed code from shipping
- Session persistence: Beads task graph + persistent memory survive context clears
- Adversarial review: Flatline Protocol uses cross-model dissent (Opus + GPT-5.2) for planning QA
- Zero-config start: Mount onto any repo, type
/plan, start building
| Command | What It Does |
|---|---|
/loa |
Where am I? What's next? |
/plan |
Plan your project (requirements -> architecture -> sprints) |
/build |
Build the current sprint |
/review |
Review and audit your work |
/ship |
Deploy and archive |
Each Golden Path command auto-detects context and does the right thing. No arguments needed. First run of /plan takes 2-5 minutes and creates grimoires/loa/prd.md.
If something isn't working, start here:
/loa doctor # Full system health check with structured error codes
/loa doctor --json # CI-friendly outputFor fine-grained control, use the underlying commands directly:
| Phase | Command | Output |
|---|---|---|
| 1 | /plan-and-analyze |
Product Requirements (PRD) |
| 2 | /architect |
Software Design (SDD) |
| 3 | /sprint-plan |
Sprint Plan |
| 4 | /implement sprint-N |
Code + Tests |
| 5 | /review-sprint sprint-N |
Approval or Feedback |
| 5.5 | /audit-sprint sprint-N |
Security Approval |
| 6 | /deploy-production |
Infrastructure |
47 total commands. Type /loa for the Golden Path or see PROCESS.md for all commands.
Seventeen specialized skills that ride alongside you:
| Skill | Role |
|---|---|
| discovering-requirements | Senior Product Manager |
| designing-architecture | Software Architect |
| planning-sprints | Technical PM |
| implementing-tasks | Senior Engineer |
| reviewing-code | Tech Lead |
| auditing-security | Security Auditor |
| deploying-infrastructure | DevOps Architect |
| translating-for-executives | Developer Relations |
| enhancing-prompts | Prompt Engineer |
| run-mode | Autonomous Executor |
| run-bridge | Excellence Loop Operator |
| simstim-workflow | HITL Orchestrator |
| riding-codebase | Codebase Analyst |
| continuous-learning | Learning Extractor |
| flatline-knowledge | Knowledge Retriever |
| browsing-constructs | Construct Browser |
| mounting-framework | Framework Installer |
| autonomous-agent | Autonomous Agent |
Loa uses a three-zone model inspired by AWS Projen and Google's ADK:
| Zone | Path | Description |
|---|---|---|
| System | .claude/ |
Framework-managed (never edit directly) |
| State | grimoires/, .beads/ |
Project memory |
| App | src/, lib/ |
Your code |
Key principle: Customize via .claude/overrides/ and .loa.config.yaml, not by editing .claude/ directly.
| Feature | Description | Documentation |
|---|---|---|
| Golden Path | 5 zero-arg commands for 90% of users | CLAUDE.md |
Error Codes & /loa doctor |
Structured LOA-E001+ codes with fix suggestions | Data |
| Flatline Protocol | Multi-model adversarial review (Opus + GPT-5.2) | Protocol |
| Adversarial Dissent | Cross-model challenge during review and audit | CHANGELOG.md |
| Cross-Repo Patterns | 25 reusable patterns in 5 library modules | Lib |
| DRY Constraint Registry | Single-source constraint generation from JSON | Data |
| Beads-First Architecture | Persistent task tracking (recommended; required for /run mode, works without for interactive use) |
CLAUDE.md |
| Persistent Memory | Session-spanning observations with progressive disclosure | Scripts |
| Input Guardrails | PII filtering, injection detection, danger levels | Protocol |
| Portable Persistence | WAL-based persistence with circuit breakers | Lib |
| Cross-Platform Compat | Shell scripting protocol for macOS + Linux | Scripts |
| Prompt Enhancement | PTCF-based prompt analysis and improvement | CHANGELOG.md |
| Run Mode | Autonomous sprint execution with draft PRs | CLAUDE.md |
| Run Bridge | Iterative excellence loop with Bridgebuilder review and flatline detection | CLAUDE.md |
| Lore Knowledge Base | Cultural/philosophical context for agent skills (Mibera + Neuromancer) | Data |
| Vision Registry | Speculative insight capture from bridge iterations | Visions |
| Grounded Truth | Checksum-verified codebase summaries extending /ride |
Script |
| Simstim | HITL accelerated development (PRD -> SDD -> Sprint -> Run) | Command |
| Compound Learning | Cross-session pattern detection + feedback loop | CHANGELOG.md |
| Construct Manifest Standard | Event-driven contracts with schema validation | CHANGELOG.md |
| Quality Gates | Two-phase review: Tech Lead + Security Auditor | PROCESS.md |
| Loa Constructs | Commercial skill packs from registry | INSTALLATION.md |
| Sprint Ledger | Global sprint numbering across cycles | CLAUDE.md |
| beads_rust | Persistent task graph across sessions | INSTALLATION.md |
| ck Search | Semantic code search | INSTALLATION.md |
| Document | Purpose |
|---|---|
| INSTALLATION.md | Setup, prerequisites, configuration, updates |
| PROCESS.md | Complete workflow, agents, commands, protocols |
| CLAUDE.md | Technical reference for Claude Code |
| CHANGELOG.md | Version history |
AGPL-3.0 — Use, modify, distribute freely. Network service deployments must release source code.
Commercial licenses are available for organizations that wish to use Loa without AGPL obligations.
Ridden with Loa