offwatch 0.5.12 → 0.5.14

package/README.md

@@ -1,178 +1,132 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/header.png" alt="Offwatch — automate dev work" width="720" />
-</p>
-
-<p align="center">
-  <a href="#quickstart"><strong>Quickstart</strong></a> &middot;
-  <a href="https://github.com/triss-smith/offwatch"><strong>GitHub</strong></a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/triss-smith/offwatch/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
-  <a href="https://github.com/triss-smith/offwatch/stargazers"><img src="https://img.shields.io/github/stars/triss-smith/offwatch?style=flat" alt="Stars" /></a>
-</p>
-
-<br/>
-
-<div align="center">
-  <video src="https://github.com/user-attachments/assets/773bdfb2-6d1e-4e30-8c5f-3487d5b70c8f" width="600" controls></video>
-</div>
-
-<br/>
-
-## What is Offwatch?
-
-# Open-source orchestration for AI agent teams
-
-**If OpenClaw is an _employee_, Offwatch is the _team lead_**
-
-Offwatch is a Node.js CLI that orchestrates a team of AI agents to automate dev work. Bring your own agents, assign tasks, and track their work from the command line.
-
-**Manage development work, not pull requests.**
-
-|        | Step            | Example                                                            |
-| ------ | --------------- | ------------------------------------------------------------------ |
-| **01** | Define the task | _"Build a REST API for user management."_                          |
-| **02** | Hire the team   | Engineers, code reviewers, deployers — any bot, any provider.      |
-| **03** | Approve and run | Review strategy. Set budgets. Hit go. Monitor from the CLI.         |
-
-<br/>
-
-<div align="center">
-<table>
-  <tr>
-    <td align="center"><strong>Supports</strong></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw" /><br/><sub>OpenClaw</sub></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/claude.svg" width="32" alt="Claude" /><br/><sub>Claude Code</sub></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/codex.svg" width="32" alt="Codex" /><br/><sub>Codex</sub></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/cursor.svg" width="32" alt="Cursor" /><br/><sub>Cursor</sub></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/bash.svg" width="32" alt="Bash" /><br/><sub>Bash</sub></td>
-    <td align="center"><img src="https://raw.githubusercontent.com/triss-smith/offwatch/main/doc/assets/logos/http.svg" width="32" alt="HTTP" /><br/><sub>HTTP</sub></td>
-  </tr>
-</table>
-
-<em>If it can receive a heartbeat, it's hired.</em>
-
-</div>
-
-<br/>
-
-## Offwatch is right for you if
-
-- ✅ You want to **automate development work** with AI agents
-- ✅ You **coordinate many different agents** (OpenClaw, Codex, Claude, Cursor) toward a common goal
-- ✅ You have **multiple AI agent terminals** open and lose track of what everyone is doing
-- ✅ You want agents running **autonomously**, but still want to audit work and chime in when needed
-- ✅ You want **persistent task tracking** across reboots
-- ✅ You want a process for managing agents that **feels like using a task manager**
-
-<br/>
-
-## Features
-
-<table>
-<tr>
-<td align="center" width="33%">
-<h3>🔌 Bring Your Own Agent</h3>
-Any agent, any runtime, one team. If it can receive a heartbeat, it's hired.
-</td>
-<td align="center" width="33%">
-<h3>🎯 Task Management</h3>
-Every task traces back to the project goal. Agents know <em>what</em> to do and <em>why</em>.
-</td>
-<td align="center" width="33%">
-<h3>💓 Heartbeats</h3>
-Agents wake on a schedule, check work, and act. Delegation flows up and down.
-</td>
-</tr>
-<tr>
-<td align="center">
-<h3>💰 Cost Control</h3>
-Monthly budgets per agent. When they hit the limit, they stop. No runaway costs.
-</td>
-<td align="center">
-<h3>🏢 Multi-Workspace</h3>
-One deployment, many workspaces. Complete data isolation.
-</td>
-<td align="center">
-<h3>🎫 Ticket System</h3>
-Every conversation traced. Every decision explained. Full tool-call tracing and audit log.
-</td>
-</tr>
-<tr>
-<td align="center">
-<h3>🛡️ Governance</h3>
-You're the lead. Approve work, override strategy, pause or terminate any agent — at any time.
-</td>
-<td align="center">
-<h3>📊 Project Tracking</h3>
-Tasks, progress, status. Your agents have work to do, with clear reporting.
-</td>
-<td align="center">
-<h3>🔄 Persistent Sessions</h3>
-Agents resume the same task context across heartbeats instead of restarting from scratch.
-</td>
-</tr>
-</table>
-
-<br/>
-
-## Problems Offwatch solves
-
-| Without Offwatch                                                                                                                     | With Offwatch                                                                                                                         |
-| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| ❌ You have 20 AI agent tabs open and can't track which one does what. On reboot you lose everything.                                | ✅ Tasks are ticket-based, conversations are threaded, sessions persist across reboots.                                                |
-| ❌ You manually gather context from several places to remind your bot what you're actually doing.                                   | ✅ Context flows from the task up through the project — your agent always knows what to do and why.                                  |
-| ❌ Folders of agent configs are disorganized and you're re-inventing task management and coordination.                              | ✅ Offwatch gives you task management, ticketing, delegation, and governance out of the box.                                          |
-| ❌ Runaway loops waste hundreds of dollars of tokens and max your quota before you even know what happened.                          | ✅ Cost tracking surfaces token budgets and throttles agents when they're out.                                                       |
-| ❌ You have recurring jobs (maintenance, reports, deployments) and have to remember to manually kick them off.                      | ✅ Heartbeats handle regular work on a schedule.                                                                                      |
-| ❌ You have an idea, you have to find your repo, fire up Claude Code, keep a tab open, and babysit it.                               | ✅ Add a task in Offwatch. Your coding agent works on it until it's done.                                                            |
-
-<br/>
-
-## Quickstart
-
-```bash
-npm install -g offwatch
-offwatch --help
-```
-
-Or run directly:
-
-```bash
-npx offwatch --help
-```
-
-<br/>
-
-## CLI Commands
-
-```bash
-offwatch worktree create     # Create a new isolated worktree for agent tasks
-offwatch worktree list       # List all worktrees
-offwatch worktree sync       # Sync issues to worktree
-```
-
-<br/>
-
-## Development
-
-```bash
-pnpm install
-pnpm build
-pnpm dev
-```
-
-<br/>
-
-## License
-
-MIT &copy; 2026 Offwatch
-
-<br/>
-
----
-
-<p align="center">
-  <sub>Open source under MIT. Built for developers who want to automate work, not babysit agents.</sub>
-</p>
+# OffWatch
+
+**Your issues. Your agents. They ship while you're off-watch.**
+
+OffWatch is a self-hosted server that connects your issue tracker to a fleet of AI coding agents. Assign an issue in Linear — an agent checks it out, opens a branch, and commits. You review and merge.
+
+No babysitting. No tab management. Work lands in your repo.
+
+---
+
+## How it works
+
+| Step | What happens |
+| ---- | ------------ |
+| **01** | An issue is assigned to you in Linear |
+| **02** | OffWatch syncs it and makes it available to your agents |
+| **03** | An agent checks it out atomically, works the issue, and commits |
+| **04** | You get a summary in the issue thread and review the PR |
+
+Agents wake on a schedule and on events — new assignments, @-mentions, approval resolutions. When there's nothing to do, they sleep.
+
+---
+
+## Features
+
+**Issue tracker sync** — Linear adapter included. Issues sync in, completions sync back. Tracker-agnostic by design; additional adapters can be added.
+
+**Atomic checkout** — one agent per issue, enforced. No duplicate work, no conflicts.
+
+**Bring your own agent** — Claude Code, Codex, Cursor, OpenClaw, any HTTP endpoint, any local process. If it can receive a heartbeat, it works.
+
+**Heartbeat protocol** — agents wake on schedule or on trigger, do their work, and sleep. Token-efficient: incremental comment delivery means agents only read what's new since their last wake.
+
+**Approval queue** — agents can propose issues to your tracker before creating them. You approve or reject from the OffWatch UI.
+
+**Multiple workspaces** — one deployment, multiple codebases. Each workspace has its own agents, projects, and tracker config.
+
+**Skills** — inject context and workflow instructions into agents at runtime. Share skills across agents.
+
+**Plugins** — extend OffWatch with custom tracing, knowledge bases, queues, and more via the plugin SDK.
+
+**Activity log** — every agent action is recorded. Full audit trail, always.
+
+**Mobile-ready UI** — manage your agents from anywhere.
+
+---
+
+## OffWatch is right for you if
+
+- You want issues from your tracker to become commits without manual intervention
+- You run multiple AI coding agents and lose track of who is doing what
+- You want agents running 24/7 but still want to review their work before it merges
+- You want a persistent session layer so agents don't restart from scratch every time
+- You're hitting large token bills and want a leaner heartbeat layer
+
+## OffWatch is not right for you if
+
+- You want a chatbot or prompt manager — agents have jobs, not chat windows
+- You want a drag-and-drop workflow builder — OffWatch models agents working issues, not pipelines
+- You have one agent — this is for fleets
+
+---
+
+## Quickstart
+
+Open source. Self-hosted. No account required.
+
+```bash
+git clone https://github.com/triss-smith/offwatch.git
+cd offwatch
+pnpm install
+pnpm dev
+```
+
+This starts the API server at `http://localhost:3100` with an embedded PostgreSQL database. No setup required.
+
+> **Requirements:** Node.js 20+, pnpm 9.15+
+
+---
+
+## Configuration
+
+On first run, create a workspace and configure your issue tracker:
+
+1. Open `http://localhost:3100` and create a workspace
+2. Go to **Settings → Issue Tracker** and connect Linear (API key + team)
+3. Add an agent and point it at your adapter of choice
+4. Assign an issue to yourself in Linear and watch it appear
+
+---
+
+## Development
+
+```bash
+pnpm dev              # Full dev (API + UI, watch mode)
+pnpm dev:server       # Server only
+pnpm build            # Build all
+pnpm typecheck        # Type checking
+pnpm test:run         # Run tests
+pnpm db:generate      # Generate DB migration
+pnpm db:migrate       # Apply migrations
+```
+
+---
+
+## Roadmap
+
+- ✅ Issue tracker adapter system (Linear)
+- ✅ Atomic issue checkout
+- ✅ Heartbeat context compaction
+- ✅ Skills manager
+- ✅ Scheduled routines
+- ✅ Approval queue
+- ✅ Plugin system
+- ✅ Multiple workspaces
+- ⚪ GitHub Issues adapter
+- ⚪ Git worktree isolation per checkout
+- ⚪ Security audit routine
+- ⚪ Desktop app
+- ⚪ Additional tracker adapters
+
+---
+
+## Contributing
+
+Contributions welcome. Open an issue to discuss before sending large PRs.
+
+---
+
+## License
+
+MIT &copy; 2026 OffWatch

