prodboard 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # prodboard
 
+## 0.1.1
+
+### Patch Changes
+
+- 1aa4d25: Add `prodboard install` and `prodboard uninstall` commands to manage a user-level systemd service for the daemon
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -1,285 +1,293 @@
 # prodboard
 
-A self-hosted, CLI-first issue tracker and cron scheduler for AI coding agents.
+Give Claude Code a persistent task board and a cron scheduler so it can manage work across sessions.
 
-## Overview
+**The problem:** Claude Code loses context between sessions. It can't remember what tasks exist, what's in progress, or what to work on next. There's no way to schedule it to run recurring jobs like daily triage or nightly CI.
 
-prodboard provides three interfaces for managing issues and scheduled AI tasks:
+**The solution:** prodboard is a local issue tracker backed by SQLite that Claude Code can read and write through MCP tools. It also includes a cron daemon that spawns Claude Code on a schedule to work through tasks autonomously.
 
-- **CLI** — Human-friendly commands for issue tracking and schedule management
-- **MCP Server** — Model Context Protocol server for AI agent integration
-- **Scheduler Daemon** — Cron-based task scheduler that invokes Claude on a schedule
+```
+You (CLI)  ──┐
+              ├──▶  SQLite DB  ◀──  MCP Server  ◀──  Claude Code
+Cron Daemon ──┘
+```
 
-All state lives in a single SQLite database at `~/.prodboard/db.sqlite`.
+## What You Get
 
-## Quick Start
+- **An issue board Claude Code can use** — Claude reads, creates, updates, and completes issues via MCP tools during any session
+- **Scheduled Claude Code runs** — Define cron jobs that spawn Claude Code to triage issues, run maintenance, or work through the backlog
+- **A CLI you can use too** — Same board, human-friendly commands. Add issues, check status, review what Claude did
+- **Everything local** — Single SQLite file at `~/.prodboard/db.sqlite`. No servers, no accounts, no cloud
 
-### Install
+## Quick Start
 
 ```bash
+# Install
 bun install -g prodboard
+
+# Initialize
+prodboard init
+
+# Connect Claude Code to the board
+claude mcp add prodboard -- bunx prodboard mcp
 ```
 
-### Initialize
+That's it. Open Claude Code and start talking to it:
+
+## Things You Can Say to Claude Code
+
+Once connected, you can manage your board entirely through conversation:
+
+### Setting Up Cron Jobs
 
-```bash
-prodboard init
 ```
+"Every hour, tail the nginx access and error logs. If you see
+ anything unusual — spikes in 5xx errors, suspicious request
+ patterns, or unexpected traffic — create a new issue to investigate"
 
-This creates `~/.prodboard/` with the database, config, and generated files.
+"Every 2 hours, pick up the next todo issue and try to fix it.
+ Open a PR with your changes, comment the PR link on the issue,
+ and move the issue to review"
 
-### Connect to Claude
+"Every 2 hours, pick up the next issue in review. Check out the
+ PR, verify the code is correct and tests pass. If everything
+ looks good, merge it. If not, add a review comment on the PR
+ explaining what needs to change and move the issue back to todo"
 
-```bash
-claude mcp add prodboard -- bunx prodboard mcp
+"Create a cron job that runs every 6 hours to check for
+ and fix any TypeScript type errors in the project"
+
+"Set up a daily schedule at 9 AM on weekdays to review
+ the board and work on the highest priority task"
+
+"Add a cron job that runs every night at midnight to
+ run the test suite and create issues for any failures"
+
+"Schedule a weekly cleanup every Friday at 5 PM to
+ archive all done issues and summarize what was accomplished"
+
+"Create a schedule that runs every 30 minutes to monitor
+ the API health endpoint and create an issue if it's down"
 ```
 
-Or copy the generated MCP config:
+### Managing Tasks
 
-```bash
-cat ~/.prodboard/mcp.json
 ```
+"Add a task to fix the authentication timeout bug in the API"
 
-### Add the CLAUDE.md (optional)
+"What's on the board right now?"
 
