fellow-agents 0.0.5 → 0.0.6

package/README.md

@@ -1,76 +1,132 @@
 # fellow-agents
 
-Multiple Claude Code agents collaborating via messaging.
+**Run a team of Claude Code agents that talk to each other.**
 
-## Quick Start
+One command gives you a coordinator, a coder, and a reviewer — each in their own terminal, communicating through async messaging, managed from a single browser UI.
 
 ```bash
 npm install -g fellow-agents
-fellow-agents start
+mkdir my-team && cd my-team
+fellow-agents
 ```
 
-Downloads binaries on first run, starts services, opens browser. No git clone needed.
+That's it. Creates a workspace, downloads what it needs, opens your browser — three agents ready to collaborate.
 
-### 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
+## What happens when you run it
+
+1. Downloads platform binaries (first run only, ~30 seconds)
+2. Starts the messaging server (emcom)
+3. Registers three agents: **coordinator**, **coder**, **reviewer**
+4. Launches the browser UI (pty-win) on `http://localhost:3700`
+
+Each agent is a Claude Code session with its own workspace, personality, and tools. They message each other through emcom — no shared context window, no token limits, real async collaboration.
+
+## Try it
+
+1. Click **coordinator** in the browser UI (hit play)
+2. Tell it: *"Have the coder write a fibonacci function and the reviewer check it for edge cases."*
+3. Watch the agents coordinate — messages flow in the feed panel on the right
+
+The coordinator breaks down the task, sends it to the coder via emcom, the coder writes the code and sends it to the reviewer, the reviewer sends feedback back. All visible in real time.
+
+## How it works
+
+```
+fellow-agents start
+       |
+       v
+  +-----------+     emcom messages     +-----------+
+  | coordinator| <------------------> |   coder    |
+  +-----------+                        +-----------+
+       ^                                    |
+       |           emcom messages           |
+       +---------------------------------- +
+       |                                    v
+  +-----------+                        +-----------+
+  |  pty-win  |  browser UI on :3700   |  reviewer |
+  +-----------+                        +-----------+
+       |
+  emcom-server on :8800
 ```
 
