fellow-agents 0.0.21 → 0.0.22

package/README.md

@@ -12,6 +12,20 @@ fellow-agents
 
 That's it. Creates a workspace, downloads what it needs, opens your browser — three agents ready to collaborate.
 
+## What you get
+
+![fellow-agents in action — multiple AI sessions talking to each other in one browser tab](https://raw.githubusercontent.com/rajan-chari/fellow-agents/main/docs/screenshot.png)
+
+A team of AI agents working together in one browser. Each session is an autonomous agent — they message each other, coordinate on tasks, and track shared work. All running locally, all visible at once.
+
+- **(1) CLI sessions are agents.** Each one has its own identity, system prompt, and workspace.
+- **(2) Bring your own AI.** Claude Code, GitHub Copilot CLI, pi, or any compatible CLI — mix and match per agent.
+- **(3) Agents talk to each other.** Built-in async messaging (emcom) lets agents hand off tasks, request reviews, escalate questions — no shared context window, no token limits.
+- **(4) Run one or many per tab.** Group agents by team or project. Switch between tabs like browser tabs.
+- **(5) Built-in work tracker.** Every agent sees the same queue. File items, assign work, track status across sessions.
+
+If you've ever wished Claude could send a sub-task to another instance and get an answer back while you keep working — this is that.
+
 ---
 
 ## What happens when you run it

package/dist/cli.js

@@ -4,8 +4,9 @@ const args = process.argv.slice(2);
 const command = args[0] === "stop" ? "stop"
     : args[0] === "clean" ? "clean"
         : args[0] === "uninstall" ? "uninstall"
-            : (args[0] === "--help" || args[0] === "-h") ? "help"
-                : "start";
+            : args[0] === "config" ? "config"
+                : (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;
@@ -38,6 +39,10 @@ else if (command === "uninstall") {
         yes: hasFlag("--yes"),
     });
 }
