🐮 Moo Tasks

Agentic Task Orchestration & Management Engine built for AI coding agents (Claude Code, Cursor, Windsurf, Antigravity, Copilot) and human-in-the-loop pair programming.

Quick Start • Agent Setup • Agent Protocol • Architecture • MCP Tools

🌟 Why Moo Tasks?

Standard AI coding agents often suffer from:

1. Scope Drift: Wandering away from original user intent into endless low-value refactorings.

2. Over-Planning: Generating 40 shallow tasks without executing any of them.

3. Looping / Thrashing: Attempting the same failed fix repeatedly without stopping.

4. Unverifiable Work: Claiming code is complete without running tests or producing evidence.

5. Re-Debating Decisions: Re-arguing settled architectural choices on every context reset.

Moo Tasks solves this by providing a local SQLite engine (WAL mode), a rich real-time Web UI, and a Model Context Protocol (MCP) server that enforces strict enterprise invariants at runtime.

Related MCP server: agentloop

✨ Key Capabilities & Feature Matrix

🎯 1. Goals & Scope Control

• Verbatim Human Prompts: Sits above tasks, preserving the exact original user request.

• Goal Coverage & Loose Ends: Live metrics on task completion percentage and lingering open tasks.

• Scope Drift Detection: Automatically identifies and flags orphan tasks with no linked goal.

• Goal Open Caps: Hard cap on maximum open tasks per goal (default: 10), preventing agents from over-planning.

• Cascade Operations: Atomically drop, kill, or reopen all tasks under a goal with mandatory reasons.

📋 2. Task Lifecycle & DAG Dependencies

• Subtask Nesting Constraint: Exactly 1 level of subtasks under a parent task.

• Finite State Machine: todo, doing, blocked-on-dependency, waiting-on-human, done, dropped.

• DAG Dependency Graph: Automatic cycle detection and automatic unblocking of downstream tasks.

• Parent Closure Guard: Prevents closing parent tasks while any subtask remains open.

• Status Undo & History: Roll back accidental state transitions using full transition audit history.

🛡️ 3. Completion, Verification & Proof of Work

• Acceptance Criteria: Mandatory criteria written in Markdown before work starts.

• Evidence Requirement: Closing a task requires verifiable proof (commands run, stdout output, test proofs).

• Two-Phase Verification: Distinguishes agent_completed from human verified_done.

• Rejection with Reason: Humans or peer agents can reject completed work with feedback; the task reverts to todo and increments the reopen counter.

🙋 4. Human Collaboration & Blocking

• Waiting-on-Human Queue: Agents pause blockers with attached questions (clarification, approval, credential, decision).

• Reactive Resume: Answering a question via Web UI or MCP automatically transitions the task back into the ready queue without agent restarts.

• Dedicated Human Inbox: Real-time queue of everything needing human attention.

🔍 5. Discovered Work

• Mid-Task Work Capture: Capture new work found mid-flight without relinquishing current task claim.

• Must-Fix vs Deferred: Mark as must-fix-now (inserted as blocker) or deferred (backlog pile).

🤖 6. Ownership, Concurrency & Leases

• Exclusive Task Claims: Leases with automatic timeout (default 5 minutes) when agents go silent.

• Heartbeat Mechanism: Extend leases during long-running tasks.

• Agent Concurrency Limits: Cap simultaneous tasks held per agent (default: 1).

• File Touch Conflict Warnings: Declared files are checked for overlaps against other active claims.

🔄 7. Stall & Thrash Detection

• Attempt Counter: Incremented on each claim/attempt.

• Auto-Escalation: After $N$ attempts (default: 3), automatically pauses task to waiting-on-human instead of endless looping.

• Time-in-State Tracking: Audits time spent in doing and detects repeated reopens.

🏛️ 8. Settled Architectural Decisions (ADR)

• Project-Level Record: Preserves choices and rationales that outlive tasks.

• Pre-Planning Consultation: Agents read settled decisions before planning.

• Supersede Support: Cleanly update and link superseded decisions with mandatory reasons.

🚀 Quick Start & Installation

Option A: Install Globally (Recommended for moo command)

Install moo-tasks globally to access the short moo command anywhere:

npm install -g moo-tasks
# or: pnpm add -g moo-tasks | bun add -g moo-tasks

Once installed, you can use moo directly:

moo init       # Initialize .moo workspace in current project
moo start      # Launch real-time Web UI (http://127.0.0.1:4242)
moo ws         # List registered global workspaces
moo status     # Show Where-Did-I-Leave-Off context
moo search     # Full-text SQLite search