+**pty-win** is the browser-based terminal multiplexer — every agent session in one tab. **emcom** is the messaging layer — agents send, receive, and reply to each other asynchronously. Each agent has a `CLAUDE.md` defining its role and an `identity.json` for messaging.
+
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/) 18+
-- [Claude Code](https://claude.ai/code) (optional for setup, required to run agents)
+- **Node.js 18+** — [nodejs.org](https://nodejs.org/)
+- **Claude Code** — [claude.ai/code](https://claude.ai/code) (needed to run agent sessions)
 
-## Alternative: Git Clone
+## Options
 
 ```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+)
+fellow-agents                           # start (default command)
+fellow-agents --port 4000               # custom pty-win port
+fellow-agents --emcom-port 9000         # custom messaging port
+fellow-agents --no-browser              # headless (server/CI)
+fellow-agents --update                  # force re-download binaries
+fellow-agents stop                      # stop all services
 ```
 
-## Try It
+## Add your own agent
 
-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)
+```bash
+mkdir workspaces/designer
+```
+
+Create `CLAUDE.md` (the agent's system prompt) and `identity.json` (name + description for messaging):
+
+```json
+{
+  "name": "designer",
+  "description": "UI/UX designer — creates interfaces and reviews layouts",
+  "server": "http://127.0.0.1:8800"
+}
+```
 
-## What's Included
+```bash
+emcom --identity workspaces/designer/identity.json register
+```
 
-| Component | Purpose |
-|-----------|---------|
-| **pty-win** | Browser terminal multiplexer — manage all agent sessions |
-| **emcom** | Async messaging between agents |
-| **templates/** | 3 starter agents: coordinator, coder, reviewer |
+Restart pty-win and the new agent appears in the UI.
 
-## Add an Agent
+## Alternative install: git clone
 
 ```bash
-mkdir workspaces/myagent
-# Copy CLAUDE.md + identity.json from an existing agent, customize
-emcom --identity workspaces/myagent/identity.json register
+git clone https://github.com/rajan-chari/fellow-agents.git
+cd fellow-agents
+./setup.sh           # Mac/Linux
+pwsh ./setup.ps1     # Windows (PowerShell 7+)
 ```
 
-## Architecture
+Same result, more control. Useful for development or Docker.
+
+## File layout
 
 ```
-~/.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
+~/.fellow-agents/              # Auto-created data directory
+  bin/{platform}/              # emcom, tracker, emcom-server
+  pty-win/                     # Terminal multiplexer
+  logs/                        # Service logs (check here if something fails)
+  pid/                         # PID files
+
+./workspaces/                  # Scaffolded from templates on first run
+  coordinator/CLAUDE.md        # "Break tasks down, delegate to coder/reviewer"
+  coder/CLAUDE.md              # "Write code, send to reviewer for feedback"
+  reviewer/CLAUDE.md           # "Review code, report issues back"
 ```
 
-## Stop
+## Troubleshooting
+
+**Services won't start?** Check `~/.fellow-agents/logs/emcom-server.log` and `pty-win.log`.
+
+**Port already in use?** Use `--port` and `--emcom-port` to pick different ports.
+
+**Browser didn't open?** Navigate to `http://localhost:3700` manually.
+
+**Want to start fresh?** `rm -rf ~/.fellow-agents` and run `fellow-agents start` again.
+
+## License
 
-`fellow-agents stop` or `Ctrl+C` in the start terminal.
+MIT

package/dist/cli.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 const args = process.argv.slice(2);
-const command = args[0] || "start";
+// Default to "start" if no command given or first arg is a flag
+const command = args[0] === "stop" ? "stop"
+    : (args[0] === "--help" || args[0] === "-h") ? "help"
+        : "start";
 function getFlag(name, fallback) {
     const idx = args.indexOf(name);
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
@@ -22,14 +25,14 @@ else if (command === "stop") {
     const { stop } = await import("./commands/stop.js");
     stop();
 }
-else if (command === "--help" || command === "-h") {
+else {
     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
+  fellow-agents [options]            Start services (default)
+  fellow-agents stop                 Stop all running services
 
-Options (start):
+Options:
   --port <number>       pty-win port (default: 3700)
   --emcom-port <number> emcom-server port (default: 8800)
   --dir <path>          Working directory (default: current)
@@ -38,8 +41,4 @@ Options (start):
 
   -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

@@ -12,7 +12,14 @@ export async function start(opts) {
     console.log("  fellow-agents");
     console.log("  =============");
     console.log("");
-    const workDir = resolve(opts.dir);
+    // Auto-create fellow-agents/ subdirectory if CWD doesn't already have workspaces/
+    let workDir = resolve(opts.dir);
+    if (!existsSync(join(workDir, "workspaces"))) {
+        workDir = join(workDir, "fellow-agents");
+        const { mkdirSync } = await import("fs");
+        mkdirSync(workDir, { recursive: true });
+        console.log(`  Working directory: ${workDir}`);
+    }
     const workspacesDir = join(workDir, "workspaces");
     const emcomUrl = `http://127.0.0.1:${opts.emcomPort}`;
     // 1. Prerequisites

package/dist/lib/download.js

@@ -1,5 +1,5 @@
 import { get } from "https";
-import { createWriteStream, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "fs";
+import { createWriteStream, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, chmodSync, readdirSync } from "fs";
 import { join, dirname } from "path";
 import { execSync } from "child_process";
 import { dataDir, binDir, ptyWinDir, versionFile } from "./paths.js";
@@ -57,6 +57,15 @@ export async function downloadBinaries(force = false) {
             mkdirSync(binDir, { recursive: true });
             extractZip(dest, dataDir);
             rmSync(dest);
+            // chmod +x on Linux/Mac
+            if (process.platform !== "win32") {
+                for (const f of readdirSync(binDir)) {
+                    try {
+                        chmodSync(join(binDir, f), 0o755);
+                    }
+                    catch { }
+                }
+            }
         }
         else if (asset.name.includes("pty-win")) {
             console.log(`  Downloading ${asset.name}...`);

package/dist/lib/services.js

@@ -39,15 +39,32 @@ function isRunning(pid) {
 }
 export function startEmcomServer(emcomPort, env) {
     const bin = join(binDir, `emcom-server${binarySuffix()}`);
+    if (!existsSync(bin)) {
+        console.error(`  emcom-server not found at ${bin}`);
+        return -1;
+    }
     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;
+    try {
+        const proc = spawn(bin, ["--port", String(emcomPort)], {
+            env: { ...env, EMCOM_PORT: String(emcomPort) },
+            detached: true,
+            stdio: ["ignore", log, log],
+        });
+        proc.on("error", (err) => {
+            if (err.code === "EACCES") {
+                console.error(`  Permission denied: ${bin}`);
+                console.error(`  Fix: chmod +x "${bin}"`);
+            }
+        });
+        proc.unref();
+        writePid("emcom-server", proc.pid);
+        return proc.pid;
+    }
+    catch (err) {
+        console.error(`  Failed to start emcom-server: ${err.message}`);
+        console.error(`  Check permissions on ${binDir}`);
+        return -1;
+    }
 }
 export function startPtyWin(port, workspacesDir, emcomUrl, env) {
     const main = join(ptyWinDir, "dist", "index.js");

package/dist/shims/emcom-server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runBinary } from "./run-binary.js";
+runBinary("emcom-server");

package/dist/shims/emcom.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runBinary } from "./run-binary.js";
+runBinary("emcom");

package/dist/shims/pty-cld.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
+// pty-cld lives alongside pty-win in the data directory
+import { dataDir } from "../lib/paths.js";
+const ptyCldDir = join(dataDir, "pty-cld");
+const main = join(ptyCldDir, "dist", "index.js");
+if (!existsSync(main)) {
+    console.error("pty-cld not found. Run 'fellow-agents' first to download binaries.");
+    process.exit(1);
+}
+try {
+    execFileSync("node", [main, ...process.argv.slice(2)], { stdio: "inherit" });
+}
+catch (err) {
+    process.exit(err.status ?? 1);
+}

package/dist/shims/pty-win.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
+import { ptyWinDir } from "../lib/paths.js";
+const main = join(ptyWinDir, "dist", "index.js");
+if (!existsSync(main)) {
+    console.error("pty-win not found. Run 'fellow-agents' first to download binaries.");
+    process.exit(1);
+}
+try {
+    execFileSync("node", [main, ...process.argv.slice(2)], { stdio: "inherit" });
+}
+catch (err) {
+    process.exit(err.status ?? 1);
+}

package/dist/shims/run-binary.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import { join } from "path";
+import { existsSync } from "fs";
+import { binDir } from "../lib/paths.js";
+import { binarySuffix } from "../lib/platform.js";
+export function runBinary(name) {
+    const bin = join(binDir, `${name}${binarySuffix()}`);
+    if (!existsSync(bin)) {
+        console.error(`${name} not found. Run 'fellow-agents' first to download binaries.`);
+        process.exit(1);
+    }
+    try {
+        execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+    }
+    catch (err) {
+        process.exit(err.status ?? 1);
+    }
+}

package/dist/shims/tracker.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runBinary } from "./run-binary.js";
+runBinary("tracker");

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "fellow-agents",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
   "type": "module",
   "bin": {
-    "fellow-agents": "dist/cli.js"
+    "fellow-agents": "dist/cli.js",
+    "emcom": "dist/shims/emcom.js",
+    "emcom-server": "dist/shims/emcom-server.js",
+    "tracker": "dist/shims/tracker.js",
+    "pty-win": "dist/shims/pty-win.js",
+    "pty-cld": "dist/shims/pty-cld.js"
   },
   "files": [
     "dist/",