Olly Molly

Your AI Development Team, Running Locally

Quick Start •
CLI Options •
Features •
How It Works •
Contributing

npm version

---

Olly Molly is a local-first AI development team manager. Assign tasks to AI agents (PM, Frontend, Backend, QA) and watch them work on your codebase—all from a beautiful kanban board interface.

Quick Start

``bash npx olly-molly`

That's it. Open http://localhost:1234 and start managing your AI team.

`Features`

- 🎯 Kanban Board — Drag-and-drop task management - 🤖 AI Agents — PM, Frontend Dev, Backend Dev, QA, DevOps, Bug Hunter - 💬 Natural Requests — Ask PM in plain language, get structured tickets - 🔒 Local-First — Everything runs on your machine - 🎨 Minimal Design — Clean, paper-like UI inspired by fontshare.com - 🌙 Dark Mode — Easy on the eyes

`AI Agents`

Olly Molly comes with 6 specialized AI agents, each designed for specific development tasks:

| Agent | Role | Description | |-------|------|-------------| | 👔 PM Agent | Project Manager | Creates tickets, assigns tasks, sets priorities, tracks progress | | 🎨 Frontend Developer | FE_DEV | React/Next.js UI development, responsive design, API integration | | ⚙️ Backend Developer | BACKEND_DEV | REST APIs, database design, server-side logic, testing | | 🔍 QA Engineer | QA | Automated testing with Chrome DevTools/Playwright MCP, bug reporting | | 🚀 DevOps Engineer | DEVOPS | CI/CD pipelines, deployment, infrastructure, monitoring | | 🐛 Bug Hunter | BUG_HUNTER | Full-stack debugging, error analysis, regression testing |

`$3`

Create a new file in agents/ directory:

`typescript // agents/my-agent.ts import type { AgentDefinition } from './types';