💡 Note on moo vs npx:

• Bare moo <command> works when installed globally via npm install -g moo-tasks.

• If running without global installation, use npx moo-tasks <command> (do not use npx moo, as moo on npm registry is an unrelated package).

• If moo: command not found appears after global install, ensure npm's global bin directory is in your $PATH:

  export PATH="$(npm prefix -g)/bin:$PATH"

Option B: On-Demand via npx moo-tasks

Run directly without global installation:

1. Initialize Workspace & Agent Protocols

Run in your project root:

npx moo-tasks init

This:

• Initializes .moo/tasks.db SQLite database with WAL mode.

• Generates AGENTS.md, CLAUDE.md, .cursorrules, and .windsurfrules.

2. Launch Local Web UI

npx moo-tasks start

Open http://127.0.0.1:4242 in your browser.

To access the Web UI from another device or tablet on your local network (LAN):

npx moo-tasks start --lan
# Automatically logs: http://192.168.x.x:4242/

🔌 Agent & MCP Setup

One-Command Multi-Agent Installer

# Configure all detected agent IDEs at once:
npx moo-tasks install all

# Or configure specific clients:
npx moo-tasks install claude       # Updates ~/.claude.json
npx moo-tasks install cursor       # Generates .cursor/mcp.json
npx moo-tasks install windsurf     # Updates ~/.codeium/windsurf/mcp_config.json
npx moo-tasks install antigravity  # Generates .gemini/settings.json

Manual Configuration

{
  "mcpServers": {
    "moo-tasks": {
      "command": "npx",
      "args": ["moo-tasks", "mcp"]
    }
  }
}

🤖 Mandatory Agent Protocol

All AI coding agents are instructed to follow this 6-step lifecycle:

1. SESSION RESUME  → Call moo_session_resume() & moo_list_decisions()
2. ANCHOR GOAL     → Call moo_create_goal(title, verbatimPrompt)
3. PLAN & CRITERIA → Call moo_create_task() with markdown criteria BEFORE code
4. EXCLUSIVE CLAIM → Call moo_claim_task(taskId, agentId, sessionId)
5. IMPLEMENTATION  → If blocked, call moo_ask_human() or link blockers
6. VERIFIED PROOF  → Call moo_complete_task() with test proof & output snippet
7. ADR RECORD      → Call moo_record_decision() for architectural choices

🛠️ MCP Tool Reference

🏛️ Architecture & Clean Code

src/
├── domain/                    # Pure Enterprise Domain Rules & Invariants
│   ├── types.ts              # Domain interfaces & value types
│   ├── errors.ts             # Domain-specific typed error classes
│   ├── dependency.ts         # DAG cycle detector & unblocked evaluator
│   ├── conflict.ts           # File touch overlap conflict detector
│   └── similarity.ts         # Duplicate task similarity detector
│
├── infrastructure/            # Persistence & External Integrations
│   ├── db/database.ts        # SQLite manager (WAL mode, busy timeout)
│   ├── db/migrations.ts      # Schema DDL and versioning
│   ├── git/git-context.ts    # Git branch, commit, dirty status extractor
│   └── repositories/         # SQLite Repository Implementations
│
├── services/                  # Application Services (Use Cases)
│   ├── goal-service.ts        # Goal lifecycle & cap enforcement
│   ├── task-lifecycle-service.ts # State machine, ready queue, undo
│   ├── claim-service.ts       # Exclusive claims, leases, dead-agent timeout
│   ├── verification-service.ts# Proof of work & two-phase verification
│   ├── human-collab-service.ts# Human Q&A queue & reactive resume
│   ├── discovered-work-service.ts # Mid-flight discovered work
│   ├── decision-service.ts    # ADR logs & supersede linking
│   ├── duplicate-merge-service.ts # Idempotency & task merging
│   ├── session-service.ts     # Where-did-I-leave-off session resume
│   ├── housekeeping-service.ts# Archiving & multi-format export
│   └── index.ts               # Dependency Injection Container
│
├── mcp/                       # Model Context Protocol Stdio Server
├── server/                    # Fastify HTTP + Server-Sent Events (SSE) Engine
├── cli/                       # CLI Commands (start, init, install, mcp)
└── ui/                        # Vanilla JS + Tailwind + Lucide Icons Web UI

🤝 Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for development setup, testing, and PR guidelines.

📄 License

This project is licensed under the MIT License.