claude-friends 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nandini Talwar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# claude-friends
+
+See who's online in Claude Code. Add friends, share what you're working on, nudge each other.
+
+```
+● 2 online (alice, bob)
+```
+
+## Install
+
+```bash
+npm install -g claude-friends
+claude-friends setup
+claude mcp add claude-friends -- claude-friends serve
+```
+
+That's it. No database, no API keys.
+
+## What you get
+
+A status line in Claude Code showing online friends, plus these tools:
+
+| Command | What it does |
+|---|---|
+| "who's online?" | See friends with 🟢/⚫ indicators |
+| "add friend alice" | Add someone by username |
+| "set my status to debugging auth" | Share what you're working on |
+| "nudge bob" | Poke a friend with a message |
+| "share my token usage: 45000" | Let friends see your token count |
+| "check nudges" | See if anyone poked you |
+
+## Status line
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node /path/to/claude-friends/statusline.js"
+  }
+}
+```
+
+Or after global install:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "claude-friends statusline"
+  }
+}
+```
+
+## How it works
+
+- **PartyKit** handles real-time presence via WebSockets
+- When you open Claude Code → you go online
+- When you close it → PartyKit detects the disconnect → you go offline
+- Friend lists and nudges are stored in-memory on the server
+- No accounts, no passwords — just a username
+
+## Self-hosting
+
+Want to run your own server? Fork this repo, then:
+
+```bash
+npx partykit deploy
+```
+
+Update the `PARTY_HOST` in `client.js` to point to your deployment.
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createInterface } from "readline";
+import { getConfig } from "./client.js";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(homedir(), ".claude-friends.json");
+
+const command = process.argv[2];
+
+if (command === "setup") {
+  const existing = getConfig();
+  if (existing) {
+    console.log(`\nAlready set up as "${existing.username}".`);
+    console.log(`Config: ${CONFIG_PATH}`);
+    console.log(`\nTo change username, delete ${CONFIG_PATH} and run again.\n`);
+    process.exit(0);
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+
+  console.log(`
+╔══════════════════════════════════════╗
+║        claude-friends setup          ║
+╚══════════════════════════════════════╝
+`);
+
+  const username = await ask("Choose a username: ");
+
+  if (!username.trim()) {
+    console.log("Username can't be empty.");
+    process.exit(1);
+  }
+
+  writeFileSync(CONFIG_PATH, JSON.stringify({ username: username.trim() }, null, 2));
+
+  console.log(`
+Done! You're "${username.trim()}".
+
+Now add the MCP server to Claude Code:
+
+  claude mcp add claude-friends -- node ${join(__dirname, "mcp-server.js")}
+
+Then in Claude Code, try:
+  "who's online?"
+  "add friend alice"
+  "set my status to debugging auth"
+  "nudge bob"
+`);
+
+  rl.close();
+} else if (command === "serve") {
+  // Start the MCP server directly
+  await import("./mcp-server.js");
+} else if (command === "whoami") {
+  const config = getConfig();
+  if (!config) {
+    console.log("Not set up yet. Run: claude-friends setup");
+  } else {
+    console.log(config.username);
+  }
+} else {
+  console.log(`
+claude-friends — social presence for Claude Code
+
+Commands:
+  setup     Pick a username (one-time)
+  serve     Start the MCP server (used by Claude Code)
+  whoami    Show your username
+
+Quick start:
+  claude-friends setup
+  claude mcp add claude-friends -- claude-friends serve
+`);
+}

package/client.js

@@ -0,0 +1,58 @@
+// Shared client for connecting to the PartyKit server
+import PartySocket from "partysocket";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+
+const CONFIG_PATH = join(homedir(), ".claude-friends.json");
+
+// TODO: replace with your deployed PartyKit URL after `npx partykit deploy`
+const PARTY_HOST = "claude-friends-app.nandinitalwar.partykit.dev";
+
+export function getConfig() {
+  if (!existsSync(CONFIG_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function createConnection(username) {
+  const ws = new PartySocket({
+    host: PARTY_HOST,
+    room: "lobby",
+    query: { username },
+  });
+  return ws;
+}
+
+// One-shot: connect, request data, disconnect
+export async function queryFriends(username, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const ws = createConnection(username);
+    const timer = setTimeout(() => {
+      ws.close();
+      reject(new Error("timeout"));
+    }, timeout);
+
+    ws.addEventListener("open", () => {
+      ws.send(JSON.stringify({ type: "get-friends" }));
+    });
+
+    ws.addEventListener("message", (event) => {
+      const msg = JSON.parse(event.data);
+      if (msg.type === "friends-list") {
+        clearTimeout(timer);
+        ws.close();
+        resolve(msg.friends);
+      }
+    });
+
+    ws.addEventListener("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

package/mcp-server.js

@@ -0,0 +1,216 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getConfig, createConnection } from "./client.js";
+
+const config = getConfig();
+if (!config) {
+  console.error("Not set up. Run: claude-friends setup");
+  process.exit(1);
+}
+
+const username = config.username;
+
+// Persistent WebSocket connection — stays open while Claude Code is running
+const ws = createConnection(username);
+
+// Local cache of state, updated via WebSocket messages
+let friendsList = [];
+let pendingNudges = [];
+let lastError = null;
+
+// Promise-based request/response helper
+function request(msg, responseType, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("timeout")), timeout);
+    const handler = (event) => {
+      const data = JSON.parse(event.data);
+      if (data.type === responseType) {
+        clearTimeout(timer);
+        ws.removeEventListener("message", handler);
+        resolve(data);
+      } else if (data.type === "error") {
+        clearTimeout(timer);
+        ws.removeEventListener("message", handler);
+        resolve(data);
+      }
+    };
+    ws.addEventListener("message", handler);
+    ws.send(JSON.stringify(msg));
+  });
+}
+
+// Listen for incoming messages
+ws.addEventListener("message", (event) => {
+  const msg = JSON.parse(event.data);
+
+  switch (msg.type) {
+    case "state":
+      friendsList = msg.friends || [];
+      pendingNudges = msg.nudges || [];
+      break;
+    case "nudge":
+      pendingNudges.push({ from: msg.from, message: msg.message });
+      break;
+    case "friend-added":
+    case "friend-removed":
+      // Refresh friends list
+      ws.send(JSON.stringify({ type: "get-friends" }));
+      break;
+    case "friends-list":
+      friendsList = msg.friends || [];
+      break;
+    case "error":
+      lastError = msg.message;
+      break;
+  }
+});
+
+// Wait for connection before starting MCP
+await new Promise((resolve) => {
+  if (ws.readyState === 1) return resolve();
+  ws.addEventListener("open", resolve, { once: true });
+});
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: "claude-friends",
+  version: "0.1.0",
+});
+
+server.tool(
+  "friends-online",
+  "See which of your friends are currently online in Claude Code.",
+  {},
+  async () => {
+    const resp = await request({ type: "get-friends" }, "friends-list");
+    const friends = resp.friends || [];
+
+    if (friends.length === 0) {
+      return { content: [{ type: "text", text: "No friends yet. Use add-friend to add someone!" }] };
+    }
+
+    const sorted = [...friends].sort((a, b) => (b.online ? 1 : 0) - (a.online ? 1 : 0));
+    const onlineCount = sorted.filter((f) => f.online).length;
+
+    const lines = sorted.map((f) => {
+      const dot = f.online ? "🟢" : "⚫";
+      const status = f.status && f.status !== "offline" && f.status !== "unknown" ? ` — ${f.status}` : "";
+      const tokens = f.tokensUsed ? ` [${(f.tokensUsed / 1000).toFixed(1)}K tokens]` : "";
+      return `${dot} ${f.name}${status}${tokens}`;
+    });
+
+    return {
+      content: [{
+        type: "text",
+        text: `Friends (${onlineCount}/${friends.length} online):\n${lines.join("\n")}`,
+      }],
+    };
+  }
+);
+
+server.tool(
+  "add-friend",
+  "Add a friend by their username.",
+  { username: z.string().describe("The friend's username") },
+  async ({ username: friend }) => {
+    const resp = await request({ type: "add-friend", friend }, "friend-added");
+    if (resp.type === "error") {
+      return { content: [{ type: "text", text: resp.message }] };
+    }
+    return { content: [{ type: "text", text: `Added ${friend} as a friend!` }] };
+  }
+);
+
+server.tool(
+  "remove-friend",
+  "Remove a friend.",
+  { username: z.string().describe("The friend's username") },
+  async ({ username: friend }) => {
+    const resp = await request({ type: "remove-friend", friend }, "friend-removed");
+    return { content: [{ type: "text", text: `Removed ${friend}.` }] };
+  }
+);
+
+server.tool(
+  "set-status",
+  "Set your status so friends can see what you're working on.",
+  { status: z.string().describe("Your status, e.g. 'debugging auth flow'") },
+  async ({ status }) => {
+    ws.send(JSON.stringify({ type: "set-status", status }));
+    return { content: [{ type: "text", text: `Status set: "${status}"` }] };
+  }
+);
+
+server.tool(
+  "share-tokens",
+  "Share your token usage with friends.",
+  { tokens: z.number().describe("Tokens used this session") },
+  async ({ tokens }) => {
+    ws.send(JSON.stringify({ type: "share-tokens", tokens }));
+    return { content: [{ type: "text", text: `Sharing: ${tokens.toLocaleString()} tokens` }] };
+  }
+);
+
+server.tool(
+  "hide-tokens",
+  "Stop sharing token usage.",
+  {},
+  async () => {
+    ws.send(JSON.stringify({ type: "hide-tokens" }));
+    return { content: [{ type: "text", text: "Token usage hidden." }] };
+  }
+);
+
+server.tool(
+  "nudge",
+  "Send a nudge/message to a friend.",
+  {
+    username: z.string().describe("Friend to nudge"),
+    message: z.string().optional().describe("Optional message"),
+  },
+  async ({ username: friend, message }) => {
+    const resp = await request(
+      { type: "nudge", friend, message },
+      "nudge-sent"
+    );
+    if (resp.type === "error") {
+      return { content: [{ type: "text", text: resp.message }] };
+    }
+    return { content: [{ type: "text", text: `Nudge sent to ${friend}!` }] };
+  }
+);
+
+server.tool(
+  "check-nudges",
+  "Check if anyone has nudged you.",
+  {},
+  async () => {
+    const resp = await request({ type: "get-nudges" }, "nudges-list");
+    const nudges = resp.nudges || [];
+    if (nudges.length === 0) {
+      return { content: [{ type: "text", text: "No new nudges." }] };
+    }
+    const lines = nudges.map((n) => `💬 ${n.from}: ${n.message}`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+server.tool(
+  "my-profile",
+  "Show your username and status.",
+  {},
+  async () => {
+    return {
+      content: [{ type: "text", text: `🟢 ${username} (that's you)` }],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Cleanup
+process.on("SIGINT", () => { ws.close(); process.exit(0); });
+process.on("SIGTERM", () => { ws.close(); process.exit(0); });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "claude-friends",
+  "version": "0.1.0",
+  "description": "See who's online in Claude Code. Add friends, share status, nudge each other.",
+  "type": "module",
+  "bin": {
+    "claude-friends": "./cli.js"
+  },
+  "main": "mcp-server.js",
+  "scripts": {
+    "dev": "npx partykit dev",
+    "deploy": "npx partykit deploy"
+  },
+  "files": [
+    "cli.js",
+    "mcp-server.js",
+    "statusline.js",
+    "client.js"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "partysocket": "^1.0.3",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "partykit": "^0.0.111"
+  },
+  "keywords": ["claude", "claude-code", "mcp", "social", "presence", "friends"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandinitalwar/claude-friends"
+  }
+}

package/statusline.js

@@ -0,0 +1,23 @@
+// Lightweight status line for Claude Code
+// Connects, grabs friend count, prints one line, exits
+import { getConfig, queryFriends } from "./client.js";
+
+const config = getConfig();
+if (!config) {
+  process.stdout.write("○ friends: run claude-friends setup");
+  process.exit(0);
+}
+
+try {
+  const friends = await queryFriends(config.username, 3000);
+  const online = friends.filter((f) => f.online);
+  const dot = online.length > 0 ? "●" : "○";
+  const names = online.slice(0, 3).map((f) => f.name).join(", ");
+  const suffix = online.length > 3 ? "…" : "";
+  const nameStr = names ? ` (${names}${suffix})` : "";
+  process.stdout.write(`${dot} ${online.length} online${nameStr}`);
+} catch {
+  process.stdout.write("○ friends: offline");
+}
+
+process.exit(0);