Ploomy

Ploomy is a daemon that monitors GitHub Issues and automatically generates implementation plans using multiple AI models (Claude + Codex) working in coordination.

How It Works

1. Issue Detection - Monitors all repositories accessible to the GitHub App for Issues with a configured label (default: plan-request)
2. Questioning Phase - Claude Opus 4.6 analyzes the Issue, explores the codebase, and asks clarifying questions via Issue comments until all ambiguities are resolved
3. Drafting Phase - Once questions are resolved, Claude generates a detailed implementation plan (plan.md)
4. Review Phase - Codex CLI reviews the draft plan and suggests improvements
5. Finalization Phase - Claude incorporates review feedback (with autonomous triage), producing the final plan
6. Delivery - The final plan.md is pushed to a branch (ploomy/issue-{number}) in the target repository and a summary is posted on the Issue

Tech Stack

• Language: TypeScript (ES2022, Node16 modules)
• Runtime: Node.js >= 18
• GitHub API: Octokit (GitHub App authentication)
• State: SQLite (via better-sqlite3)
• Config: dotenv
• Plan generation: Claude CLI (claude -p) - read-only codebase exploration
• Plan review: Codex CLI (codex exec) - read-only review

Quick Start

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your GitHub App ID and private key path

# Build
npm run build

# Run
npm start

# Or run in development mode
npm run dev

Running as a daemon (macOS)

To run Ploomy as a native LaunchAgent (starts on login, restarts on failure), see deploy/README.md. From the project root:

chmod +x deploy/install-daemon.sh
./deploy/install-daemon.sh

Logs: ~/.ploomy/logs/daemon.log and ~/.ploomy/logs/daemon.err.log.

Configuration

All configuration uses the PLANNER_ prefix:

Variable	Description	Default
PLANNER_APP_ID	GitHub App ID	(required)
PLANNER_PRIVATE_KEY_PATH	Path to the App private key .pem file	(required*)
PLANNER_PRIVATE_KEY	App private key content (alternative to path)	(required*)
PLANNER_ISSUE_LABEL	Label that triggers plan generation	plan-request
PLANNER_POLL_INTERVAL	Polling interval in seconds	120
PLANNER_CLAUDE_MODEL	Claude model override	(claude CLI default)
PLANNER_CODEX_MODEL	Codex model override	(codex CLI default)
PLANNER_WORK_DIR	Working directory for cloned repos	~/.ploomy/repos
PLANNER_DB_PATH	SQLite database path	~/.ploomy/state.db
PLANNER_PLANS_DIR	Local plan file storage	~/.ploomy/plans
PLANNER_LOG_LEVEL	Log level (debug, info, warn, error)	info

* Either PLANNER_PRIVATE_KEY_PATH or PLANNER_PRIVATE_KEY must be set.

Monitored repositories are auto-discovered from the GitHub App installations. Install the App on the organizations/user accounts whose repositories you want to monitor.

Prerequisites

• A GitHub App with Issues read/write permissions, installed on target organizations/user accounts
• Claude Code CLI (claude) installed and authenticated
• Codex CLI (codex) installed and authenticated

State Transitions

PENDING → QUESTIONING → AWAITING_USER (loop until resolved) → DRAFTING → REVIEWING → FINALIZING → DONE
                                                                            ↕
                                                                   AWAITING_USER_FINAL

Any phase can transition to FAILED, which retries from PENDING on the next cycle.

License

MIT