Procler

English | 日本語

A process manager where Claude Code is a first-class citizen.

Every command returns structured JSON. Every error includes a machine-readable code and a suggested fix. Built for the workflow where your AI assistant manages your dev environment.

Quick Start

uv tool install procler

procler define --name api --command "uvicorn main:app --port 8000"
procler start api
procler status api       # JSON with pid, uptime, linux_state
procler logs api --tail 20
procler stop api

Why Procler?

Modern development means juggling local servers, Docker containers, background workers, and database migrations. Procler gives you one tool to manage all of them — with JSON output that LLMs can parse, health checks that block dependent services, and recipes that automate multi-step workflows.

Features

Core — Process lifecycle with local and Docker execution contexts, log capture, PID tracking, Linux kernel state detection (/proc integration).

Orchestration — Groups with dependency-ordered startup (depends_on with healthy/log_ready conditions), multi-step recipes with dry-run preview, cron-scheduled processes, process replicas.

Monitoring — HTTP/TCP/command health probes, memory threshold auto-restart, ready_log_line regex matching, real-time WebSocket status and log streaming.

Developer Experience — JSON-native CLI, structured errors with error_code + suggestion, config variable substitution (${VAR}), Procfile import, systemd/Compose export, command snippets, Vue 3 web dashboard, Textual TUI.

When to Use Procler

Good fit:

• Multi-service dev environments (API + worker + DB + cache)
• Mixed local + Docker workflows
• AI-assisted development (Claude Code, Cursor, etc.)
• Teams that want config-as-code for their dev processes

Consider alternatives if:

• Single-process monitoring only — use your OS process manager
• Kubernetes clusters — use Helm/ArgoCD
• Multi-machine orchestration — use Nomad or Docker Swarm
• Production deployment only — use systemd directly (Procler can export to it)

Comparison

Showcase

[C01] Basic Process Lifecycle

$ procler define --name my-api --command "sleep 60"
{
  "success": true,
  "data": {"action": "created", "process": {"name": "my-api", ...}}
}

$ procler start my-api
{
  "success": true,
  "data": {"status": "started", "process": {"status": "running", "pid": 12345}}
}

$ procler status my-api
{
  "success": true,
  "data": {"process": {"name": "my-api", "status": "running", "pid": 12345, "uptime_seconds": 5}}
}

$ procler stop my-api
{"success": true, "data": {"status": "stopped"}}

[C02] JSON Response Contract

Every CLI command returns this envelope:

{"success": true, "data": {"..."}}

[C03] Error Response Contract

Every error includes error_code and suggestion:

{
  "success": false,
  "error": "Process 'api' not found",
  "error_code": "process_not_found",
  "suggestion": "Run 'procler list' to see available processes"
}

[C15] Idempotent Operations

$ procler start my-api       # Already running → no-op
{"success": true, "data": {"status": "already_running", "process": {"pid": 12345}}}

$ procler stop my-api        # Already stopped → no-op
{"success": true, "data": {"status": "already_stopped"}}

[C04] Group Orchestration

$ procler group start backend  # Starts redis → db → api → worker (in order)
$ procler group status backend # Status of all group processes
$ procler group stop backend   # Stops in reverse order

[C05] Recipe Dry-Run

$ procler recipe run deploy --dry-run   # Preview without executing
$ procler recipe run deploy             # Execute the multi-step recipe

[C06] Snippet Lifecycle

$ procler snippet save --name rebuild --command "docker compose build" --tags docker
$ procler snippet list --tag docker
$ procler snippet run rebuild
$ procler snippet remove rebuild

Installation

# Recommended
uv tool install procler

# With TUI support
uv tool install procler[tui]

# Or via pip
pip install procler

From source:

git clone https://github.com/gabu-quest/procler.git
cd procler && uv sync --all-extras

Frontend is pre-built and included. No separate build step needed.

Configuration

Per-project .procler/ directory. Discovery order: $PROCLER_CONFIG_DIR > .procler.env > .procler/ > git root > ~/.procler/

procler config init       # [C07] Creates .procler/ with template
procler config validate   # [C08] Validates syntax and references
procler config explain    # Plain-language explanation (LLM-friendly)

[C09] Comprehensive Example

version: 1

vars:
  API_PORT: "8000"
  DB_CONTAINER: postgres-dev

processes:
  api:
    command: uvicorn main:app --reload --port ${API_PORT}     # Variable substitution
    context: local
    cwd: /path/to/project
    tags: [backend, api]
    description: "API server"
    namespace: backend                                         # Namespace isolation
    ready_log_line: "Uvicorn running on"                      # log_ready condition
    max_memory: 512M                                          # Auto-restart on RSS exceed
    healthcheck:
      http_get: "http://localhost:${API_PORT}/health"         # HTTP probe (built-in)
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

  worker:
    command: celery worker -A tasks
    replicas: 3                                               # Creates worker-1, -2, -3
    depends_on:
      - redis                                                 # Wait for started (default)
      - name: api
        condition: log_ready                                  # Wait for ready_log_line
      - name: db
        condition: healthy                                    # Wait for health check

  db:
    command: postgres
    healthcheck:
      tcp_socket: "localhost:5432"                            # TCP probe (built-in)
      interval: 5s
      timeout: 3s

  cleanup:
    command: python scripts/cleanup.py
    schedule: "0 */6 * * *"                                   # Cron: every 6 hours

  db-migrate:
    command: alembic upgrade head
    context: docker
    container: ${DB_CONTAINER}                                # Docker execution

groups:
  backend:
    description: "Full backend stack"
    processes: [redis, db, api, worker]
    stop_order: [worker, api, db, redis]                      # Custom stop order

recipes:
  deploy:
    description: "Graceful deployment"
    on_error: stop
    steps:
      - stop: worker
      - stop: api
      - wait: 2s
      - exec: "alembic upgrade head"
        context: docker
        container: ${DB_CONTAINER}
      - start: api
      - start: worker

snippets:
  rebuild:
    command: docker compose build
    description: "Rebuild containers"
    tags: [docker]

CLI Reference

All commands return structured JSON. Run procler capabilities for the full machine-readable schema.

Define Options

REST API

Base URL: http://localhost:8000/api

Web Dashboard

Vue 3 frontend with Cyberpunk design. Start with procler serve and open http://localhost:8000.

• Dashboard — Process overview with real-time status
• Process Detail — Live log streaming via WebSocket, search/filter
• Groups — Card-based view, one-click start/stop all
• Recipes — Step preview, dry-run, execution progress
• Snippets — Save, manage, run reusable commands
• Config — Stats, variables, changelog viewer

Keyboard shortcuts: press ? for all. Quick nav: g d dashboard, g p processes, g g groups, g r recipes, g s snippets.

Frontend dev: cd frontend && npm run dev (port 5173), rebuild with bash scripts/build_frontend.sh

Honest Limitations

• Single-machine only — Procler manages processes on one host. For multi-machine, use Nomad or Docker Swarm.
• SQLite state — Runtime state is local SQLite. Not suitable for clustered deployments.
• Local logs only — Log capture is filesystem-based. No remote log sinks (Splunk, Datadog, etc.).
• One config per project — Use $PROCLER_CONFIG_DIR to manage multiple configs per project.
• No Windows support — Linux and macOS only (/proc integration for process state).

Environment Variables

Development

uv sync --all-extras        # Install all dependencies
uv run pytest -v            # Run tests (320+)
uv run procler serve --reload  # Dev server with hot reload

License

MIT