+else if (command === "config") {
+    const { config } = await import("./commands/config.js");
+    config(args.slice(1));
+}
 else {
     console.log(`fellow-agents — multi-agent system for Claude Code, Copilot CLI, and pi
 
@@ -49,8 +54,9 @@ else {
 Commands:
   fellow-agents [options]            Start services (the usual command)
   fellow-agents stop                 Stop running services
-  fellow-agents clean                Wipe cached binaries + pty-win install (preserves logs)
+  fellow-agents clean                Wipe cached binaries + pty-win install (preserves logs and preferences)
   fellow-agents uninstall [--yes]    Remove all state, including scaffolded workspaces
+  fellow-agents config <get|set>     Read or write user preferences (see 'config --help')
 
 Start options:
   --port <number>       pty-win port (default: 3700)
@@ -63,6 +69,10 @@ Uninstall options:
   --yes                 Actually perform the uninstall (default is dry-run preview)
   --dir <path>          Workspace location (default: current — use if you ran start elsewhere)
 
+Config:
+  fellow-agents config get [key]            Print all preferences, or one value
+  fellow-agents config set <key> <value>    Write a preference (e.g. cliPreference claude)
+
 General:
   -h, --help            Show this help
 

package/dist/commands/clean.js

@@ -67,6 +67,7 @@ export function clean() {
     console.log("");
     console.log(`  Cleaned ${formatBytes(totalFreed)} from ${dataDir}`);
     console.log(`  Logs preserved at ${join(dataDir, "logs")}`);
+    console.log(`  Preferences preserved at ${join(dataDir, "preferences.json")} (if set)`);
     console.log(`  Run 'fellow-agents' to reinstall.`);
     console.log("");
 }

package/dist/commands/config.js

@@ -0,0 +1,109 @@
+import { readPreferences, writePreferences, lookupCli, preferencesFile, KNOWN_KEYS, } from "../lib/preferences.js";
+function printHelp() {
+    console.log(`fellow-agents config — read or write user preferences
+
+Usage:
+  fellow-agents config get                Print all preferences as JSON
+  fellow-agents config get <key>          Print the value of a single key
+  fellow-agents config set <key> <value>  Write a value (creates the file if missing)
+
+Known keys:
+  cliPreference   The CLI launched by pty-win's play button.
+                  Bare command (claude | copilot | pi) or full path to an executable.
+
+File: ${preferencesFile}
+
+Examples:
+  fellow-agents config set cliPreference claude
+  fellow-agents config set cliPreference "C:\\Program Files\\claude\\claude.exe"
+  fellow-agents config get cliPreference`);
+}
+function isKnownKey(key) {
+    return KNOWN_KEYS.includes(key);
+}
+export function config(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printHelp();
+        return;
+    }
+    const sub = args[0];
+    if (sub === "get") {
+        handleGet(args.slice(1));
+        return;
+    }
+    if (sub === "set") {
+        handleSet(args.slice(1));
+        return;
+    }
+    console.error(`Unknown config subcommand: ${sub}`);
+    console.error(`Run 'fellow-agents config --help' for usage.`);
+    process.exit(1);
+}
+function handleGet(args) {
+    const prefs = readPreferences();
+    if (args.length === 0) {
+        if (prefs === null) {
+            console.log("No preferences set.");
+            console.log(`Run 'fellow-agents' or 'fellow-agents config set <key> <value>' to create them.`);
+            return;
+        }
+        console.log(JSON.stringify(prefs, null, 2));
+        return;
+    }
+    const key = args[0];
+    if (!isKnownKey(key)) {
+        console.error(`Unknown key: ${key}`);
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    if (prefs === null) {
+        console.log("No preferences set.");
+        console.log(`Run 'fellow-agents' or 'fellow-agents config set ${key} <value>' to set it.`);
+        return;
+    }
+    const value = prefs[key];
+    if (value === undefined || value === null || value === "") {
+        console.log(`${key} is not set.`);
+        return;
+    }
+    console.log(String(value));
+}
+function handleSet(args) {
+    if (args.length < 2) {
+        console.error("Usage: fellow-agents config set <key> <value>");
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    const key = args[0];
+    const value = args.slice(1).join(" ");
+    if (!isKnownKey(key)) {
+        console.error(`Unknown key: ${key}`);
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    if (!value.trim()) {
+        console.error(`Value for '${key}' cannot be empty.`);
+        process.exit(1);
+    }
+    // cliPreference: warn (don't fail) if where.exe / which doesn't find it.
+    // Real use case: user pre-configures before installing the CLI, or the CLI
+    // is in a non-default location PATH doesn't see yet. Reject would block valid flows.
+    if (key === "cliPreference") {
+        const looksLikePath = value.includes("\\") || value.includes("/");
+        const resolved = lookupCli(value);
+        if (resolved === null && !looksLikePath) {
+            const tool = process.platform === "win32" ? "where.exe" : "which";
+            console.error(`  WARNING: '${tool} ${value}' returned no matches.`);
+            console.error(`  Writing the preference anyway — pty-win will fall back if the CLI is missing at launch time.`);
+            console.error(`  Fix later with: fellow-agents config set cliPreference <name-or-path>`);
+        }
+    }
+    const existing = readPreferences();
+    const written = writePreferences({
+        ...(existing ?? {}),
+        [key]: value,
+        updatedBy: "config-set",
+    });
+    console.log(`Set ${key} = ${value}`);
+    console.log(`Wrote ${preferencesFile} (schema ${written.schema}, updatedAt ${written.updatedAt}).`);
+}

package/dist/commands/start.js

@@ -2,12 +2,15 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
 import http from "http";
 import { join, resolve } from "path";
 import { execSync } from "child_process";
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { binDir, ptyWinDir, logsDir, dataDir } 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 { installSkills } from "../lib/skills.js";
 import { binarySuffix } from "../lib/platform.js";
+import { readPreferences, writePreferences, autoDetectClis, lookupCli, } from "../lib/preferences.js";
 // Minimal engines.node range check — handles ">=N", "<N", and combinations.
 function nodeInRange(version, range) {
     const major = parseInt(version.split(".")[0], 10);
@@ -17,6 +20,75 @@ function nodeInRange(version, range) {
     const max = maxMatch ? parseInt(maxMatch[1], 10) : Infinity;
     return major >= min && major < max;
 }
+/**
+ * First-run CLI preference prompt. Returns the chosen value (bare command or full path),
+ * or null if we should skip (non-interactive, or user declined).
+ *
+ * Design (locked 5/27 with milo):
+ * - Native readline (no inquirer dep — start.ts is a setup pipeline, not a chat UI)
+ * - Auto-detected CLIs from PATH shown as numbered choices, plus a "Custom path" option
+ * - If user types a custom value not on PATH, single confirm: "Use it anyway? [y/N]"
+ * - Non-interactive stdin (CI, piped) → return null, caller logs a hint
+ */
+async function promptForCliPreference() {
+    if (!input.isTTY)
+        return null;
+    const detected = autoDetectClis();
+    const rl = readline.createInterface({ input, output });
+    try {
+        console.log("");
+        console.log("  Pick your preferred CLI — pty-win's play button will launch this in each new tab.");
+        console.log("  (You can change it later with 'fellow-agents config set cliPreference <name>'.)");
+        console.log("");
+        const choices = [...detected];
+        if (detected.length > 0) {
+            for (let i = 0; i < detected.length; i++) {
+                console.log(`    [${i + 1}] ${detected[i]}`);
+            }
+        }
+        else {
+            console.log("    (None of claude/copilot/pi found on PATH — pick Custom path to specify your own)");
+        }
+        const customIdx = choices.length + 1;
+        console.log(`    [${customIdx}] Custom path or other command`);
+        console.log(`    [s] Skip for now`);
+        console.log("");
+        const answer = (await rl.question("  Choice: ")).trim().toLowerCase();
+        if (answer === "s" || answer === "skip" || answer === "") {
+            console.log("  Skipped — pty-win will pick a default until you set one.");
+            return null;
+        }
+        const num = parseInt(answer, 10);
+        if (!isNaN(num) && num >= 1 && num <= detected.length) {
+            return detected[num - 1];
+        }
+        if (!isNaN(num) && num === customIdx) {
+            const value = (await rl.question("  Enter command or full path: ")).trim();
+            if (!value) {
+                console.log("  Empty input — skipped.");
+                return null;
+            }
+            // Confirm step if value doesn't resolve and doesn't look like a path
+            const looksLikePath = value.includes("\\") || value.includes("/");
+            const resolved = lookupCli(value);
+            if (resolved === null && !looksLikePath) {
+                const tool = process.platform === "win32" ? "where.exe" : "which";
+                console.log(`  '${tool} ${value}' returned no matches.`);
+                const confirm = (await rl.question("  Use it anyway? [y/N]: ")).trim().toLowerCase();
+                if (confirm !== "y" && confirm !== "yes") {
+                    console.log("  Skipped.");
+                    return null;
+                }
+            }
+            return value;
+        }
+        console.log(`  Unrecognised choice '${answer}' — skipped.`);
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
 export async function start(opts) {
     console.log("");
     console.log("  fellow-agents");
@@ -43,6 +115,34 @@ export async function start(opts) {
         }
         catch { }
     }
+    // CLI preference prompt — fires when preferences.json is missing or has no cliPreference.
+    // Independent of the first-run marker so a user who wipes preferences.json (or upgrades from
+    // a pre-0.0.22 install) gets prompted on the next run. Non-interactive sessions skip silently.
+    const existingPrefs = readPreferences();
+    if (existingPrefs === null || !existingPrefs.cliPreference) {
+        const chosen = await promptForCliPreference();
+        if (chosen) {
+            try {
+                writePreferences({
+                    ...(existingPrefs ?? {}),
+                    cliPreference: chosen,
+                    updatedBy: "first-run-prompt",
+                });
+                console.log(`  CLI preference set: ${chosen}`);
+                console.log("");
+            }
+            catch (err) {
+                console.error(`  Failed to write preferences: ${err.message}`);
+                console.error(`  Continuing without a stored preference.`);
+                console.log("");
+            }
+        }
+        else if (!input.isTTY) {
+            console.log("  (non-interactive — skipping CLI preference setup)");
+            console.log(`  Set later with: fellow-agents config set cliPreference <name-or-path>`);
+            console.log("");
+        }
+    }
     // Auto-create fellow-agents/ subdirectory if CWD doesn't already have workspaces/
     let workDir = resolve(opts.dir);
     if (!existsSync(join(workDir, "workspaces"))) {

package/dist/lib/preferences.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { dataDir } from "./paths.js";
+/** ~/.fellow-agents/preferences.json */
+export const preferencesFile = join(dataDir, "preferences.json");
+export const CURRENT_SCHEMA = 1;
+/** Known CLI names — used by autoDetectClis() and as the default preset list for first-run prompt. */
+export const KNOWN_CLIS = ["claude", "copilot", "pi"];
+/** Known preference keys (for config get/set validation + --help listing). */
+export const KNOWN_KEYS = ["cliPreference"];
+export const KEY_SCHEMAS = {
+    cliPreference: {
+        type: "select",
+        label: "Default CLI",
+        description: "The CLI launched by pty-win's play button in each new tab.",
+        options: [...KNOWN_CLIS],
+        allowCustom: true,
+        customLabel: "Custom path…",
+    },
+};
+/**
+ * Read preferences from disk.
+ * Returns null if file is missing.
+ * Returns { schema: CURRENT_SCHEMA } with a warning on the console if file exists but is malformed —
+ * caller can decide whether to re-prompt.
+ */
+export function readPreferences() {
+    if (!existsSync(preferencesFile))
+        return null;
+    try {
+        const raw = readFileSync(preferencesFile, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error("not an object");
+        if (typeof parsed.schema !== "number")
+            throw new Error("missing schema");
+        return parsed;
+    }
+    catch (err) {
+        console.error(`  WARNING: ${preferencesFile} is malformed (${err.message}). Treating as unset.`);
+        return null;
+    }
+}
+/**
+ * Write preferences atomically (temp + renameSync — atomic on Windows from Node 10+).
+ * Always stamps `updatedAt` to now and `updatedBy` to the supplied value.
+ * Ensures dataDir exists. Cleans up the temp file on failure.
+ */
+export function writePreferences(prefs) {
+    mkdirSync(dataDir, { recursive: true });
+    const next = {
+        schema: prefs.schema ?? CURRENT_SCHEMA,
+        cliPreference: prefs.cliPreference,
+        updatedAt: new Date().toISOString(),
+        updatedBy: prefs.updatedBy,
+    };
+    const tmp = `${preferencesFile}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", "utf-8");
+        renameSync(tmp, preferencesFile);
+    }
+    catch (err) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+    return next;
+}
+/**
+ * Look up a CLI on PATH. Returns the resolved full path (first hit), or null if not found.
+ * Uses `where.exe` on Windows and `which -a` on Unix. Never throws.
+ */
+export function lookupCli(name) {
+    const cmd = process.platform === "win32" ? `where.exe ${name}` : `which ${name}`;
+    try {
+        const out = execSync(cmd, { stdio: ["ignore", "pipe", "ignore"] })
+            .toString()
+            .split(/\r?\n/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return out.length > 0 ? out[0] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Auto-detect which of the KNOWN_CLIS are on PATH.
+ * Returns the subset that resolved, preserving the KNOWN_CLIS priority order.
+ */
+export function autoDetectClis() {
+    return KNOWN_CLIS.filter((name) => lookupCli(name) !== null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fellow-agents",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
   "type": "module",
   "bin": {