-```bash
-prodboard init --claude-md
+"Pick up the next task and start working on it"
+
+"Mark the login bug as done, I fixed it manually"
+
+"Create an issue to refactor the database layer, mark it as todo"
+
+"Show me all in-progress issues"
+
+"Add a comment to the auth bug — we need to check the session TTL"
 ```
 
-## CLI Reference
+### Reviewing Activity
 
-### Issue Management
+```
+"Show me what the last cron run did"
 
-```bash
-# Create an issue
-prodboard add "Fix login bug" -d "SameSite cookie issue on Safari" -s todo
-
-# List issues
-prodboard ls                        # All non-archived issues
-prodboard ls --status todo          # Filter by status
-prodboard ls --search "login"       # Search title/description
-prodboard ls --json                 # JSON output
-prodboard ls --all                  # Include archived
-
-# Show issue details
-prodboard show <id>                 # Full ID or unique prefix
-prodboard show a3f9                 # Prefix match
-
-# Edit an issue
-prodboard edit <id> --title "New title"
-prodboard edit <id> --status review
-prodboard edit <id> -d "Updated description"
-
-# Move issue status
-prodboard mv <id> done
-
-# Delete an issue
-prodboard rm <id> --force
-
-# Comments
-prodboard comment <id> "Looking into this"
-prodboard comment <id> "Fixed it" --author claude
-prodboard comments <id>
-prodboard comments <id> --json
+"What tasks did you complete this week?"
+
+"Show the schedule stats for the daily triage job"
 ```
 
-### Schedule Management
+Claude Code handles all the MCP tool calls behind the scenes — you just talk to it naturally.
+
+## Adding Tasks from the CLI
+
+You can also manage the board directly:
 
 ```bash
-# Create a schedule
-prodboard schedule add \
-  --name "daily-triage" \
-  --cron "0 9 * * 1-5" \
-  --prompt "Review the board and triage new issues"
+prodboard add "Fix login bug" -d "OAuth callback URL is wrong" -s todo
+prodboard add "Add dark mode" -s todo
+prodboard add "Write API tests" -s todo
+prodboard ls
+```
 
-# List schedules
-prodboard schedule ls
-prodboard schedule ls --all --json
+### Starting the Scheduler
 
-# Edit a schedule
-prodboard schedule edit <id> --cron "0 10 * * *"
+```bash
+# Start the cron daemon (keeps running in foreground)
+prodboard daemon
 
-# Enable/disable
-prodboard schedule enable <id>
-prodboard schedule disable <id>
+# Or preview what's scheduled without running anything
+prodboard daemon --dry-run
+```
 
-# Delete
-prodboard schedule rm <id> --force
+## CLI Reference
+
+### Issues
 
-# Run immediately (foreground)
-prodboard schedule run <id>
+```bash
+prodboard add "Fix bug" -d "description" -s todo    # Create
+prodboard ls                                         # List (table)
+prodboard ls --status todo --status in-progress      # Filter by status
+prodboard ls --search "login" --json                 # Search + JSON output
+prodboard show <id>                                  # Details + comments
+prodboard edit <id> --title "New title" -s review    # Update fields
+prodboard mv <id> done                               # Change status
+prodboard rm <id> --force                            # Delete
+```
 
-# View run history
-prodboard schedule logs
-prodboard schedule logs --schedule <id> --limit 10
+### Comments
 
-# View statistics
-prodboard schedule stats
-prodboard schedule stats --schedule <id> --days 7
+```bash
+prodboard comment <id> "Looking into this"           # Add comment
+prodboard comment <id> "Fixed" --author claude       # With author
+prodboard comments <id>                              # List comments
 ```
 
-### Daemon
+### Schedules
 
 ```bash
