agentmash 0.3.0

package/mcp/server.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+// AgentMash MCP server — "who is working on what?", answerable mid-plan.
+//
+// The hooks tell an agent about a collision at the moment it edits a file,
+// which is the last moment the answer can still be useful. This exposes the
+// same room over MCP so an agent can ask while it is still deciding what to
+// do.
+//
+// It is a stdio server that reuses the coordination server's existing HTTP
+// API and the hooks' config resolution, so there is no new endpoint, no new
+// credential, and nothing to keep in sync but the room id that already lives
+// in the repo.
+//
+// Nothing is ever written to stdout except JSON-RPC: that channel is the
+// protocol. Diagnostics go to stderr.
+
+import { pathToFileURL } from 'node:url';
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import crypto from 'node:crypto';
+
+import { buildReconciliationBrief, toRepoRelative } from '../hooks/lib.mjs';
+import { fetchJson, normalizePath, postJson, resolveCoordination } from './coordination.mjs';
+import {
+  renderClaimResult,
+  renderClaims,
+  renderCollisions,
+  renderContestedFiles,
+  renderPathActivity,
+  renderRelease,
+  renderResolved,
+  renderUnavailable,
+  renderWhoIsWorking,
+} from './render.mjs';
+
+/**
+ * Claims are held by a session, and this process is one. Claude Code does not
+ * hand its own session id to MCP servers, so the process mints its own: the
+ * hooks' session_end cannot release these, which is why the transport closing
+ * does (see start) and why every claim also carries a TTL.
+ */
+const SESSION_ID = `mcp-${crypto.randomBytes(8).toString('base64url')}`;
+/** Only a process that actually claimed something has anything to release on exit. */
+let claimedSomething = false;
+
+const NAME = 'agentmash';
+const VERSION = '0.1.0';
+
+/** One hour of context by default; a working day when asking about a path. */
+const DEFAULT_WINDOW_MIN = 60;
+const DEFAULT_PATH_WINDOW_MIN = 480;
+const MAX_WINDOW_MIN = 7 * 24 * 60; // the server prunes events after 7 days
+
+const INSTRUCTIONS = `AgentMash coordinates the coding agents of everyone working in this same repository. It
+reports who is active right now, what they said they are working on, which branch they are on, and which files
+they have edited — and it lets you claim the scope you are about to work on so their agents route around you.
+
+Use it while you are still planning, not after you have started editing. The point is to change what you do,
+not to explain a collision afterwards.
+
+The one habit that matters: before starting any task that touches more than a file or two, call claim_work with
+the paths you expect to change and a one-sentence description. If it reports an overlap, split the work — take
+what they have not claimed, or build on top of what they will land — instead of editing the same lines. When you
+finish, call release_claim. Claims expire on their own and end with your session, so forgetting is safe; claiming
+too broadly ("src") is not, because it tells your teammates nothing.
+
+When a collision has already happened — you and a teammate both changed the same file — AgentMash will stop you
+before you finish and hand you a reconciliation brief. You can also ask for it any time with get_collisions. Do
+the merge yourself, on this machine, preserving both intents; then call mark_resolved so the room knows it is
+settled and stops asking.
+
+who_is_working_on_what, has_anyone_touched, list_claims, list_contested_files and get_collisions only read. When
+the coordination server cannot be reached, every tool says so in as many words — never read a failure as "nobody
+is working on anything".`;
+
+const minutesField = (fallback, what) =>
+  z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_WINDOW_MIN)
+    .default(fallback)
+    .describe(
+      `How far back to look, in minutes (default ${fallback}${
+        fallback === 480 ? ', about a working day' : ''
+      }). ${what} Events older than 7 days are pruned by the server, so larger values stop helping.`
+    );
+
+const includeSelfField = z
+  .boolean()
+  .default(false)
+  .describe(
+    "Include this agent's own developer identity in the answer. Off by default, because you rarely need to be told what you yourself have been editing."
+  );
+
+const text = (body) => ({ content: [{ type: 'text', text: body }] });
+
+/**
+ * Resolved per call rather than once at startup: `agentmash init` may connect
+ * the repo while this process is already running, and a long-lived server that
+ * cached "not connected" would keep saying so for the rest of the session.
+ */
+function coordinationNow() {
+  const index = process.argv.indexOf('--repo');
+  const fromFlag = index !== -1 ? process.argv[index + 1] : null;
+  return resolveCoordination(process.env.CLAUDE_PROJECT_DIR || fromFlag || process.cwd());
+}
+
+/** Ask /activity once and hand the payload to a renderer, or explain why we could not. */
+async function activity(coordination, minutes, subject, render) {
+  const answer = await fetchJson(coordination, `/activity?minutes=${encodeURIComponent(minutes)}`);
+  if (!answer.ok) return text(renderUnavailable(coordination, answer, subject));
+  return text(render(answer.data, coordination));
+}
+
+export function createServer() {
+  const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS });
+  const annotations = { readOnlyHint: true, openWorldHint: true };
+
+  server.registerTool(
+    'who_is_working_on_what',
+    {
+      title: 'Who is working on what',
+      description: `Ask this repository's AgentMash room who else is working here right now: their name, what
+they told their agent they are doing, the branch they are on, and the files they have touched. Call it while
+you are still planning — before you decide which files to change, and especially when the request is broad
+enough to overlap with someone else ("refactor the auth layer", "add a migration", "clean up the API"). The
+answer is meant to change your plan: if a teammate is already reshaping a module, read their changes first or
+pick work that does not collide. If the coordination server cannot be reached, this says so explicitly; an
+empty room and an unreachable server are worded differently, so do not treat one as the other.`,
+      inputSchema: {
+        minutes: minutesField(DEFAULT_WINDOW_MIN, 'Someone idle for longer than this will not appear.'),
+        include_self: includeSelfField,
+      },
+      annotations,
+    },
+    async ({ minutes, include_self }) => {
+      const coordination = coordinationNow();
+      return activity(coordination, minutes, 'who else is working in this repo', (data) =>
+        renderWhoIsWorking(data, coordination, { minutes, includeSelf: include_self })
+      );
+    }
+  );
+
+  server.registerTool(
+    'has_anyone_touched',
+    {
+      title: 'Has anyone touched this path',
+      description: `Ask whether anyone on the team has recently edited a particular file, or anything inside a
+particular directory. Use it the moment you know which part of the repo your task lives in and while you can
+still change course — "has anyone touched this module today?" is exactly the question it answers. Takes a
+repo-relative path, either a file ("server/src/app.ts") or a directory ("server/src", "dashboard"), and
+reports who touched what, when, what their edit did, and the task they were on. A genuinely quiet path and an
+unreachable coordination server are worded differently, so do not read one as the other.`,
+      inputSchema: {
+        path: z
+          .string()
+          .min(1)
+          .max(1024)
+          .describe(
+            'Repo-relative path to a file or a directory, with forward slashes — for example "server/src/app.ts" or "server/src". A directory matches everything beneath it.'
+          ),
+        minutes: minutesField(
+          DEFAULT_PATH_WINDOW_MIN,
+          'Edits older than this will not appear.'
+        ),
+        include_self: includeSelfField,
+      },
+      annotations,
+    },
+    async ({ path, minutes, include_self }) => {
+      const coordination = coordinationNow();
+      // Agents hand over absolute paths as readily as relative ones; the room
+      // only ever stores repo-relative ones.
+      const target = normalizePath(toRepoRelative(coordination.projectDir, path));
+      if (!target) {
+        return text('`path` must be a repo-relative file or directory path, for example "server/src/app.ts".');
+      }
+      return activity(coordination, minutes, `recent activity under ${target}`, (data) =>
+        renderPathActivity(data, coordination, { target, minutes, includeSelf: include_self })
+      );
+    }
+  );
+
+  server.registerTool(
+    'list_contested_files',
+    {
+      title: 'List contested files',
+      description: `List the files in this repository that more than one person's agent has edited recently —
+the places where a collision has already begun. Use it when you are choosing where to work, before a refactor
+that spans several files, or whenever you want to know which parts of the codebase are currently crowded. An
+empty list and an unreachable coordination server are worded differently.`,
+      inputSchema: {
+        minutes: minutesField(
+          DEFAULT_WINDOW_MIN,
+          'A file last contested longer ago than this will not appear.'
+        ),
+      },
+      annotations,
+    },
+    async ({ minutes }) => {
+      const coordination = coordinationNow();
+      return activity(coordination, minutes, 'which files are contested', (data) =>
+        renderContestedFiles(data, coordination, { minutes })
+      );
+    }
+  );
+
+  // ── claims: say what you are taking, before you take it ──────────────────
+  const writeAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  };
+
+  server.registerTool(
+    'claim_work',
+    {
+      title: 'Claim work',
+      description: `Tell the room what you are about to work on, so other agents can route around you — and find
+out, before you write anything, whether someone has already claimed part of it. Call this at the start of any
+task that will touch more than a file or two, with the repo-relative paths you expect to change and a
+one-sentence description of the task. If the answer reports an OVERLAP, do not just carry on: split the work —
+take the files and symbols they have not claimed, or build on what they will land rather than changing it. A
+claim is stated intent, not a lock; it expires on its own, ends with your session, and is released early by
+release_claim. Claim what you will actually touch: a claim on "src" tells your teammates nothing.`,
+      inputSchema: {
+        task: z
+          .string()
+          .min(3)
+          .max(300)
+          .describe(
+            'What you are about to do, in one sentence, the way you would tell a teammate. Shown to every other agent that comes near this scope.'
+          ),
+        paths: z
+          .array(z.string().min(1).max(1024))
+          .min(1)
+          .max(50)
+          .describe(
+            'Repo-relative files or directories you expect to change, forward slashes. A directory claims everything beneath it.'
+          ),
+        symbols: z
+          .array(z.string().min(1).max(200))
+          .max(100)
+          .optional()
+          .describe(
+            'Exported names you expect to change or rename, if you know them. Lets a teammate three files away be warned when you reshape an interface they import.'
+          ),
+        ttl_minutes: z
+          .number()
+          .int()
+          .min(5)
+          .max(480)
+          .default(120)
+          .describe(
+            'How long the claim stands if you never release it (default 120). It is released early by release_claim and when your session ends.'
+          ),
+      },
+      annotations: writeAnnotations,
+    },
+    async ({ task, paths, symbols, ttl_minutes }) => {
+      const coordination = coordinationNow();
+      const rel = paths.map((p) => normalizePath(toRepoRelative(coordination.projectDir, p))).filter(Boolean);
+      if (rel.length === 0) {
+        return text('`paths` must contain at least one repo-relative file or directory, for example "server/src/app.ts".');
+      }
+      const answer = await postJson(coordination, '/claims', {
+        developer: coordination.developer,
+        session_id: SESSION_ID,
+        task,
+        paths: rel,
+        symbols,
+        ttl_minutes,
+      });
+      if (!answer.ok) return text(renderUnavailable(coordination, answer, 'whether this scope is already claimed'));
+      claimedSomething = true;
+      return text(renderClaimResult(answer.data, coordination, { paths: rel, task }));
+    }
+  );
+
+  server.registerTool(
+    'release_claim',
+    {
+      title: 'Release a claim',
+      description: `Release a claim you made with claim_work, once the work is done or you have decided not to do
+it. Pass the claim id to release one, or nothing to release every claim this session holds. Not releasing is
+safe — claims expire and end with your session — but releasing promptly lets a waiting teammate start sooner.`,
+      inputSchema: {
+        claim_id: z
+          .string()
+          .regex(/^claim_[A-Za-z0-9_-]+$/)
+          .optional()
+          .describe('The id claim_work returned. Omit to release every claim this session holds.'),
+      },
+      annotations: writeAnnotations,
+    },
+    async ({ claim_id }) => {
+      const coordination = coordinationNow();
+      const answer = await postJson(coordination, '/claims/release', {
+        developer: coordination.developer,
+        session_id: SESSION_ID,
+        ...(claim_id ? { claim_id } : {}),
+      });
+      if (!answer.ok) return text(renderUnavailable(coordination, answer, 'whether the claim was released'));
+      return text(renderRelease(answer.data, { claimId: claim_id }));
+    }
+  );
+
+  server.registerTool(
+    'list_claims',
+    {
+      title: 'List claims',
+      description: `List what other people's agents have claimed in this repository right now — the scopes they
+have said they are taking, and for what. Cheaper than reading their edits, because a claim exists before any
+edit does. Use it when choosing where to work. Nothing claimed and an unreachable server are worded differently.`,
+      inputSchema: { include_self: includeSelfField },
+      annotations,
+    },
+    async ({ include_self }) => {
+      const coordination = coordinationNow();
+      const answer = await fetchJson(coordination, '/claims');
+      if (!answer.ok) return text(renderUnavailable(coordination, answer, 'what is claimed right now'));
+      return text(renderClaims(answer.data, coordination, { includeSelf: include_self }));
+    }
+  );
+
+  // ── collisions: settle what the claim did not prevent ────────────────────
+  server.registerTool(
+    'get_collisions',
+    {
+      title: 'Get collisions',
+      description: `Which files you changed did a teammate also change? For each, this says who, when, on which
+branch, what they were working on, what their edit did, and which symbols you both touched — then how to
+reconcile: see their version, merge so both intents survive, and either open a pull request or commit
+directly, depending on how this room is configured. Call it before you finish a task, or whenever a merge is
+coming. The Stop hook asks the same question automatically as you finish; this lets you ask earlier. No
+collisions and an unreachable server are worded differently.`,
+      inputSchema: {
+        minutes: minutesField(DEFAULT_WINDOW_MIN, 'Edits older than this are not considered collisions.'),
+      },
+      annotations,
+    },
+    async ({ minutes }) => {
+      const coordination = coordinationNow();
+      const answer = await fetchJson(
+        coordination,
+        `/collisions?developer=${encodeURIComponent(coordination.developer)}&minutes=${encodeURIComponent(minutes)}`
+      );
+      if (!answer.ok) return text(renderUnavailable(coordination, answer, 'whether you have collided with anyone'));
+      return text(renderCollisions(answer.data, coordination, { minutes, brief: buildReconciliationBrief }));
+    }
+  );
+
+  server.registerTool(
+    'mark_resolved',
+    {
+      title: 'Mark a collision resolved',
+      description: `Tell the room a collision on a file is settled, so it stops prompting about it. Call it after
+you have reconciled: outcome "pr" with the pull request URL when this room needs a human to approve, "merged"
+when you committed the reconciled result directly, "no_conflict" when you checked and the two changes did not
+actually overlap, or "dismissed" when the team decided to leave it. The room will prompt again only if someone
+edits the file after this.`,
+      inputSchema: {
+        file_path: z
+          .string()
+          .min(1)
+          .max(1024)
+          .describe('Repo-relative path of the file whose collision you reconciled.'),
+        outcome: z
+          .enum(['pr', 'merged', 'no_conflict', 'dismissed'])
+          .describe('How it was settled. "pr" needs `url`.'),
+        url: z.string().url().optional().describe('The pull request URL, for outcome "pr".'),
+        note: z
+          .string()
+          .max(500)
+          .optional()
+          .describe('One sentence on what you kept from each side, for the people who will read the board.'),
+      },
+      annotations: writeAnnotations,
+    },
+    async ({ file_path, outcome, url, note }) => {
+      const coordination = coordinationNow();
+      const rel = normalizePath(toRepoRelative(coordination.projectDir, file_path));
+      if (!rel) return text('`file_path` must be a repo-relative path, for example "src/models/user.ts".');
+      const answer = await postJson(coordination, '/resolutions', {
+        developer: coordination.developer,
+        session_id: SESSION_ID,
+        file_path: rel,
+        outcome,
+        url,
+        note,
+      });
+      if (!answer.ok) return text(renderUnavailable(coordination, answer, 'whether the resolution was recorded'));
+      return text(renderResolved(answer.data, { filePath: rel, outcome, url }));
+    }
+  );
+
+  return server;
+}
+
+/**
+ * Best effort, bounded, and only if this process ever claimed anything: a
+ * session that is going away should not leave its name on a scope for the
+ * rest of a TTL.
+ */
+async function releaseOwnClaims() {
+  if (!claimedSomething) return;
+  claimedSomething = false;
+  const coordination = { ...coordinationNow(), timeoutMs: 1500 };
+  await postJson(coordination, '/claims/release', {
+    developer: coordination.developer,
+    session_id: SESSION_ID,
+  });
+}
+
+/**
+ * Serve on stdio. Exported because this process is not always the entry point:
+ * `agentmash mcp` and the committed launcher in .claude/agentmash/ both start
+ * the server by importing it, so that the way it is reached can change without
+ * the server itself knowing.
+ */
+export async function start() {
+  const server = createServer();
+  // The host ending the session is our session_end, and it arrives in one of
+  // three shapes: the transport closing, stdin ending, or a signal. All three
+  // are best effort — a host that calls TerminateProcess (Windows) delivers
+  // none of them — which is why every claim also carries a TTL.
+  server.server.onclose = () => {
+    void releaseOwnClaims();
+  };
+  process.stdin.once('end', () => {
+    void releaseOwnClaims();
+  });
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+      releaseOwnClaims().finally(() => process.exit(0));
+    });
+  }
+  await server.connect(new StdioServerTransport());
+}
+
+// Only run when executed directly, so tests can import createServer().
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  start().catch((err) => {
+    console.error('[agentmash-mcp] fatal:', err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agentmash",
+  "version": "0.3.0",
+  "description": "Let your team's Claude Code agents see each other's work",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "hooks",
+    "coordination",
+    "agents",
+    "multi-agent",
+    "team"
+  ],
+  "homepage": "https://github.com/dauletbekalim/agentmash#readme",
+  "bugs": {
+    "url": "https://github.com/dauletbekalim/agentmash/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dauletbekalim/agentmash.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agentmash": "./agentmash.mjs"
+  },
+  "files": [
+    "agentmash.mjs",
+    "hooks/",
+    "mcp/",
+    "clients/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync-hooks": "node sync-hooks.mjs",
+    "prepare": "node sync-hooks.mjs",
+    "test": "node --import tsx --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  }
+}