package/bin/offwatch.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
+import { loadCLIBinPath } from "../lib/downloader.js";
 import { spawn } from "child_process";
-import { dirname, resolve } from "path";
+import { dirname } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const srcDir = resolve(__dirname, "..", "src");
 
-// Run the CLI source with tsx (TypeScript executor)
-spawn("npx", ["tsx", resolve(srcDir, "index.ts")], {
-  stdio: "inherit",
-  shell: true,
-});
+const binPath = await loadCLIBinPath(__dirname);
+
+// Run the downloaded CLI binary
+spawn("node", [binPath], { stdio: "inherit" });

package/lib/downloader.js

@@ -0,0 +1,112 @@
+import got from "got";
+import fs from "fs";
+import fsa from "fs-extra";
+import * as os from "node:os";
+import tar from "tar";
+import stream from "node:stream";
+import { promisify } from "node:util";
+import path from "node:path";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const debugMode = process.env.DEBUG != null;
+const pipeline = promisify(stream.pipeline);
+
+const pkg = JSON.parse(fs.readFileSync(__dirname + "/../package.json", "utf8"));
+const CLI_FILENAME = "offwatch";
+
+const logDebug = (message) => {
+  if (debugMode) {
+    console.debug(`[DEBUG] ${message}`);
+  }
+};
+
+const getPlatform = () => {
+  const platform = os.platform();
+  if (platform === "win32") return "win32-x64";
+  if (platform === "darwin") return "darwin-x64";
+  return "linux-x64";
+};
+
+const downloadRelease = async (versionDir) => {
+  logDebug(`downloadRelease(${versionDir})`);
+  const version = pkg.version;
+
+  const releases = (await got
+    .get(`https://api.github.com/repos/triss-smith/offwatch/releases`)
+    .json());
+
+  // Find the latest release that matches our major.minor
+  const currentParts = extractVersionParts(version);
+  const matchingRelease = releases
+    .filter((release) => {
+      const releaseVersion = extractVersionParts(release.tag_name);
+      return (releaseVersion.major === currentParts.major &&
+        releaseVersion.minor === currentParts.minor);
+    })
+    .sort((a, b) => {
+      return Number(extractVersionParts(b.tag_name).patch) >
+        Number(extractVersionParts(a.tag_name).patch)
+        ? 1
+        : -1;
+    })[0] || releases[0];
+
+  if (!matchingRelease) {
+    throw new Error(`No releases found for ${currentParts.major}.${currentParts.minor}`);
+  }
+
+  const platform = getPlatform();
+  logDebug(`Looking for platform: ${platform} in release ${matchingRelease.tag_name}`);
+
+  const asset = matchingRelease.assets.find((asset) => {
+    return asset.name.includes(platform);
+  });
+
+  if (!asset) {
+    throw new Error(`${platform} is not currently supported. Check GitHub releases for available platforms.`);
+  }
+
+  try {
+    fsa.mkdirpSync(versionDir);
+  } catch (e) { }
+
+  const ext = asset.name.endsWith(".js") ? ".js" : "";
+  const filePath = path.join(versionDir, CLI_FILENAME + ext);
+  const tempPath = path.join(versionDir, asset.name);
+
+  logDebug(`Downloading ${asset.browser_download_url}`);
+
+  await pipeline(got.stream(asset.browser_download_url), fs.createWriteStream(tempPath));
+
+  if (ext) {
+    // For .js files, rename to expected name
+    fs.renameSync(tempPath, filePath);
+  } else {
+    // For compressed files, decompress
+    await pipeline(fs.createReadStream(tempPath), tar.x({
+      C: versionDir,
+      strip: 1,
+    }));
+    fs.unlinkSync(tempPath);
+  }
+};
+
+export const loadCLIBinPath = async (cwd) => {
+  const versionDir = path.join(cwd, pkg.version);
+  const ext = process.platform === "win32" ? ".js" : "";
+  const binPath = path.join(versionDir, CLI_FILENAME + ext);
+  logDebug(`loadCLIBinPath: ${binPath}`);
+
+  if (!fs.existsSync(binPath)) {
+    await downloadRelease(versionDir);
+  }
+
+  logDebug(`returning ${binPath}`);
+  return binPath;
+};
+
+const extractVersionParts = (version) => {
+  const [major, minor, patch] = version.replace(/^v/, "").split(".");
+  return { major, minor, patch };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offwatch",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "description": "Offwatch — orchestrate AI agent teams to automate dev work",
   "type": "module",
   "bin": {
@@ -24,20 +24,27 @@
     "url": "https://github.com/triss-smith/offwatch/issues"
   },
   "files": [
-    "src",
     "bin",
-    "lib"
+    "lib",
+    "postinstall.js"
   ],
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
-    "tsx": "^4.19.2",
-    "commander": "^13.1.0",
-    "@clack/prompts": "^0.10.0",
+    "@clack/prompts": "^0.7.0",
+    "commander": "^13.0.0",
+    "dotenv": "^16.4.5",
+    "drizzle-orm": "^0.38.0",
+    "embedded-postgres": "^18.1.0-beta.16",
+    "fs-extra": "^10.1.0",
+    "got": "^14.0.0",
     "picocolors": "^1.1.1",
-    "dotenv": "^17.0.1",
-    "drizzle-orm": "^0.38.4",
-    "embedded-postgres": "^18.1.0-beta.16"
+    "postgres": "^3.4.5",
+    "superjson": "^2.2.1",
+    "tar": "^6.2.0",
+    "undici": "^6.21.0",
+    "ws": "^8.19.0",
+    "zod": "^3.24.0"
   }
 }