-# Start daemon (foreground, for systemd)
-prodboard daemon
+prodboard schedule add --name "job" --cron "0 9 * * *" --prompt "Do X"
+prodboard schedule ls                                # List schedules
+prodboard schedule edit <id> --cron "0 10 * * *"     # Edit
+prodboard schedule enable <id>                       # Enable
+prodboard schedule disable <id>                      # Disable
+prodboard schedule rm <id> --force                   # Delete
+prodboard schedule run <id>                          # Run immediately
+prodboard schedule logs                              # Run history
+prodboard schedule stats --days 7                    # Statistics
+```
 
-# Dry run (show schedules without executing)
-prodboard daemon --dry-run
+### Daemon
 
-# Check daemon status
-prodboard daemon status
+```bash
+prodboard daemon                                     # Start (foreground)
+prodboard daemon --dry-run                           # Preview schedules
+prodboard daemon status                              # Check if running
 ```
 
 ### Other
 
 ```bash
-prodboard config    # Show current configuration
-prodboard version   # Show version
-prodboard help      # Show help
+prodboard config                                     # Show configuration
+prodboard version                                    # Show version
 ```
 
-## MCP Tools Reference
-
-| Tool | Description |
-|------|-------------|
-| `board_summary` | Overview of issues by status, recent issues |
-| `list_issues` | List issues with optional filters |
-| `get_issue` | Get full issue details with comments |
-| `create_issue` | Create a new issue |
-| `update_issue` | Update issue fields |
-| `delete_issue` | Delete an issue |
-| `add_comment` | Add a comment (default author: claude) |
-| `pick_next_issue` | Claim next todo, move to in-progress |
-| `complete_issue` | Mark done with optional comment |
-| `list_schedules` | List scheduled tasks |
-| `create_schedule` | Create a scheduled task |
-| `update_schedule` | Update a scheduled task |
-| `delete_schedule` | Delete a scheduled task |
-| `list_runs` | View run history |
-
-### MCP Resources
-
-| URI | Description |
-|-----|-------------|
-| `prodboard://issues` | Board summary (same as board_summary) |
-| `prodboard://schedules` | Active schedules with next run times |
+IDs support prefix matching — use `a3f9` instead of the full `a3f9b2c1d4e5f678`.
+
+## MCP Tools
+
+These are the tools Claude Code sees when connected to the board:
+
+| Tool | What Claude Uses It For |
+|------|------------------------|
+| `board_summary` | See issue counts and recent activity |
+| `list_issues` | Browse issues with filters |
+| `get_issue` | Read full issue details and comments |
+| `create_issue` | Log a new task or bug |
+| `update_issue` | Change title, description, or status |
+| `delete_issue` | Remove an issue |
+| `add_comment` | Leave notes on issues (default author: "claude") |
+| `pick_next_issue` | Claim the oldest todo, move to in-progress |
+| `complete_issue` | Mark done with an optional summary comment |
+| `list_schedules` | See scheduled jobs |
+| `create_schedule` | Set up a new cron job |
+| `update_schedule` | Modify a schedule |
+| `delete_schedule` | Remove a schedule |
+| `list_runs` | Check run history and results |
+
+MCP resources: `prodboard://issues` (board summary) and `prodboard://schedules` (active schedules).
 
 ## Configuration
 
-Config file: `~/.prodboard/config.jsonc` (JSONC format — comments allowed)
+Config file: `~/.prodboard/config.jsonc`
 
 ```jsonc
 {
   "general": {
-    // Issue statuses in display order
     "statuses": ["todo", "in-progress", "review", "done", "archived"],
-    // Default status for new issues
     "defaultStatus": "todo",
-    // Optional prefix for issue IDs
     "idPrefix": ""
   },
   "daemon": {
-    // Max concurrent scheduled runs
     "maxConcurrentRuns": 2,
-    // Default max turns for Claude
     "maxTurns": 50,
-    // Absolute max (cannot be overridden)
     "hardMaxTurns": 200,
-    // Run timeout in seconds
     "runTimeoutSeconds": 1800,
-    // Days to keep run history
     "runRetentionDays": 30,
-    // Log level: debug, info, warn, error
     "logLevel": "info",
-    // Worktree usage: auto, always, never
     "useWorktrees": "auto"
   }
 }
 ```
 
-## Scheduler Guide
+## Scheduler Details
 
 ### Cron Syntax
 
