Project Moose

Visual AI Agent Orchestration Platform

A canvas-based workspace where AI agents spawn, delegate, collaborate, and complete tasks — all in real-time.

Caution

Project Moose is under active development and not yet ready for general use. There are no published releases, no install packages, and no CI/CD pipeline. APIs and configuration may change without notice. If you're interested, star the repo and check back soon.

This project is 100% AI-coded — built entirely through conversational AI pair programming using Claude Code. Every line of code, every SVG, every CSS animation was generated by AI with human creative direction.

---

What is Project Moose?

Project Moose turns AI coding agents into a visual, collaborative workforce. Instead of chatting with a single AI assistant, you orchestrate a hierarchy of specialized agents on an interactive canvas — each with their own role, model, tools, and task list.

Think of it as a visual IDE meets agent swarm: you assign a task to a Bull Moose (orchestrator), it spawns Junior Moose agents to handle subtasks, which in turn spawn Deer (leaf workers) to do the actual coding, file editing, and research. You watch the entire operation unfold on a node-based canvas in real-time.

Key Features

• Canvas Workspace — Drag-and-drop node graph where each agent is a visual node with live state indicators (idle, working, spawning, error, question)
• Hierarchical Agent Spawning — Orchestrator agents automatically decompose tasks and spawn child agents, forming a tree of delegation
• Agent Folders — Organize agent definitions into switchable folders (e.g., "Default", "Moose Herd") with per-folder configurations
• Tool Scoping — Fine-grained control over which tools each agent can access, with 8 built-in tool groups (read, edit, command, browser, task, planning, interaction, skills)
• Skills System — Browsable skill registry with install/uninstall support, extending agent capabilities
• Real-Time Todo Tracking — Each agent displays a task badge on its canvas node; click to see a collapsible todo list with progress bars
• Configurable Agent Definitions — Define agent roles, system prompts, models, tools, spawn limits, and idle timeouts via JSON config
• Multi-Model Support — Each agent can use a different LLM (local via LM Studio, or cloud providers like OpenAI, Anthropic, Google)
• Force-Directed Layout — Nodes automatically repel each other to prevent overlap, with smooth redistribute-on-spawn
• Liquid Spawn Animations — New agents emerge with a morphing blob animation, colored glow rings, and ripple effects
• Agent Communication — Parent-child message passing for questions, scope requests, and answers
• Context Usage Rings — Visual ring around each node showing how much of the agent's context window is consumed
• Task Completion Detection — Agents glow green on task completion; todos auto-complete when leaf agents finish
• GC Warning System — Idle agents get countdown warnings before automatic cleanup

The Agent Hierarchy

Bull Moose (Orchestrator)
├── Junior Moose (Sub-orchestrator)
│   ├── Deer (Leaf worker — writes code, edits files)
│   ├── Smart Moose (Research & analysis)
│   └── Debug Moose (Debugging specialist)
├── Scout Moose (Reconnaissance & exploration)
└── Trail Moose (Path planning & architecture)

Each level has different capabilities:

• Orchestrators can spawn children and manage todo lists
• Leaf agents execute tasks directly (file edits, code generation, research)
• All agents report progress back up the hierarchy

---

Getting Started

Prerequisites

• Bun (v1.1+)
• An LLM provider (e.g., LM Studio for local models, or API keys for cloud providers)

Installation

# Clone the repository
git clone https://github.com/prob32/projectmoose.git
cd projectmoose

# Install dependencies
bun install

# Start the dev server (frontend :3000 + backend :4096)
bun run dev

Then open http://localhost:3000 in your browser.

Configuration

Agent definitions are organized into folders in ~/.config/opencode/moose-agents.json:

{
  "activeFolder": "default",
  "folders": [
    {
      "id": "default",
      "name": "Default",
      "description": "Traditional dev agents — architect, code, ask, debug, review, orchestrate",
      "icon": "terminal",
      "color": "#64b5f6",
      "agents": [
        {
          "id": "architect",
          "name": "Architect",
          "description": "Plan and design before implementation",
          "color": "#FF9800",
          "prompt": "You are an experienced technical leader...",
          "role": "orchestrator",
          "model": {
            "providerID": "openrouter",
            "modelID": "anthropic/claude-sonnet-4"
          },
          "permissionMode": "plan",
          "thinking": { "effort": "none" },
          "tools": {
            "mode": "scoped",
            "allow": ["read", "browser", "planning", "interaction", "skills", "task"]
          },
          "spawnable": {
            "agents": ["coder", "ask", "debugger"],
            "limit": "auto"
          },
          "idle_timeout": 0,
          "order": 0
        },
        {
          "id": "coder",
          "name": "Coder",
          "description": "Write, modify, and refactor code",
          "color": "#4CAF50",
          "prompt": "You are a highly skilled software engineer...",
          "role": "coder",
          "model": {
            "providerID": "openrouter",
            "modelID": "openai/gpt-5.2-codex"
          },
          "permissionMode": "build",
          "tools": {
            "mode": "scoped",
            "allow": ["read", "edit", "command", "planning", "interaction", "skills", "browser"]
          },
          "skills": ["frontend-design"],
          "idle_timeout": 90,
          "order": 1
        }
      ]
    }
  ]
}

