PPM - Personal Project Manager

A mobile-first web IDE with AI chat, terminal, git, database tools, and file explorer — all in one browser tab.

Quick Start

Binary (no dependencies)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/hienlh/ppm/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/hienlh/ppm/main/scripts/install.ps1 | iex

Downloads the latest binary, adds to PATH, and shows next steps. To upgrade, run the same command again.

Via Bun

# 1. Install Bun (if you don't have it)
curl -fsSL https://bun.sh/install | bash

# 2. Run directly (no install needed)
bunx @hienlh/ppm start

# Or install globally
bun add -g @hienlh/ppm
ppm start

Note: The bunx/bun method requires Bun runtime. The binary install method has no dependencies.

On first run, PPM walks you through interactive setup: port, auth password, project scan directory, and AI settings. Config is stored in ~/.ppm/ppm.db (SQLite).

After setup, open the URL shown in terminal and enter your access password.

What You Get

• AI Chat — Claude AI with tool execution, file attachments, streaming, session history, slash commands
• Terminal — Full PTY terminal (xterm.js), multiple sessions per project
• File Explorer — Browse, edit, create, delete files with Monaco editor
• Git — Status, diff, commit, push/pull, branching, merge, rebase, commit graph
• Database — SQLite + PostgreSQL viewer with query editor, data grid, cell editing
• Notifications — Web Push + Telegram bot integration
• Remote Access — Cloudflare tunnel for public URL sharing (--share flag)
• Command Palette — Fuzzy search for commands, files, tables (Shift+Shift or F1)
• PWA — Installable as a progressive web app
• Mobile-First — Responsive UI with bottom sheets and touch optimization

CLI

# Server
ppm start                  # Start (background daemon, default port 3210)
ppm start -f               # Foreground mode (for debugging)
ppm start --share          # Start + Cloudflare tunnel for public URL
ppm start -p 4000          # Custom port
ppm stop                   # Stop daemon
ppm restart                # Restart
ppm status                 # Show status
ppm open                   # Open in browser
ppm logs -f                # Tail logs

# Projects
ppm projects list
ppm projects add my-app /path/to/my-app
ppm projects remove my-app

# Git
ppm git status
ppm git log
ppm git commit -m "message"
ppm git push

# Database
ppm db connections         # List DB connections
ppm db query my-db "SELECT * FROM users LIMIT 10"

# Config
ppm config get port
ppm config set port 4000

# Chat (CLI mode)
ppm chat

# Other
ppm init                   # Re-run setup wizard
ppm report                 # File bug report on GitHub

Non-Interactive / AI Agent Setup

For scripts, CI environments, or AI agents that cannot interact with prompts:

# Step 1: Init without any prompts (uses defaults, auto-generates password)
bunx @hienlh/ppm init -y

# Step 2: Start with Cloudflare tunnel in foreground
bunx @hienlh/ppm start -f --share

The -y flag skips all prompts and applies these defaults:

• Port: 3210
• Scan directory: $HOME
• Auth: enabled, password auto-generated (printed at end of init output)
• AI model: claude-sonnet-4-6

Override any default with flags:

bunx @hienlh/ppm init -y \
  --port 3210 \
  --password "your-password" \
  --scan /path/to/projects \
  --share

Once running, the Cloudflare public URL is printed to stdout — parse it to share with users.

Use with Claude Code

Install the PPM skill so Claude Code (and other compatible AI agents) can control PPM via its CLI, HTTP API, and SQLite config DB:

ppm export skill --install
# Installs to ~/.claude/skills/ppm/ (use --scope project for per-project install).

Then in Claude Code: /ppm list my projects → Claude invokes ppm projects list automatically. Re-run any time to refresh (existing files are backed up with a .bak-<timestamp> suffix). Requires PPM v0.13.0+.

Requirements

• Bun v1.3.6+ (install)
• Git v2.0+ (for git features)
• Claude Code authenticated (claude CLI logged in) — for AI chat

Development

git clone https://github.com/hienlh/ppm.git
cd ppm && bun install

bun dev:server    # Backend (port 8081, uses dev profile)
bun dev:web       # Vite frontend (port 5173)
bun test          # Run tests
bun run build     # Build frontend + CLI binary -> dist/ppm

Dev uses a separate SQLite database (ppm.dev.db) from production (ppm.db), both in ~/.ppm/.

For architecture details, API reference, and contribution guidelines, see the docs directory.

Documentation

| Doc | Purpose | |-----|---------| | Project Overview | Goals, features, decisions | | System Architecture | Layers, protocols, data flows | | Codebase Summary | Module responsibilities | | Code Standards | Conventions and patterns | | Deployment Guide | Installation, config, troubleshooting | | Design Guidelines | UI framework, colors, components | | Project Roadmap | Status and plans |

Known Gotchas

• SDK .env poisoning: Projects with ANTHROPIC_API_KEY in .env can break SDK tool execution. PPM neutralizes these vars automatically.
• Windows: SDK uses CLI fallback (claude -p) due to Bun pipe buffering issues. Ensure claude is in PATH.

Issues: GitHub