-Standard 5-field cron expressions:
+Standard 5-field cron:
 
 ```
-minute (0-59)
-hour (0-23)
-day of month (1-31)
-month (1-12)
-day of week (0-6, 0=Sunday)
+┌───────────── minute (0-59)
+│ ┌─────────── hour (0-23)
+│ │ ┌───────── day of month (1-31)
+│ │ │ ┌─────── month (1-12)
+│ │ │ │ ┌───── day of week (0-6, Sun=0)
+│ │ │ │ │
+* * * * *
 ```
 
-Examples:
-- `0 9 * * 1-5` — Weekdays at 9:00 AM
-- `*/15 * * * *` — Every 15 minutes
-- `0 0 1 * *` — First of every month at midnight
-- `0 9,17 * * *` — 9 AM and 5 PM daily
+| Expression | Meaning |
+|-----------|---------|
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 0 1 * *` | First of every month |
+| `0 9,17 * * *` | 9 AM and 5 PM daily |
 
 ### Template Variables
 
-Use in schedule prompts:
+Use in schedule prompts to inject board context:
 
-| Variable | Description |
-|----------|-------------|
-| `{{board_summary}}` | Compact summary: "3 todo, 1 in-progress, 0 review" |
+| Variable | Value |
+|----------|-------|
+| `{{board_summary}}` | "3 todo, 1 in-progress, 0 review" |
 | `{{todo_count}}` | Number of todo issues |
 | `{{in_progress_count}}` | Number of in-progress issues |
 | `{{datetime}}` | Current ISO 8601 timestamp |
 | `{{schedule_name}}` | Name of the schedule |
 
-Example:
-
 ```bash
 prodboard schedule add \
   --name "morning-standup" \
   --cron "0 9 * * 1-5" \
-  --prompt "Board status: {{board_summary}}. Pick and work on the next todo issue."
+  --prompt "Board: {{board_summary}}. Pick the next todo and work on it."
 ```
 
-## Running as a Service
-
-### systemd
-
-Create `/etc/systemd/system/prodboard.service`:
+### Running as a systemd Service
 
-```ini
-[Unit]
-Description=prodboard scheduler daemon
-After=network.target
+```bash
+# Install and start as a user-level systemd service (no sudo needed)
+prodboard install
 
-[Service]
-Type=simple
-User=your-user
-ExecStart=/usr/local/bin/bun run prodboard daemon
-Restart=on-failure
-RestartSec=10
+# Check status
+systemctl --user status prodboard
 
-[Install]
-WantedBy=multi-user.target
-```
+# Remove the service
+prodboard uninstall
 
-```bash
-sudo systemctl enable prodboard
-sudo systemctl start prodboard
-sudo systemctl status prodboard
+# Reinstall (e.g. after updating prodboard)
+prodboard install --force
 ```
 
 ## Troubleshooting
 
-**"prodboard is not initialized"**
-Run `prodboard init` to create `~/.prodboard/`.
+**"prodboard is not initialized"** — Run `prodboard init`.
 
-**MCP server not connecting**
-Check that `~/.prodboard/mcp.json` exists and the path to prodboard is correct.
+**MCP not connecting** — Verify `claude mcp add prodboard -- bunx prodboard mcp` was run, or check `~/.prodboard/mcp.json`.
 
-**Daemon not starting**
-Check `~/.prodboard/logs/daemon.log` for errors. Ensure claude CLI is installed and accessible.
+**Daemon not starting** — Check `~/.prodboard/logs/daemon.log`. Make sure `claude` CLI is installed and `ANTHROPIC_API_KEY` is set.
 
-**Stale PID file**
-If `prodboard daemon status` shows "stale PID file", the daemon crashed. It will auto-clean the PID file. Run `prodboard daemon` to restart.
+**Stale PID file** — The daemon crashed. Run `prodboard daemon` to restart (auto-cleans stale PIDs).
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prodboard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Self-hosted, CLI-first issue tracker and cron scheduler for AI coding agents",
   "type": "module",
   "license": "MIT",

package/src/commands/install.ts

