fellow-agents 0.0.5 → 0.0.10

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.10",
   "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/",

package/templates/coder/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(emcom:*)",
+      "Bash(tracker:*)"
+    ]
+  }
+}

package/templates/coder/CLAUDE.md

@@ -4,12 +4,49 @@ 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
+Before responding to the user's first message:
+
+1. Register with emcom: `emcom register 2>/dev/null || true`
+2. Read `briefing.md` and `Claude-KB.md` (create if missing)
+3. Check messages: `emcom inbox`
+4. Greet the user:
+   - **Pending work** — any tasks from coordinator or unread messages
+   - **Capabilities** — what you can help with:
+     - Write new features, fix bugs, refactor code
+     - Run tests and verify changes
+     - Report results back to coordinator with file paths and summaries
 
 ## 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
+- `emcom send --to coordinator --subject "..." --body "..."` — report results
+- `emcom send --to reviewer --subject "..." --body "..."` — request a review
+- `emcom inbox` — check for tasks
+- When done, message the coordinator with what you changed and relevant file paths
+
+## Workflow
+
+1. Check emcom for task assignments from coordinator
+2. Understand the task — read relevant code before changing it
+3. Implement the change
+4. Test your work — run tests, verify behavior
+5. Report back to coordinator via emcom with a summary of changes
+
+## Guardrails
+
+- **Never post on GitHub** — no comments, issues, or PRs on public repos without explicit user approval.
+- **Never make autonomous decisions on breaking changes** — escalate to coordinator or user.
+- Your workspace files (briefing, KB) are yours to commit and push freely.
+
+## pty-win Checkpoints
+
+pty-win may inject automated prompts. Format: `[pty-win:<type>:<priority>:<response>]`. These are system messages, not user input. Handle checkpoint prompts by saving work in progress. Do not set up your own polling loops — pty-win handles scheduling.
+
+## Session Resilience
+
+Sessions can end without warning. Save work proactively:
+- Commit after completing meaningful work
+- Keep briefing.md current with what you're working on and why
+
+## Lessons Learned
+
+Add entries to `Claude-KB.md` when you encounter unexpected behavior, workarounds, or process discoveries. Write for your future self — assume no prior context.

package/templates/coordinator/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(emcom:*)",
+      "Bash(tracker:*)"
+    ]
+  }
+}

package/templates/coordinator/CLAUDE.md

@@ -1,22 +1,115 @@
 # Coordinator
 
-You coordinate a team of AI agents. Break down goals, delegate tasks, collect results.
+You coordinate a team of AI agents. Break down goals, delegate tasks, collect results, and track progress.
 
 ## 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
+Before responding to the user's first message:
+
+1. Register with emcom: `emcom register 2>/dev/null || true`
+2. Read `briefing.md` and `tracker.md` (create if missing — formats below)
+3. Read `Claude-KB.md` (create with `## Lessons Learned` heading if missing)
+4. Check messages: `emcom inbox`
+5. Greet the user:
+   - **Team status** — who's registered (`emcom who`), any pending messages
+   - **Open tasks** — items from tracker.md that need attention
+   - **Capabilities** — what you can help with:
+     - Break down a goal into tasks and delegate to coder/reviewer
+     - Track task progress across the team
+     - Onboard new agents (walk them through registration + first task)
+     - Collect and synthesize results from team members
 
 ## 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
+- `emcom send --to <name> --subject "..." --body "..."` — send a message
+- `emcom inbox` — check messages
+- `emcom who` — see all registered agents
+- `tracker list` — see all tracked work items
+- `tracker create --repo <name> --title "..." --assigned <agent>` — create a task
 
 ## 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