Agent Definition Fields

Field	Type	Required	Description
id	string	yes	Unique identifier within the folder
name	string	yes	Display name
description	string	no	Short description shown in sidebar
color	string	yes	Hex color (#RRGGBB) for canvas node
prompt	string	yes	System prompt defining agent behavior
role	string	no	Semantic role (e.g., orchestrator, coder, researcher, debugger)
model	{ providerID, modelID }	no	LLM model override (inherits parent's model if omitted)
permissionMode	"build" | "plan"	no	build = full edit access, plan = read-only (default: build)
thinking	{ budget?, effort? }	no	Extended thinking config
tools	{ mode, allow?, deny? }	no	Tool scoping — see below
skills	string[]	no	Specific skills this agent can load (e.g., ["frontend-design", "commit"])
mcp	{ servers?, deny? }	no	MCP server access control
spawnable	{ agents[], limit }	no	Which child agents this agent can spawn (makes it an orchestrator)
idle_timeout	number	no	Seconds before GC cleanup (0 = never, default: 120)
order	number	no	Sort order in sidebar (default: 0)

Tool Scoping

tools.mode controls how tools are granted:

• "all" (default) — agent has all tools, minus any in tools.deny
• "scoped" — agent only has tools from groups listed in tools.allow

Available tool groups: read, edit, command, browser, task, planning, interaction, skills

Skills vs Tool Groups

• tools.allow: ["skills"] grants the agent the ability to invoke skills (the skill tool)
• skills: ["frontend-design"] controls which specific skills the agent can load

Both are needed for an agent to use a specific skill.

Default agent presets are seeded on first run. Switch between folders using the sidebar folder switcher.

---

Architecture

Project Moose is built as a layer on top of OpenCode, the open-source AI coding agent:

┌───────────────────────────────────────────────────┐
│  Frontend (SolidJS :3000)                         │
│  ├── Agent Canvas (nodes, connections, SVG)       │
│  ├── Sidebar (folders, agent list, drag-reorder)  │
│  ├── Agent Chat Panel (per-agent messages)        │
│  ├── Todo Panel (collapsible task lists)          │
│  └── Canvas Controls (zoom, pan, minimap)         │
├───────────────────────────────────────────────────┤
│  Backend (Bun + Hono :4096)                       │
│  ├── Agent Definition CRUD  → moose-agents.json   │
│  ├── Agent Instances        → SQLite (Drizzle)    │
│  ├── Agent Bridge           → translateMooseToAgent│
│  ├── Spawn Validation       → isSpawnAllowed()    │
│  ├── Layout Engine          → force-directed      │
│  ├── GC + Communication     → idle timeouts, msgs │
│  ├── Task Tool              → spawn + delegate    │
│  └── SSE Events (6 types)   → real-time sync      │
├───────────────────────────────────────────────────┤
│  OpenCode Core                                    │
│  ├── LLM Provider Abstraction                     │
│  ├── Tool System (8 groups, scoped permissions)   │
│  ├── Session & Message Storage                    │
│  ├── MCP Server Integration                       │
│  └── Permission System                            │
└───────────────────────────────────────────────────┘

Moose Agent Modules (v0.3.1)

The agent system is organized into focused modules under packages/opencode/src/agent/moose/:

Module	Responsibility
schema.ts	Zod schemas — single source of truth for all types
definition.ts	Agent/folder CRUD and config file management
instance.ts	Runtime instances — SQLite persistence via Drizzle
layout.ts	Force-directed layout and arc redistribution
spawn.ts	Spawn validation, limits, orchestrator detection
communication.ts	Parent-child messaging with direction validation
events.ts	6 BusEvent types for SSE streaming
gc.ts	Garbage collection with idle timeouts
presets/	Default and Moose Herd folder presets

See docs/moose-architecture.md for the full architecture reference.

Tech Stack

Layer	Technology
Frontend	SolidJS, Tailwind CSS, Canvas SVG
Backend	Bun, Hono, SQLite (Drizzle ORM), Zod
LLM Integration	OpenCode provider system (LM Studio, OpenAI, Anthropic, Google, etc.)
Real-time	Server-Sent Events (SSE)
State Management	SolidJS stores + reactive signals

---

Roadmap

• Canvas workspace with agent nodes
• Hierarchical agent spawning and delegation
• Real-time todo tracking with canvas badges
• Liquid spawn animations
• Force-directed node layout
• Agent communication (questions, scope requests)
• Task completion detection and auto-complete
• Group Chat — lasso-select multiple agents into a shared conversation
• Agent folders and presets
• Canvas zoom, pan, and minimap controls
• Skills system (browsable registry with install/uninstall)
• Tool scoping (8 groups with allow/deny lists)
• Modular agent architecture (v0.3.1 refactor)
• CodeGraph integration (semantic code graph explorer + MCP)
• Export/import workspace configurations
• Mobile-friendly remote control interface

---

Built On

Project Moose is built on OpenCode — the open-source AI coding agent. OpenCode provides the core LLM integration, tool system, session management, and permission framework that Moose extends with visual orchestration.

---

License

MIT

---

_{Built with determination by moose, for moose.}