@@ -0,0 +1,127 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const SERVICE_NAME = "prodboard";
+const SERVICE_DIR = path.join(os.homedir(), ".config", "systemd", "user");
+const SERVICE_PATH = path.join(SERVICE_DIR, `${SERVICE_NAME}.service`);
+
+function parseArgs(args: string[]): { flags: Record<string, boolean> } {
+  const flags: Record<string, boolean> = {};
+  for (const arg of args) {
+    if (arg === "--force" || arg === "-f") {
+      flags.force = true;
+    }
+  }
+  return { flags };
+}
+
+async function systemctlAvailable(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["systemctl", "--version"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const code = await proc.exited;
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function runSystemctl(...args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["systemctl", "--user", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+export function generateServiceFile(bunPath: string, prodboardPath: string, home: string): string {
+  return `[Unit]
+Description=prodboard scheduler daemon
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${bunPath} run ${prodboardPath} daemon
+Restart=on-failure
+RestartSec=10
+Environment="HOME=${home}"
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export async function install(args: string[]): Promise<void> {
+  const { flags } = parseArgs(args);
+
+  if (!(await systemctlAvailable())) {
+    console.error("systemd is not available on this system.");
+    console.error("The install command requires systemd (Linux).");
+    process.exit(1);
+  }
+
+  const alreadyInstalled = fs.existsSync(SERVICE_PATH);
+
+  if (alreadyInstalled && !flags.force) {
+    console.log("prodboard is already installed as a systemd service.");
+    const { stdout } = await runSystemctl("status", SERVICE_NAME);
+    console.log(stdout);
+    return;
+  }
+
+  const bunPath = Bun.which("bun") ?? process.execPath;
+  const prodboardPath = Bun.which("prodboard") ?? `${bunPath} x prodboard`;
+  const home = os.homedir();
+
+  const serviceContent = generateServiceFile(bunPath, prodboardPath, home);
+
+  fs.mkdirSync(SERVICE_DIR, { recursive: true });
+  fs.writeFileSync(SERVICE_PATH, serviceContent);
+  console.log(`Service file written to ${SERVICE_PATH}`);
+
+  const reload = await runSystemctl("daemon-reload");
+  if (reload.exitCode !== 0) {
+    console.error("Failed to reload systemd:", reload.stderr);
+    process.exit(1);
+  }
+
+  const enable = await runSystemctl("enable", SERVICE_NAME);
+  if (enable.exitCode !== 0) {
+    console.error("Failed to enable service:", enable.stderr);
+    process.exit(1);
+  }
+
+  const start = await runSystemctl("start", SERVICE_NAME);
+  if (start.exitCode !== 0) {
+    console.error("Failed to start service:", start.stderr);
+    process.exit(1);
+  }
+
+  console.log("prodboard service installed, enabled, and started.");
+  const { stdout } = await runSystemctl("status", SERVICE_NAME);
+  console.log(stdout);
+}
+
+export async function uninstall(_args: string[]): Promise<void> {
+  if (!fs.existsSync(SERVICE_PATH)) {
+    console.log("prodboard is not installed as a systemd service.");
+    return;
+  }
+
+  await runSystemctl("stop", SERVICE_NAME);
+  await runSystemctl("disable", SERVICE_NAME);
+
+  fs.unlinkSync(SERVICE_PATH);
+  console.log(`Removed ${SERVICE_PATH}`);
+
+  await runSystemctl("daemon-reload");
+  console.log("prodboard service uninstalled.");
+}

package/src/index.ts

@@ -142,6 +142,17 @@ export async function main(): Promise<void> {
         }
         break;
       }
+      case "install": {
+        ensureInitialized();
+        const { install } = await import("./commands/install.ts");
+        await install(args.slice(1));
+        break;
+      }
+      case "uninstall": {
+        const { uninstall } = await import("./commands/install.ts");
+        await uninstall(args.slice(1));
+        break;
+      }
       case "config": {
         ensureInitialized();
         const { loadConfig } = await import("./config.ts");
@@ -191,6 +202,8 @@ Commands:
   comments <id>     List comments for an issue
   schedule <sub>    Manage scheduled tasks
   daemon            Start the scheduler daemon
+  install           Install systemd service
+  uninstall         Remove systemd service
   config            Show configuration
   mcp               Start MCP server (stdio)
   version           Show version