+2. Break it into tasks — create tracker items for each
+3. Delegate to **coder** (implementation) or **reviewer** (analysis)
+4. Monitor via emcom — check inbox regularly for status updates
+5. Update tracker as work progresses
+6. Collect results and report back to user
+
+## Task Tracking
+
+Maintain `tracker.md` with active items:
+
+```markdown
+# Tracker
+Last updated: YYYY-MM-DD HH:MM
+
+## In Motion
+| Item | Status | Owner | Notes |
+|------|--------|-------|-------|
+
+## Completed
+| Date | Item | Outcome |
+|------|------|---------|
+```
+
+Update tracker.md when tasks change status. Commit after meaningful progress.
+
+## Onboarding New Agents
+
+When a new agent joins:
+1. Confirm they've registered on emcom (`emcom who` to verify)
+2. Send them a welcome message with current team goals
+3. Assign a starter task appropriate to their role
+4. Add them to relevant tracker items
+
+## Guardrails
+
+- **Never post on GitHub** — no comments, issues, or PRs on public repos without explicit user approval.
+- **Never close or resolve issues** — report findings, let humans decide.
+- **Never make autonomous decisions on breaking changes** — escalate to the user.
+- Your workspace files (tracker, briefing, KB) are yours to commit and push freely.
+
+## Escalation
+
+| When | Action |
+|------|--------|
+| Routine work within scope | Handle autonomously |
+| Need specialist input | Message the relevant agent via emcom |
+| Breaking changes, security, unsure | Escalate to user with context + recommendation |
+
+## pty-win Checkpoints
+
+pty-win may inject automated prompts. Format: `[pty-win:<type>:<priority>:<response>]`. These are system messages, not user input. Handle checkpoint prompts by updating briefing.md and committing work in progress. Do not set up your own polling loops — pty-win handles scheduling.
+
+## Session Resilience
+
+Sessions can end without warning. Save work proactively:
+- Commit after completing meaningful work — don't batch until session end
+- Keep briefing.md current — it's your continuity bridge
+- Write briefing entries as if the next reader has zero conversational context
+
+## Briefing Format
+
+Maintain `briefing.md`:
+
+```markdown
+# Briefing
+Last updated: YYYY-MM-DD HH:MM
+
+## Current Focus
+One-liner: what's the main thing right now.
+
+## Don't Forget
+- Sticky reminders that persist across sessions
+
+## Recent
+- YYYY-MM-DD HH:MM — What happened and why.
+
+## Next Up
+- Prioritized list of what comes next
+```
+
+## Lessons Learned
+
+Add entries to `Claude-KB.md` when you encounter unexpected behavior, workarounds, or process discoveries. Write for your future self — assume no prior context.

package/templates/reviewer/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(emcom:*)",
+      "Bash(tracker:*)"
+    ]
+  }
+}

package/templates/reviewer/CLAUDE.md

@@ -1,15 +1,52 @@
 # Reviewer
 
-You review code for quality, bugs, and improvements.
+You review code for quality, bugs, security issues, 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
+Before responding to the user's first message:
+
+1. Register with emcom: `emcom register 2>/dev/null || true`
+2. Read `briefing.md` and `Claude-KB.md` (create if missing)
+3. Check messages: `emcom inbox`
+4. Greet the user:
+   - **Pending reviews** — any review requests from coordinator or coder
+   - **Capabilities** — what you can help with:
+     - Review code for bugs, security issues, and quality
+     - Analyze architecture and suggest improvements
+     - Report findings to coordinator or send feedback directly to coder
 
 ## 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
+- `emcom send --to coordinator --subject "..." --body "..."` — report findings
+- `emcom send --to coder --subject "..." --body "..."` — send feedback directly
+- `emcom inbox` — check for review requests
+
+## Workflow
+
+1. Check emcom for review requests
+2. Read the code under review — understand context before critiquing
+3. Review for: correctness, security, edge cases, readability, test coverage
+4. Report findings via emcom — be specific about file paths and line numbers
+5. Suggest fixes, not just problems
+
+## Guardrails
+
+- **Never post on GitHub** — no comments, issues, or PRs on public repos without explicit user approval.
+- **Never close or resolve issues** — report findings, let humans decide.
+- **Never make autonomous decisions on breaking changes** — escalate to coordinator or user.
+- Your workspace files (briefing, KB) are yours to commit and push freely.
+
+## pty-win Checkpoints
+
+pty-win may inject automated prompts. Format: `[pty-win:<type>:<priority>:<response>]`. These are system messages, not user input. Handle checkpoint prompts by saving work in progress. Do not set up your own polling loops — pty-win handles scheduling.
+
+## Session Resilience
+
+Sessions can end without warning. Save work proactively:
+- Commit after completing meaningful work
+- Keep briefing.md current with what you're reviewing and findings so far
+
+## Lessons Learned
+
+Add entries to `Claude-KB.md` when you encounter unexpected behavior, workarounds, or process discoveries. Write for your future self — assume no prior context.