fellow-agents 0.0.5

package/README.md

@@ -0,0 +1,76 @@
+# fellow-agents
+
+Multiple Claude Code agents collaborating via messaging.
+
+## Quick Start
+
+```bash
+npm install -g fellow-agents
+fellow-agents start
+```
+
+Downloads binaries on first run, starts services, opens browser. No git clone needed.
+
+### Options
+
+```bash
+fellow-agents start --port 3700 --emcom-port 8800  # custom ports
+fellow-agents start --no-browser                    # headless
+fellow-agents start --update                        # force re-download binaries
+fellow-agents stop                                  # stop all services
+```
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18+
+- [Claude Code](https://claude.ai/code) (optional for setup, required to run agents)
+
+## Alternative: Git Clone
+
+```bash
+git clone https://github.com/rajan-chari/fellow-agents.git
+cd fellow-agents
+./setup.sh           # Mac/Linux
+pwsh ./setup.ps1     # Windows (requires PowerShell 7+)
+```
+
+## Try It
+
+1. Open **coordinator** in pty-win (click play)
+2. Say: *"Have the coder write a fibonacci script and the reviewer check it."*
+3. Watch agents message each other in the emcom feed (right panel)
+
+## What's Included
+
+| Component | Purpose |
+|-----------|---------|
+| **pty-win** | Browser terminal multiplexer — manage all agent sessions |
+| **emcom** | Async messaging between agents |
+| **templates/** | 3 starter agents: coordinator, coder, reviewer |
+
+## Add an Agent
+
+```bash
+mkdir workspaces/myagent
+# Copy CLAUDE.md + identity.json from an existing agent, customize
+emcom --identity workspaces/myagent/identity.json register
+```
+
+## Architecture
+
+```
+~/.fellow-agents/          # Data directory (auto-created)
+  bin/{platform}/          # emcom, tracker, emcom-server binaries
+  pty-win/                 # Terminal multiplexer
+  pid/                     # PID files for running services
+  logs/                    # Service logs
+
+./workspaces/              # Agent workspaces (scaffolded from templates)
+  coordinator/             # Task coordinator
+  coder/                   # Code writer
+  reviewer/                # Code reviewer
+```
+
+## Stop
+
+`fellow-agents stop` or `Ctrl+C` in the start terminal.

package/dist/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+const args = process.argv.slice(2);
+const command = args[0] || "start";
+function getFlag(name, fallback) {
+    const idx = args.indexOf(name);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+function hasFlag(name) {
+    return args.includes(name);
+}
+if (command === "start") {
+    const { start } = await import("./commands/start.js");
+    await start({
+        port: parseInt(getFlag("--port", "3700"), 10),
+        emcomPort: parseInt(getFlag("--emcom-port", "8800"), 10),
+        dir: getFlag("--dir", process.cwd()),
+        noBrowser: hasFlag("--no-browser"),
+        update: hasFlag("--update"),
+    });
+}
+else if (command === "stop") {
+    const { stop } = await import("./commands/stop.js");
+    stop();
+}
+else if (command === "--help" || command === "-h") {
+    console.log(`fellow-agents — multi-agent system for Claude Code
+
+Usage:
+  fellow-agents start [options]    Start services (download binaries on first run)
+  fellow-agents stop               Stop all running services
+
+Options (start):
+  --port <number>       pty-win port (default: 3700)
+  --emcom-port <number> emcom-server port (default: 8800)
+  --dir <path>          Working directory (default: current)
+  --no-browser          Don't open browser
+  --update              Force re-download binaries
+
+  -h, --help            Show this help`);
+}
+else {
+    console.error(`Unknown command: ${command}. Run 'fellow-agents --help' for usage.`);
+    process.exit(1);
+}
+export {};

package/dist/commands/start.js

@@ -0,0 +1,135 @@
+import { existsSync } from "fs";
+import http from "http";
+import { join, resolve } from "path";
+import { execSync } from "child_process";
+import { binDir, ptyWinDir, logsDir } from "../lib/paths.js";
+import { downloadBinaries } from "../lib/download.js";
+import { startEmcomServer, startPtyWin, stopAll, logPath } from "../lib/services.js";
+import { scaffoldWorkspaces, registerAgents, writeHooks } from "../lib/workspaces.js";
+import { binarySuffix } from "../lib/platform.js";
+export async function start(opts) {
+    console.log("");
+    console.log("  fellow-agents");
+    console.log("  =============");
+    console.log("");
+    const workDir = resolve(opts.dir);
+    const workspacesDir = join(workDir, "workspaces");
+    const emcomUrl = `http://127.0.0.1:${opts.emcomPort}`;
+    // 1. Prerequisites
+    console.log("[1/7] Checking prerequisites...");
+    const nodeVer = process.versions.node;
+    const nodeMajor = parseInt(nodeVer.split(".")[0], 10);
+    if (nodeMajor < 18) {
+        console.error(`  Node.js 18+ required (found ${nodeVer})`);
+        process.exit(1);
+    }
+    console.log(`  Node.js ${nodeVer}`);
+    try {
+        execSync("claude --version", { stdio: "pipe" });
+        console.log("  Claude Code found");
+    }
+    catch {
+        console.log("  Claude Code not found (optional — install from https://claude.ai/code)");
+    }
+    // 2. Download binaries
+    console.log("[2/7] Downloading binaries...");
+    try {
+        await downloadBinaries(opts.update);
+    }
+    catch (err) {
+        console.error(`  Download failed: ${err}`);
+        if (!existsSync(join(binDir, `emcom${binarySuffix()}`))) {
+            console.error("  No cached binaries available. Check your internet connection.");
+            process.exit(1);
+        }
+        console.log("  Using cached binaries");
+    }
+    // 3. Install pty-win dependencies
+    console.log("[3/7] Installing pty-win...");
+    if (existsSync(join(ptyWinDir, "package.json"))) {
+        if (!existsSync(join(ptyWinDir, "node_modules"))) {
+            execSync("npm install --production", { cwd: ptyWinDir, stdio: "pipe" });
+        }
+        console.log("  pty-win ready");
+    }
+    else {
+        console.error("  pty-win not found — download may have failed");
+        process.exit(1);
+    }
+    // 4. Scaffold workspaces
+    console.log("[4/7] Scaffolding workspaces...");
+    scaffoldWorkspaces(workDir);
+    // PATH trick: prepend bin dir so agents find emcom/tracker
+    const env = { ...process.env, PATH: `${binDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH}` };
+    // 5. Start emcom-server
+    console.log("[5/7] Starting emcom-server...");
+    const emcomPid = startEmcomServer(opts.emcomPort, env);
+    console.log(`  emcom-server started (pid ${emcomPid})`);
+    // Wait for health
+    const healthy = await new Promise((resolve) => {
+        let attempts = 0;
+        const check = () => {
+            http.get(`${emcomUrl}/api/health`, (res) => {
+                if (res.statusCode === 200)
+                    return resolve(true);
+                if (++attempts < 20)
+                    setTimeout(check, 500);
+                else
+                    resolve(false);
+            }).on("error", () => {
+                if (++attempts < 20)
+                    setTimeout(check, 500);
+                else
+                    resolve(false);
+            });
+        };
+        check();
+    });
+    if (healthy) {
+        console.log(`  emcom-server running on :${opts.emcomPort}`);
+    }
+    else {
+        console.error(`  Warning: emcom-server health check failed — it may not be running`);
+        console.error(`  Check logs: ${logPath("emcom-server")}`);
+    }
+    // 6. Register agents
+    console.log("[6/7] Registering agents + configuring hooks...");
+    registerAgents(workspacesDir, env);
+    writeHooks(workspacesDir, opts.port);
+    // 7. Start pty-win
+    console.log("[7/7] Starting pty-win...");
+    const ptyPid = startPtyWin(opts.port, workspacesDir, emcomUrl, env);
+    console.log(`  pty-win started (pid ${ptyPid})`);
+    // Open browser
+    if (!opts.noBrowser) {
+        setTimeout(() => {
+            const url = `http://127.0.0.1:${opts.port}`;
+            try {
+                if (process.platform === "win32")
+                    execSync(`start "" "${url}"`, { stdio: "ignore" });
+                else if (process.platform === "darwin")
+                    execSync(`open "${url}"`, { stdio: "ignore" });
+                else
+                    execSync(`xdg-open "${url}" 2>/dev/null || true`, { stdio: "ignore" });
+            }
+            catch { }
+        }, 2000);
+    }
+    console.log("");
+    console.log("  Setup complete!");
+    console.log(`  pty-win:      http://127.0.0.1:${opts.port}`);
+    console.log(`  emcom-server: ${emcomUrl}`);
+    console.log(`  logs:         ${logsDir}`);
+    console.log("");
+    console.log("  Press Ctrl+C to stop all services.");
+    console.log("");
+    // Wait for Ctrl+C
+    process.on("SIGINT", () => {
+        console.log("\n  Shutting down...");
+        stopAll();
+        console.log("  Stopped.");
+        process.exit(0);
+    });
+    // Keep alive
+    setInterval(() => { }, 60000);
+}

package/dist/commands/stop.js

@@ -0,0 +1,8 @@
+import { stopAll } from "../lib/services.js";
+export function stop() {
+    console.log("");
+    console.log("  Stopping fellow-agents...");
+    stopAll();
+    console.log("  Done.");
+    console.log("");
+}

package/dist/lib/download.js

@@ -0,0 +1,93 @@
+import { get } from "https";
+import { createWriteStream, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { execSync } from "child_process";
+import { dataDir, binDir, ptyWinDir, versionFile } from "./paths.js";
+import { detectPlatform } from "./platform.js";
+const REPO = "rajan-chari/fellow-agents";
+function httpsGet(url) {
+    return new Promise((resolve, reject) => {
+        get(url, { headers: { "User-Agent": "fellow-agents-cli" } }, (res) => {
+            if (res.statusCode === 301 || res.statusCode === 302) {
+                return httpsGet(res.headers.location).then(resolve, reject);
+            }
+            let data = "";
+            res.on("data", (chunk) => (data += chunk));
+            res.on("end", () => resolve(data));
+            res.on("error", reject);
+        }).on("error", reject);
+    });
+}
+function httpsDownload(url, dest) {
+    return new Promise((resolve, reject) => {
+        get(url, { headers: { "User-Agent": "fellow-agents-cli" } }, (res) => {
+            if (res.statusCode === 301 || res.statusCode === 302) {
+                return httpsDownload(res.headers.location, dest).then(resolve, reject);
+            }
+            const file = createWriteStream(dest);
+            res.pipe(file);
+            file.on("finish", () => { file.close(); resolve(); });
+            file.on("error", reject);
+        }).on("error", reject);
+    });
+}
+export async function downloadBinaries(force = false) {
+    // Fetch latest release
+    const json = await httpsGet(`https://api.github.com/repos/${REPO}/releases/latest`);
+    const release = JSON.parse(json);
+    const tag = release.tag_name;
+    // Check if up to date
+    if (!force && existsSync(versionFile) && existsSync(binDir)) {
+        const localVer = readFileSync(versionFile, "utf-8").trim();
+        if (localVer === tag) {
+            console.log(`  Binaries up to date (${tag})`);
+            return tag;
+        }
+        console.log(`  Update available: ${localVer} → ${tag}`);
+    }
+    console.log(`  Downloading release ${tag}...`);
+    const platform = detectPlatform();
+    for (const asset of release.assets) {
+        if (asset.name.includes(platform)) {
+            console.log(`  Downloading ${asset.name}...`);
+            const dest = join(dataDir, asset.name);
+            mkdirSync(dirname(dest), { recursive: true });
+            await httpsDownload(asset.browser_download_url, dest);
+            // Extract zip
+            mkdirSync(binDir, { recursive: true });
+            extractZip(dest, dataDir);
+            rmSync(dest);
+        }
+        else if (asset.name.includes("pty-win")) {
+            console.log(`  Downloading ${asset.name}...`);
+            const dest = join(dataDir, asset.name);
+            mkdirSync(dirname(dest), { recursive: true });
+            // Remove old node_modules before extracting new pty-win
+            const nodeModules = join(ptyWinDir, "node_modules");
+            if (existsSync(nodeModules))
+                rmSync(nodeModules, { recursive: true });
+            await httpsDownload(asset.browser_download_url, dest);
+            extractZip(dest, dataDir);
+            rmSync(dest);
+        }
+    }
+    // Save version
+    mkdirSync(join(dataDir, "bin"), { recursive: true });
+    writeFileSync(versionFile, tag, "utf-8");
+    return tag;
+}
+function extractZip(zipPath, destDir) {
+    // Use tar on all platforms (Windows 10+ has tar built in)
+    try {
+        execSync(`tar -xf "${zipPath}" -C "${destDir}"`, { stdio: "pipe" });
+    }
+    catch {
+        // Fallback: PowerShell on Windows
+        if (process.platform === "win32") {
+            execSync(`powershell -NoProfile -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"`, { stdio: "pipe" });
+        }
+        else {
+            execSync(`unzip -qo "${zipPath}" -d "${destDir}"`, { stdio: "pipe" });
+        }
+    }
+}

package/dist/lib/paths.js

@@ -0,0 +1,19 @@
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { detectPlatform } from "./platform.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** ~/.fellow-agents/ */
+export const dataDir = join(homedir(), ".fellow-agents");
+/** ~/.fellow-agents/bin/{platform}/ */
+export const binDir = join(dataDir, "bin", detectPlatform());
+/** ~/.fellow-agents/pty-win/ */
+export const ptyWinDir = join(dataDir, "pty-win");
+/** ~/.fellow-agents/pid/ */
+export const pidDir = join(dataDir, "pid");
+/** ~/.fellow-agents/logs/ */
+export const logsDir = join(dataDir, "logs");
+/** ~/.fellow-agents/bin/.version */
+export const versionFile = join(dataDir, "bin", ".version");
+/** templates/ directory shipped with the npm package */
+export const templatesDir = join(__dirname, "..", "..", "templates");

package/dist/lib/platform.js

@@ -0,0 +1,15 @@
+import { platform, arch } from "os";
+export function detectPlatform() {
+    const os = platform();
+    const cpu = arch();
+    if (os === "win32")
+        return "win-x64";
+    if (os === "darwin")
+        return cpu === "arm64" ? "osx-arm64" : "osx-x64";
+    if (os === "linux")
+        return "linux-x64";
+    throw new Error(`Unsupported platform: ${os}-${cpu}`);
+}
+export function binarySuffix() {
+    return platform() === "win32" ? ".exe" : "";
+}

package/dist/lib/services.js

@@ -0,0 +1,97 @@
+import { spawn } from "child_process";
+import http from "http";
+import https from "https";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, openSync } from "fs";
+import { join } from "path";
+import { pidDir, binDir, ptyWinDir, logsDir } from "./paths.js";
+import { binarySuffix } from "./platform.js";
+function writePid(name, pid) {
+    mkdirSync(pidDir, { recursive: true });
+    writeFileSync(join(pidDir, `${name}.pid`), String(pid), "utf-8");
+}
+function readPid(name) {
+    const file = join(pidDir, `${name}.pid`);
+    if (!existsSync(file))
+        return null;
+    const pid = parseInt(readFileSync(file, "utf-8").trim(), 10);
+    return isNaN(pid) ? null : pid;
+}
+function removePid(name) {
+    const file = join(pidDir, `${name}.pid`);
+    if (existsSync(file))
+        rmSync(file);
+}
+function openLog(name) {
+    mkdirSync(logsDir, { recursive: true });
+    return openSync(join(logsDir, `${name}.log`), "w");
+}
+export function logPath(name) {
+    return join(logsDir, `${name}.log`);
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function startEmcomServer(emcomPort, env) {
+    const bin = join(binDir, `emcom-server${binarySuffix()}`);
+    const log = openLog("emcom-server");
+    const proc = spawn(bin, ["--port", String(emcomPort)], {
+        env: { ...env, EMCOM_PORT: String(emcomPort) },
+        detached: true,
+        stdio: ["ignore", log, log],
+    });
+    proc.unref();
+    writePid("emcom-server", proc.pid);
+    return proc.pid;
+}
+export function startPtyWin(port, workspacesDir, emcomUrl, env) {
+    const main = join(ptyWinDir, "dist", "index.js");
+    const log = openLog("pty-win");
+    const proc = spawn("node", [main, "--port", String(port), "--root", workspacesDir, "--emcom", emcomUrl], {
+        env,
+        detached: true,
+        stdio: ["ignore", log, log],
+    });
+    proc.unref();
+    writePid("pty-win", proc.pid);
+    return proc.pid;
+}
+export function stopAll() {
+    for (const name of ["emcom-server", "pty-win"]) {
+        const pid = readPid(name);
+        if (pid && isRunning(pid)) {
+            try {
+                process.kill(pid);
+                console.log(`  Stopped ${name} (pid ${pid})`);
+            }
+            catch {
+                console.log(`  Could not stop ${name} (pid ${pid})`);
+            }
+        }
+        else {
+            console.log(`  ${name} not running`);
+        }
+        removePid(name);
+    }
+}
+export function waitForHealth(url, timeoutMs = 30000) {
+    const mod = url.startsWith("https") ? https : http;
+    const startTime = Date.now();
+    return new Promise((resolve) => {
+        const check = () => {
+            if (Date.now() - startTime > timeoutMs)
+                return resolve(false);
+            mod.get(url, (res) => {
+                resolve(res.statusCode === 200);
+            }).on("error", () => {
+                setTimeout(check, 500);
+            });
+        };
+        check();
+    });
+}

package/dist/lib/workspaces.js

@@ -0,0 +1,54 @@
+import { cpSync, mkdirSync, existsSync, readdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { templatesDir, binDir } from "./paths.js";
+import { binarySuffix } from "./platform.js";
+export function scaffoldWorkspaces(targetDir) {
+    const workspacesDir = join(targetDir, "workspaces");
+    if (existsSync(workspacesDir) && readdirSync(workspacesDir).length > 0) {
+        console.log("  Workspaces already exist — skipping scaffold");
+        return;
+    }
+    console.log("  Scaffolding workspaces from templates...");
+    mkdirSync(workspacesDir, { recursive: true });
+    cpSync(templatesDir, workspacesDir, { recursive: true });
+}
+export function registerAgents(workspacesDir, env) {
+    const emcom = join(binDir, `emcom${binarySuffix()}`);
+    const dirs = readdirSync(workspacesDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory());
+    for (const dir of dirs) {
+        const idFile = join(workspacesDir, dir.name, "identity.json");
+        if (!existsSync(idFile))
+            continue;
+        try {
+            execSync(`"${emcom}" --identity "${idFile}" register --force`, {
+                env,
+                stdio: "pipe",
+                timeout: 10000,
+            });
+            console.log(`  Registered: ${dir.name}`);
+        }
+        catch {
+            console.log(`  Warning: failed to register ${dir.name}`);
+        }
+    }
+}
+export function writeHooks(workspacesDir, ptyWinPort) {
+    const dirs = readdirSync(workspacesDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory());
+    for (const dir of dirs) {
+        const claudeDir = join(workspacesDir, dir.name, ".claude");
+        mkdirSync(claudeDir, { recursive: true });
+        const settings = {
+            hooks: {
+                Stop: [{ matcher: "", hooks: [{ type: "http", url: `http://127.0.0.1:${ptyWinPort}/api/hook/stop`, timeout: 2 }] }],
+                Notification: [{ matcher: "idle_prompt|permission_prompt", hooks: [{ type: "http", url: `http://127.0.0.1:${ptyWinPort}/api/hook/notify`, timeout: 2 }] }],
+                UserPromptSubmit: [{ matcher: "", hooks: [{ type: "http", url: `http://127.0.0.1:${ptyWinPort}/api/hook/prompt-submit`, timeout: 2 }] }],
+            },
+            messageIdleNotifThresholdMs: 5000,
+        };
+        writeFileSync(join(claudeDir, "settings.local.json"), JSON.stringify(settings, null, 2), "utf-8");
+        console.log(`  Hooks configured: ${dir.name}`);
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "fellow-agents",
+  "version": "0.0.5",
+  "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
+  "type": "module",
+  "bin": {
+    "fellow-agents": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "agents",
+    "multi-agent",
+    "terminal",
+    "collaboration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rajan-chari/fellow-agents"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2"
+  }
+}

package/templates/coder/CLAUDE.md

@@ -0,0 +1,15 @@
+# Coder
+
+You write, fix, and improve code based on task descriptions from the coordinator.
+
+## On Load
+
+1. Register with emcom: `emcom --identity identity.json register 2>/dev/null || true`
+2. Check messages: `emcom --identity identity.json inbox`
+3. Greet the user and check for pending work
+
+## Communication
+
+- `emcom --identity identity.json send --to coordinator --subject "..." --body "..."` — report results
+- `emcom --identity identity.json inbox` — check for tasks
+- When done, message the coordinator with what you did and relevant file paths

package/templates/coder/identity.json

@@ -0,0 +1 @@
+{"name": "coder", "description": "Coder agent — writes and fixes code", "server": "http://127.0.0.1:8800"}

package/templates/coordinator/CLAUDE.md

@@ -0,0 +1,22 @@
+# Coordinator
+
+You coordinate a team of AI agents. Break down goals, delegate tasks, collect results.
+
+## On Load
+
+1. Register with emcom: `emcom --identity identity.json register 2>/dev/null || true`
+2. Check messages: `emcom --identity identity.json inbox`
+3. Ask the user what they'd like the team to work on
+
+## Communication
+
+- `emcom --identity identity.json send --to <name> --subject "..." --body "..."` — send a message
+- `emcom --identity identity.json inbox` — check messages
+- `emcom who` — see all agents
+
+## Workflow
+
+1. User gives you a goal
+2. Delegate to **coder** (implementation) or **reviewer** (analysis)
+3. Collect results via emcom
+4. Report back to user

package/templates/coordinator/identity.json

@@ -0,0 +1 @@
+{"name": "coordinator", "description": "Task coordinator — delegates work and collects results", "server": "http://127.0.0.1:8800"}

package/templates/reviewer/CLAUDE.md

@@ -0,0 +1,15 @@
+# Reviewer
+
+You review code for quality, bugs, and improvements.
+
+## On Load
+
+1. Register with emcom: `emcom --identity identity.json register 2>/dev/null || true`
+2. Check messages: `emcom --identity identity.json inbox`
+3. Greet the user and check for pending reviews
+
+## Communication
+
+- `emcom --identity identity.json send --to coordinator --subject "..." --body "..."` — report findings
+- `emcom --identity identity.json send --to coder --subject "..." --body "..."` — send feedback directly
+- `emcom --identity identity.json inbox` — check for review requests

package/templates/reviewer/identity.json

@@ -0,0 +1 @@
+{"name": "reviewer", "description": "Reviewer agent — reviews code for quality and correctness", "server": "http://127.0.0.1:8800"}