package/postinstall.js

@@ -0,0 +1,18 @@
+import { loadCLIBinPath } from "./lib/downloader.js";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Skip download in monorepo development (workspace packages are used directly)
+if (!process.cwd().includes("node_modules")) {
+  loadCLIBinPath(__dirname).then(
+    () => {
+      process.exit(0);
+    },
+    (err) => {
+      console.error(err);
+      process.exit(1);
+    }
+  );
+}

package/src/__tests__/agent-jwt-env.test.ts

@@ -1,79 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  ensureAgentJwtSecret,
-  mergePaperclipEnvEntries,
-  readAgentJwtSecretFromEnv,
-  readPaperclipEnvEntries,
-  resolveAgentJwtEnvFile,
-} from "../config/env.js";
-import { agentJwtSecretCheck } from "../checks/agent-jwt-secret-check.js";
-
-const ORIGINAL_ENV = { ...process.env };
-
-function tempConfigPath(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-jwt-env-"));
-  const configDir = path.join(dir, "custom");
-  fs.mkdirSync(configDir, { recursive: true });
-  return path.join(configDir, "config.json");
-}
-
-describe("agent jwt env helpers", () => {
-  beforeEach(() => {
-    process.env = { ...ORIGINAL_ENV };
-    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
-  });
-
-  afterEach(() => {
-    process.env = { ...ORIGINAL_ENV };
-  });
-
-  it("writes .env next to explicit config path", () => {
-    const configPath = tempConfigPath();
-    const result = ensureAgentJwtSecret(configPath);
-
-    expect(result.created).toBe(true);
-
-    const envPath = resolveAgentJwtEnvFile(configPath);
-    expect(fs.existsSync(envPath)).toBe(true);
-    const contents = fs.readFileSync(envPath, "utf-8");
-    expect(contents).toContain("PAPERCLIP_AGENT_JWT_SECRET=");
-  });
-
-  it("loads secret from .env next to explicit config path", () => {
-    const configPath = tempConfigPath();
-    const envPath = resolveAgentJwtEnvFile(configPath);
-    fs.writeFileSync(envPath, "PAPERCLIP_AGENT_JWT_SECRET=test-secret\n", { mode: 0o600 });
-
-    const loaded = readAgentJwtSecretFromEnv(configPath);
-    expect(loaded).toBe("test-secret");
-    expect(process.env.PAPERCLIP_AGENT_JWT_SECRET).toBe("test-secret");
-  });
-
-  it("doctor check passes when secret exists in adjacent .env", () => {
-    const configPath = tempConfigPath();
-    const envPath = resolveAgentJwtEnvFile(configPath);
-    fs.writeFileSync(envPath, "PAPERCLIP_AGENT_JWT_SECRET=check-secret\n", { mode: 0o600 });
-
-    const result = agentJwtSecretCheck(configPath);
-    expect(result.status).toBe("pass");
-  });
-
-  it("quotes hash-prefixed env values so dotenv round-trips them", () => {
-    const configPath = tempConfigPath();
-    const envPath = resolveAgentJwtEnvFile(configPath);
-
-    mergePaperclipEnvEntries(
-      {
-        PAPERCLIP_WORKTREE_COLOR: "#439edb",
-      },
-      envPath,
-    );
-
-    const contents = fs.readFileSync(envPath, "utf-8");
-    expect(contents).toContain('PAPERCLIP_WORKTREE_COLOR="#439edb"');
-    expect(readPaperclipEnvEntries(envPath).PAPERCLIP_WORKTREE_COLOR).toBe("#439edb");
-  });
-});