Olly Molly

Your AI Development Team, Running Locally

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

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

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

Adding Custom Agents

Create a new file in agents/ directory:

// 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:

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

Prerequisites

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

Run with npx (Recommended)

npx olly-molly

On macOS (arm64/x64) and Windows x64, npx olly-molly will 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

CLI Options

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`		`<data-dir>/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 <path>`	Export database to tar.gz file
`--import-db <path>`	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

# 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

Or install globally

npm install -g olly-molly
olly-molly

Development

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

AI CLI Tools (Required for Agent Execution)

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

macOS (via Homebrew):

# OpenCode
brew install sst/tap/opencode

# Codex CLI
npm install -g @openai/codex

# Claude CLI
brew install anthropics/tap/claude-code

Windows:

# 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

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

Contributing

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

Ways to Contribute

🐛 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

Development Setup

# 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

Releasing a New Version

npm version major|minor|patch (or edit package.json)

git push origin main

scripts/build-prebuilt-macos.sh
npm publish

gh release create v0.3.70 dist/prebuilt/olly-molly-darwin-arm64.tar.gz

for windows:

powershell -ExecutionPolicy Bypass -File scripts/build-prebuilt-windows.ps1

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

Project Structure

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

Code Style

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

App stuck on "Loading..."

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:

Force quit browser — Completely close Chrome/browser and reopen
Hard refresh — Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Close duplicate tabs — Make sure only one tab has Olly Molly open
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}

Name		Name	Last commit message	Last commit date
Latest commit History 445 Commits
agents		agents
app		app
bin		bin
components		components
db		db
docs		docs
lib		lib
pm2		pm2
public		public
scripts		scripts
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
app-icon.png		app-icon.png
env.example		env.example
eslint.config.mjs		eslint.config.mjs
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Olly Molly

Quick Start

Features

AI Agents

Adding Custom Agents

How It Works

Setup

Prerequisites

Run with npx (Recommended)

CLI Options

Server Settings

Data/Path Settings

Development

Advanced Options

Info

Environment Variables

Examples

Or install globally

Development

AI CLI Tools (Required for Agent Execution)

Project Selection

Contributing

Ways to Contribute

Development Setup

Releasing a New Version

Project Structure

Code Style

Tech Stack

Troubleshooting

App stuck on "Loading..."

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 92

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages