@ssheleg/agent-sync 1.2.2

package/bin/agent-sync.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * agent-sync installer. Zero dependencies.
+ *
+ * One channel per agent: Claude Code gets the plugin, every other agent gets the
+ * skill through the vercel skills CLI, and the plain ~/.claude/skills/agent-sync
+ * copy that the skills CLI recreates on its own is pruned afterwards — that
+ * duplicate shadows the plugin and silently serves a stale skill.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REPO = 'appvillis-com/agent-sync';
+const NAME = 'agent-sync';
+const SHADOW = path.join(os.homedir(), '.claude', 'skills', NAME);
+
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+
+function run(cmd, args) {
+  process.stdout.write(C.dim(`  $ ${cmd} ${args.join(' ')}\n`));
+  const r = spawnSync(cmd, args, { stdio: 'inherit' });
+  return r.status === 0;
+}
+
+function has(cmd) {
+  return spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmd], {
+    stdio: 'ignore',
+  }).status === 0;
+}
+
+function usage() {
+  console.log(`
+${C.bold('agent-sync')} — coordination for concurrent agents
+
+  npx @ssheleg/${NAME} install              install for Claude Code and other agents
+  npx @ssheleg/${NAME} install --claude-only  Claude Code plugin only
+  npx @ssheleg/${NAME} install --agent a,b    pick agents for the skills CLI
+  npx @ssheleg/${NAME} update               update every channel, then prune the shadow
+  npx @ssheleg/${NAME} --help
+
+After installing, initialise the project — this is the step that asks where
+coordination state should live:
+
+  ${C.bold('/agent-sync init')}
+
+It writes .claude/agent-sync.json (committed) and .env.agent-sync (gitignored,
+mode 600), then tells you the one thing only you can do: create an API token in
+your own knowledge-base instance and paste it into that file. The installer never
+asks for a token and never stores one.
+`);
+}
+
+function install(argv) {
+  const claudeOnly = argv.includes('--claude-only');
+  const noClaude = argv.includes('--no-claude');
+  const agentIdx = argv.indexOf('--agent');
+  const agents = agentIdx !== -1 && argv[agentIdx + 1] ? argv[agentIdx + 1].split(',') : null;
+
+  let ok = true;
+
+  if (!noClaude) {
+    console.log(C.bold('\nClaude Code — as a plugin'));
+    if (!has('claude')) {
+      console.log(C.yellow('  claude CLI not found; skipping the plugin channel'));
+    } else {
+      // The full <name>@<name> form is required; `claude plugin install agent-sync`
+      // answers "Plugin not found".
+      ok = run('claude', ['plugin', 'marketplace', 'add', REPO]) && ok;
+      ok = run('claude', ['plugin', 'install', `${NAME}@${NAME}`]) && ok;
+    }
+  }
+
+  if (!claudeOnly) {
+    console.log(C.bold('\nOther agents — via the skills CLI'));
+    const args = ['--yes', 'skills', 'add', REPO, '--global', '--yes'];
+    for (const a of agents || []) args.push('--agent', a);
+    ok = run('npx', args) && ok;
+  }
+
+  pruneShadow();
+
+  console.log(
+    ok
+      ? C.green('\n✓ installed')
+      : C.red('\n✗ at least one channel failed — see the output above')
+  );
+  console.log(`
+${C.bold('Next:')} restart Claude Code, then run ${C.bold('/agent-sync init')} in your project.
+It will ask where coordination state should live before writing anything.
+`);
+  return ok ? 0 : 1;
+}
+
+/**
+ * The shadow regrows on its own: `npx skills add|update --global` auto-detects
+ * Claude Code and recreates ~/.claude/skills/<name> — often as a symlink — even when
+ * claude-code was never named as a target. That copy shadows the plugin and serves a
+ * stale skill, so the prune belongs INSIDE every command that touches the skills CLI,
+ * not in a human's memory. lstatSync, because a symlink shadows exactly as a dir does.
+ */
+function pruneShadow() {
+  let present = false;
+  try {
+    fs.lstatSync(SHADOW);
+    present = true;
+  } catch {
+    /* not there */
+  }
+  if (!present) return;
+  fs.rmSync(SHADOW, { recursive: true, force: true });
+  console.log(C.dim(`  pruned duplicate ${SHADOW}`));
+}
+
+function update() {
+  console.log(C.bold('\nUpdating every channel'));
+  let ok = true;
+  if (has('claude')) {
+    ok = run('claude', ['plugin', 'marketplace', 'update', NAME]) && ok;
+    // The full <name>@<name> id is required; `claude plugin update <name>` answers
+    // "Plugin not found".
+    ok = run('claude', ['plugin', 'update', `${NAME}@${NAME}`]) && ok;
+  }
+  ok = run('npx', ['--yes', 'skills', 'update', NAME, '--global', '--yes']) && ok;
+  pruneShadow();
+  console.log(ok ? C.green('\n✓ updated') : C.red('\n✗ a channel failed — see above'));
+  console.log('\nRestart Claude Code so it picks the new version up.');
+  return ok ? 0 : 1;
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+  usage();
+  process.exit(0);
+}
+if (argv[0] === 'install') process.exit(install(argv.slice(1)));
+if (argv[0] === 'update') process.exit(update());
+usage();
+process.exit(1);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ssheleg/agent-sync",
+  "version": "1.2.2",
+  "description": "Let concurrent coding agents share one project without colliding \u2014 leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
+  "bin": {
+    "agent-sync": "bin/agent-sync.js"
+  },
+  "files": [
+    "bin/",
+    "plugins/",
+    "agent-sync.schema.json",
+    "agent-sync.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "python3 test/validate.py && python3 test/validate.py --self-test",
+    "prepublishOnly": "python3 test/validate.py"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "multi-agent",
+    "coordination",
+    "lease",
+    "knowledge-base",
+    "task-pipeline"
+  ],
+  "homepage": "https://github.com/appvillis-com/agent-sync",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appvillis-com/agent-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/appvillis-com/agent-sync/issues"
+  },
+  "author": "appvillis-com",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-sync",
+  "version": "1.2.2",
+  "description": "Coordination layer for multi-agent repositories — leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
+  "author": {
+    "name": "appvillis-com"
+  },
+  "homepage": "https://github.com/appvillis-com/agent-sync",
+  "repository": "https://github.com/appvillis-com/agent-sync",
+  "license": "MIT",
+  "keywords": [
+    "multi-agent",
+    "coordination",
+    "lease",
+    "knowledge-base",
+    "task-pipeline"
+  ]
+}

package/plugins/agent-sync/commands/agent-sync.md

@@ -0,0 +1,16 @@
+---
+description: Coordinate concurrent agents — initialise the shared knowledge store, check status, claim a task, reserve an id, or regenerate the board.
+argument-hint: "[init|status|claim <KEY>|release <KEY>|reserve <REG>|board]"
+---
+
+Invoke the `agent-sync` skill.
+
+Arguments: $ARGUMENTS
+
+If no arguments were given, run the skill's default entry: check whether the
+project is initialised, and if it is not, **ask the operator where coordination
+state should live before doing anything else** — a knowledge cloud (and then its
+instance URL) or local files. Never guess that answer.
+
+If the project is already initialised, report status and name exactly one next
+action.

package/plugins/agent-sync/hooks/_lib.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Shared helpers for the agent-sync hooks. Sourced, never executed.
+
+# Run a command under a time limit, portably.
+#
+# `timeout` is GNU coreutils and is NOT on a stock macOS. Calling it directly made
+# three of the four hooks die with "timeout: command not found" on every macOS
+# session — which meant leases were never renewed and never released there, the exact
+# abandoned-lease failure this tool exists to prevent. Homebrew installs it as
+# `gtimeout`, and neither is guaranteed, so fall back to a plain-bash watchdog.
+run_limited() {
+  local secs="$1"; shift
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$secs" "$@"
+    return $?
+  fi
+  if command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$secs" "$@"
+    return $?
+  fi
+
+  "$@" &
+  local pid=$!
+  ( sleep "$secs"; kill -TERM "$pid" 2>/dev/null ) &
+  local watchdog=$!
+  wait "$pid" 2>/dev/null
+  local rc=$?
+  kill "$watchdog" 2>/dev/null
+  wait "$watchdog" 2>/dev/null
+  return "$rc"
+}
+
+# Every hook is a no-op in a project that does not use agent-sync, so installing the
+# plugin globally changes nothing elsewhere.
+agent_sync_configured() {
+  [ -f "${CLAUDE_PROJECT_DIR:-$PWD}/.claude/agent-sync.json" ]
+}
+
+AGENT_SYNC_PY="${CLAUDE_PLUGIN_ROOT:-}/skills/agent-sync/scripts/agent_sync.py"