export const myAgent: AgentDefinition = { id: 'my-agent-001', role: 'MY_ROLE', name: 'My Custom Agent', avatar: '🤖', profile_image: null, system_prompt:Your agent's system prompt here..., is_default: 1, can_generate_images: 0, can_log_screenshots: 0, };`

Then add it to agents/index.ts:

`typescript import { myAgent } from './my-agent';

export const DEFAULT_AGENTS: AgentDefinition[] = [ // ... existing agents myAgent, ];`

`How It Works`

`┌─────────────────────────────────────────────────────────┐ │ Olly Molly │ ├─────────────────────────────────────────────────────────┤ │ │ │ You ──▶ PM Agent ──▶ Creates Tickets │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ TODO │ PROGRESS │ REVIEW │ DONE │ HOLD │ │ │ │ 📋 │ 🔄 │ 👀 │ ✅ │ ⏸️ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Agents (FE/BE/QA) work on assigned tickets │ │ │ │ │ ▼ │ │ Code changes in YOUR local project │ │ │ └─────────────────────────────────────────────────────────┘`

`Setup`

`$3`

- Node.js 18+ - One of the following CLI tools: Codex CLI, OpenCode, or Claude CLI

`$3`

`bash npx olly-molly`

On macOS (arm64/x64) and Windows x64, npx olly-mollywill use prebuilt bundles from GitHub Releases when available. Asset naming:

`olly-molly-darwin-arm64.tar.gz olly-molly-darwin-x64.tar.gz olly-molly-win32-x64.tar.gz`

`$3`

`bash olly-molly [options]`

#### Server Settings

| Flag | Short | Default | Description | |------|-------|---------|-------------| |--port | -p | 1234| Server port | |--host | -H | localhost| Binding host | |--no-open | | | Disable auto browser open |

#### Data/Path Settings

| Flag | Short | Default | Description | |------|-------|---------|-------------| |--data-dir | -d | ~/.olly-molly| App data directory | |--db-path | | /db | Database path |

#### Development

| Flag | Short | Description | |------|-------|-------------| |--dev | | Run in development mode (next dev) | |--verbose | -v | Enable verbose logging |

#### Advanced Options

| Flag | Description | |------|-------------| |--reset| Reset all app data (with confirmation prompt) | |--export-db | Export database to tar.gz file | |--import-db | Import database from tar.gz file |

#### Info

| Flag | Short | Description | |------|-------|-------------| |--version | -V| Show version and exit | |--help | -h | Show help and exit |

#### Environment Variables

You can also configure Olly Molly using environment variables (CLI arguments take priority):

| Variable | Description | |----------|-------------| |OLLY_MOLLY_PORT| Server port | |OLLY_MOLLY_HOST| Binding host | |OLLY_MOLLY_DATA_DIR| App data directory | |OLLY_MOLLY_DB_PATH | Database path |

#### Examples

`bash

`Start with defaults (port 1234, auto-open browser)`


npx olly-molly
Use custom port

npx olly-molly -p 3000
Bind to all interfaces (for network access)

npx olly-molly --host 0.0.0.0
Run in development mode with verbose logging

npx olly-molly --dev -v
Disable auto browser open

npx olly-molly --no-open
Export database for backup

npx olly-molly --export-db backup.tar.gz
Import database from backup

npx olly-molly --import-db backup.tar.gz
Reset all app data

npx olly-molly --reset

$3

`bash npm install -g olly-molly olly-molly`

`$3`

`bash git clone https://github.com/ruucm/olly-molly.git cd olly-molly npm install npm run dev`

`$3`

To run AI agents, you need to install Codex CLI, OpenCode, or Claude CLI:

macOS (via Homebrew):`bash

`OpenCode`


brew install sst/tap/opencode
Codex CLI

npm install -g @openai/codex
Claude CLI

brew install anthropics/tap/claude-code

Windows:`bash

`OpenCode (via npm)`


npm install -g opencode-ai
Codex CLI (via npm)

npm install -g @openai/codex
Claude CLI (via npm)

npm install -g @anthropic-ai/claude-code


> Note: Windows npm packages may not be officially supported. If installation fails, consider using WSL (Windows Subsystem for Linux) with Homebrew.
Project Selection

1. Click "Select Project" in the header 2. Add your project path (e.g.,/Users/you/my-app) 3. AI agents will work within that directory

`Contributing`

We love contributions! Here's how you can help:

`$3`

- 🐛 Bug Reports — Found a bug? Open an issue - 💡 Feature Requests — Have an idea? Let's discuss - 🔧 Pull Requests — Code contributions are welcome - 📖 Documentation — Help improve our docs - 🎨 Design — UI/UX improvements

`$3`

`bash

`Clone the repo`


git clone https://github.com/ruucm/olly-molly.git
cd olly-molly
Install dependencies

npm install
Start development server

npm run dev
Open http://localhost:1234

$3

`bash scripts/build-prebuilt-macos.sh`

`bash npm version major|minor|patch npm publish`

`bash git push origin main`

`bash gh release create v0.2.21 \ dist/prebuilt/olly-molly-darwin-arm64.tar.gz \`

for windows:`bash powershell -ExecutionPolicy Bypass -File scripts/build-prebuilt-windows.ps1`

`bash gh release upload v0.2.21 dist/prebuilt/olly-molly-win32-x64.tar.gz --clobber`

`$3`

`olly-molly/ ├── agents/ # AI agent definitions │ ├── index.ts # Agent exports & DEFAULT_AGENTS │ ├── types.ts # AgentDefinition type │ ├── pm.ts # PM Agent │ ├── fe-dev.ts # Frontend Developer │ ├── be-dev.ts # Backend Developer │ ├── qa.ts # QA Engineer │ ├── devops.ts # DevOps Engineer │ └── bug-hunter.ts # Bug Hunter ├── app/ # Next.js app router │ ├── api/ # API routes │ ├── design-system/ # Design system docs │ └── page.tsx # Main dashboard ├── components/ # React components │ ├── kanban/ # Kanban board │ ├── ui/ # Reusable UI components │ └── ... ├── db/ # SQLite schemas └── lib/ # Utilities`

`$3`

- TypeScript for type safety - Functional components with hooks - CSS variables for theming - Minimal dependencies

`Tech Stack`

- Framework: Next.js 16 - UI: React 19, Tailwind CSS 4 - Database: TanStack DB (@tanstack/react-db) with IndexedDB persistence - Drag & Drop: dnd-kit - AI: Codex CLI / OpenCode / Claude CLI

`Troubleshooting`

`$3`

This is usually caused by IndexedDB lock. IndexedDB allows only one connection per database at a time, and if a previous browser session didn't close properly, the lock may persist.

Solutions: 1. Force quit browser — Completely close Chrome/browser and reopen 2. Hard refresh —Cmd+Shift+R (Mac) or Ctrl+Shift+R` (Windows)
3. Close duplicate tabs — Make sure only one tab has Olly Molly open
4. Clear site data — DevTools → Application → Storage → Clear site data

Why this happens:
- Browser crashed or was force-quit while the app was running
- Multiple tabs trying to access the same IndexedDB
- Browser extension interfering with IndexedDB

License

MIT © ruucm

---

_{Built with ❤️ for developers who love AI}

Olly Molly

Your AI Development Team, Running Locally

Quick Start •
CLI Options •
Features •
How It Works •
Contributing

npm version

---

Olly Molly is a local-first AI development team manager. Assign tasks to AI agents (PM, Frontend, Backend, QA) and watch them work on your codebase—all from a beautiful kanban board interface.

Quick Start

``bash npx olly-molly`

That's it. Open http://localhost:1234 and start managing your AI team.

`Features`

`AI Agents`

Olly Molly comes with 6 specialized AI agents, each designed for specific development tasks:

`$3`

Create a new file in agents/ directory:

`typescript // agents/my-agent.ts import type { AgentDefinition } from './types';

Then add it to agents/index.ts:

`typescript import { myAgent } from './my-agent';

export const DEFAULT_AGENTS: AgentDefinition[] = [ // ... existing agents myAgent, ];`

`How It Works`

`Setup`

`$3`

- Node.js 18+ - One of the following CLI tools: Codex CLI, OpenCode, or Claude CLI

`$3`

`bash npx olly-molly`

On macOS (arm64/x64) and Windows x64, npx olly-mollywill use prebuilt bundles from GitHub Releases when available. Asset naming:

`olly-molly-darwin-arm64.tar.gz olly-molly-darwin-x64.tar.gz olly-molly-win32-x64.tar.gz`

`$3`

`bash olly-molly [options]`

#### Server Settings

#### Data/Path Settings

| Flag | Short | Default | Description | |------|-------|---------|-------------| |--data-dir | -d | ~/.olly-molly| App data directory | |--db-path | | /db | Database path |

#### Development

| Flag | Short | Description | |------|-------|-------------| |--dev | | Run in development mode (next dev) | |--verbose | -v | Enable verbose logging |

#### Advanced Options

#### Info

| Flag | Short | Description | |------|-------|-------------| |--version | -V| Show version and exit | |--help | -h | Show help and exit |

#### Environment Variables

You can also configure Olly Molly using environment variables (CLI arguments take priority):

#### Examples

`bash

`Start with defaults (port 1234, auto-open browser)`


npx olly-molly
Use custom port

npx olly-molly -p 3000
Bind to all interfaces (for network access)

npx olly-molly --host 0.0.0.0
Run in development mode with verbose logging

npx olly-molly --dev -v
Disable auto browser open

npx olly-molly --no-open
Export database for backup

npx olly-molly --export-db backup.tar.gz
Import database from backup

npx olly-molly --import-db backup.tar.gz
Reset all app data

npx olly-molly --reset

$3

`bash npm install -g olly-molly olly-molly`

`$3`

`bash git clone https://github.com/ruucm/olly-molly.git cd olly-molly npm install npm run dev`

`$3`

To run AI agents, you need to install Codex CLI, OpenCode, or Claude CLI:

macOS (via Homebrew):`bash

`OpenCode`


brew install sst/tap/opencode
Codex CLI

npm install -g @openai/codex
Claude CLI

brew install anthropics/tap/claude-code

Windows:`bash

`OpenCode (via npm)`


npm install -g opencode-ai
Codex CLI (via npm)

npm install -g @openai/codex
Claude CLI (via npm)

npm install -g @anthropic-ai/claude-code


> Note: Windows npm packages may not be officially supported. If installation fails, consider using WSL (Windows Subsystem for Linux) with Homebrew.
Project Selection

1. Click "Select Project" in the header 2. Add your project path (e.g.,/Users/you/my-app) 3. AI agents will work within that directory

`Contributing`

We love contributions! Here's how you can help:

`$3`

`bash

`Clone the repo`


git clone https://github.com/ruucm/olly-molly.git
cd olly-molly
Install dependencies

npm install
Start development server

npm run dev
Open http://localhost:1234

$3

`bash scripts/build-prebuilt-macos.sh`

`bash npm version major|minor|patch npm publish`

`bash git push origin main`

`bash gh release create v0.2.21 \ dist/prebuilt/olly-molly-darwin-arm64.tar.gz \`

for windows:`bash powershell -ExecutionPolicy Bypass -File scripts/build-prebuilt-windows.ps1`

`bash gh release upload v0.2.21 dist/prebuilt/olly-molly-win32-x64.tar.gz --clobber`

`$3`

- TypeScript for type safety - Functional components with hooks - CSS variables for theming - Minimal dependencies

`Tech Stack`

- Framework: Next.js 16 - UI: React 19, Tailwind CSS 4 - Database: TanStack DB (@tanstack/react-db) with IndexedDB persistence - Drag & Drop: dnd-kit - AI: Codex CLI / OpenCode / Claude CLI

`Troubleshooting`

`$3`

This is usually caused by IndexedDB lock. IndexedDB allows only one connection per database at a time, and if a previous browser session didn't close properly, the lock may persist.

Why this happens:
- Browser crashed or was force-quit while the app was running
- Multiple tabs trying to access the same IndexedDB
- Browser extension interfering with IndexedDB

License

MIT © ruucm

---

_{Built with ❤️ for developers who love AI}