package/plugins/agent-sync/hooks/guard.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# PreToolUse guard. Exit 2 blocks the call and shows stderr as the reason.
+# Any other non-zero code is NON-blocking in Claude Code, so every internal
+# failure must also exit 2 — a crashing guard that fails open guards nothing.
+set -uo pipefail
+S="${CLAUDE_PLUGIN_ROOT}/skills/agent-sync/scripts/agent_sync.py"
+input=$(cat)
+
+path=$(python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+ti=d.get("tool_input") or {}
+print(ti.get("file_path") or ti.get("path") or ti.get("notebook_path") or "")
+' <<<"$input" 2>/dev/null)
+
+# git commit: check every staged path instead of a single file argument.
+if [ -z "$path" ]; then
+  cmd=$(python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+print((d.get("tool_input") or {}).get("command",""))
+' <<<"$input" 2>/dev/null)
+  case "$cmd" in
+    *"git commit"*)
+      while IFS= read -r staged; do
+        [ -n "$staged" ] || continue
+        if ! python3 "$S" guard "$staged" >/dev/null 2>&1; then
+          echo "agent-sync: '$staged' is staged but this run holds no lease on it. Acquire one, or unstage it." >&2
+          exit 2
+        fi
+      done < <(git diff --cached --name-only 2>/dev/null)
+      ;;
+  esac
+  exit 0
+fi
+
+[ -f "${CLAUDE_PROJECT_DIR:-$PWD}/.claude/agent-sync.json" ] || exit 0
+
+if out=$(python3 "$S" guard "$path" 2>&1); then
+  exit 0
+else
+  code=$?
+  if [ "$code" -eq 2 ]; then
+    echo "$out" >&2
+    exit 2
+  fi
+  echo "agent-sync guard failed to run ($code): $out" >&2
+  exit 2
+fi

package/plugins/agent-sync/hooks/hooks.json

@@ -0,0 +1,69 @@
+{
+  "description": "agent-sync — lease enforcement and run lifecycle. Every hook exits 0 immediately when the project has no .claude/agent-sync.json, so installing the plugin globally changes nothing in projects that do not use it.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh\"",
+            "timeout": 20
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "if": "Bash(git commit *)",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/renew.sh\"",
+            "timeout": 15,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/agent-sync/hooks/renew.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Runs after every tool call, so it must be a no-op in the common case:
+# the script itself throttles on a timestamp file and touches the network at
+# most once per renewIntervalSeconds.
+set -uo pipefail
+. "${CLAUDE_PLUGIN_ROOT}/hooks/_lib.sh"
+S="$AGENT_SYNC_PY"
+agent_sync_configured || exit 0
+run_limited 10 python3 "$S" renew >/dev/null 2>&1 || true
+exit 0

package/plugins/agent-sync/hooks/session-end.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Release every lease this run holds. An abandoned lease looks like active work
+# until its TTL expires.
+set -uo pipefail
+. "${CLAUDE_PLUGIN_ROOT}/hooks/_lib.sh"
+S="$AGENT_SYNC_PY"
+agent_sync_configured || exit 0
+held=$(run_limited 10 python3 "$S" whoami 2>/dev/null | sed -n 's/^holds: //p')
+[ -z "$held" ] || [ "$held" = "nothing" ] && exit 0
+IFS=', ' read -r -a keys <<<"$held"
+for k in "${keys[@]}"; do
+  [ -n "$k" ] && run_limited 10 python3 "$S" release "$k" >/dev/null 2>&1 || true
+done
+exit 0

package/plugins/agent-sync/hooks/session-start.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Register the run and print the board summary plus one next action.
+set -uo pipefail
+. "${CLAUDE_PLUGIN_ROOT}/hooks/_lib.sh"
+S="$AGENT_SYNC_PY"
+agent_sync_configured || exit 0
+run_limited 10 python3 "$S" status 2>&1 || true
+exit 0