pi-teams 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# pi-teams
+
+Agent teams for `pi`, ported from `claude-code-teams-mcp`.
+
+This package implements a team protocol for agents working together on a project using shared task lists and messaging, mediated via `tmux`. It allows a "Lead" agent to spawn "Teammates", assign them tasks, and communicate via a persistent inbox system.
+
+## Features
+
+- **Team Orchestration**: Create named teams with isolated configurations.
+- **Agent Spawning**: Launch teammates in background `tmux` panes.
+- **Messaging Protocol**: Lead can send direct messages and instructions; teammates can reply and report progress.
+- **Shared Task List**: Track progress across the whole team with persistent task states (`pending`, `in_progress`, `completed`).
+- **Identity Awareness**: Agents know if they are a Lead or a Teammate and adjust their system prompts accordingly.
+
+## Installation
+
+```bash
+pi install npm:pi-teams
+```
+
+Or from GitHub:
+
+```bash
+pi install github:burggraf/pi-teams
+```
+
+## Getting Started (Quick Start)
+
+To get a team up and running, follow these steps:
+
+1.  **Initialize your team**:
+    "Start a new team called 'ui-refactor' for improving the React component architecture."
+2.  **Define your plan**:
+    "Create tasks for 'refactor-header', 'add-storybooks', and 'update-theme'."
+3.  **Spawn a specialist**:
+    "Spawn a teammate named 'storybook-expert' in the `packages/ui` directory. Their goal is to create Storybook stories for all components in the `src/components` directory."
+4.  **Follow progress**:
+    "Check on 'storybook-expert'. Any updates? Show me the current task list."
+
+## How to Use in Pi
+
+As a developer, you interact with `pi-teams` by giving natural language instructions to the pi agent. The agent will then use the underlying tools to execute your requests.
+
+### 1. Starting a New Team
+**You:** "Start a new team called 'backend-migration' for refactoring our auth service."
+- **Pi will:** Call `team_create("backend-migration", "Refactoring auth service")`.
+
+### 2. Adding Teammates
+**You:** "Spawn a teammate named 'security-audit' in the `./auth` directory. Their goal is to find any hardcoded secrets."
+- **Pi will:** Call `spawn_teammate("backend-migration", "security-audit", "Analyze all files in the current directory and find hardcoded secrets. Report back with a message to team-lead.", "./auth")`.
+- **In your terminal:** A new `tmux` pane will open running a fresh `pi` instance with those instructions.
+
+### 3. Coordinating via Tasks
+**You:** "Create a task for 'security-audit' to check the `.env` handling and set it to 'in_progress'."
+- **Pi will:** Call `task_create` and then `task_update` to assign it to the teammate.
+
+### 4. Checking Progress
+**You:** "Check on 'security-audit'. Do they have any updates for me?"
+- **Pi will:** Call `check_teammate` to see if they are active and `read_inbox` to see if they sent any messages back to you (the lead).
+
+### 5. Managing the Team
+**You:** "List all tasks and show me the team config."
+- **Pi will:** Call `task_list` and `read_config` to give you a status overview.
+
+## Teammate Experience
+
+When a teammate is spawned:
+- A new `tmux` pane will open in your terminal.
+- The teammate agent will be running a `pi` session with its initial instructions.
+- The agent's status bar (if supported by your terminal) will indicate its role and team name.
+- It will automatically start by checking its inbox for initial tasks or additional context.
+- It will periodically check for new messages from the "Lead" agent.
+
+## Communication Flow
+1. **Lead to Teammate**: Use `send_message`. The teammate is programmed to check their inbox.
+2. **Teammate to Lead**: Teammates are instructed to use `send_message` with `recipient="team-lead"`.
+3. **Checking Messages**: You can ask Pi "Read my messages" or "Check for new messages from the team".
+
+### Team Management
+- `team_create(team_name, description?)`: Initialize a new team.
+- `team_delete(team_name)`: Remove all team data and configuration.
+- `read_config(team_name)`: View the current team members and status.
+
+### Teammate Operations
+- `spawn_teammate(team_name, name, prompt, cwd)`: Spawn a new `pi` agent in a `tmux` pane with specific instructions.
+- `check_teammate(team_name, agent_name)`: Check if an agent is still alive in `tmux` and see their unread message count.
+- `force_kill_teammate(team_name, agent_name)`: Forcibly terminate an agent's `tmux` pane and remove them from the team.
+
+### Communication
+- `send_message(team_name, recipient, content, summary)`: Send a message to any team member.
+- `read_inbox(team_name, unread_only?)`: Check for incoming messages. Teammates use this to get their orders.
+
+### Task Management
+- `task_create(team_name, subject, description)`: Add a new task to the team board.
+- `task_list(team_name)`: List all tasks and their owners/status.
+- `task_get(team_name, task_id)`: Get full details for a specific task.
+- `task_update(team_name, task_id, status?, owner?)`: Update status or assign/reassign a task.
+
+## Troubleshooting
+
+- **Tmux not found**: Ensure `tmux` is installed on your system.
+- **Tmux pane doesn't open**: Make sure you have a `tmux` session active when spawning teammates.
+- **Pi not in path**: Teammates are spawned with the command `pi`. Ensure the `pi` binary is in your PATH.
+- **Storage Issues**: If team data is corrupted or you want a fresh start, you can manually delete the data at `~/.claude/teams/` and `~/.claude/tasks/`.
+
+## Safety and Concurrency
+
+`pi-teams` is designed for high reliability in multi-agent environments:
+
+- **Granular Locking**: Uses a per-file locking mechanism (`.filename.lock`) to ensure that concurrent reads and writes from multiple agents don't corrupt team state or task lists.
+- **Atomic Operations**: All state changes are wrapped in atomic file operations with automatic retries and exponential backoff.
+- **Identity Protection**: Teammate sessions are isolated with their own environment variables (`PI_TEAM_NAME`, `PI_AGENT_NAME`) and tailored system prompts.
+- **Tmux Integration**: Leverages `tmux` for robust process management and visual separation of agent activities.
+
+## Requirements
+
+- **tmux**: Must be installed on your system.
+- **pi**: The `pi` binary must be accessible in your environment.
+
+## Credits and Attribution
+
+This project is a port of [claude-code-teams-mcp](https://github.com/cs50victor/claude-code-teams-mcp) by [cs50victor](https://github.com/cs50victor). It adapts the core team orchestration protocol and shared task management concepts from the original MCP server to work natively within the `pi` ecosystem.
+
+Special thanks to the original author for the architectural inspiration and for deep-diving into the agent coordination patterns that make this package possible.
+
+## License
+MIT

package/extensions/index.ts

@@ -0,0 +1,361 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import * as paths from "../src/utils/paths";
+import * as teams from "../src/utils/teams";
+import * as tasks from "../src/utils/tasks";
+import * as messaging from "../src/utils/messaging";
+import { Member } from "../src/utils/models";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+
+export default function (pi: ExtensionAPI) {
+  const isTeammate = !!process.env.PI_AGENT_NAME;
+  const agentName = process.env.PI_AGENT_NAME || "team-lead";
+  const teamName = process.env.PI_TEAM_NAME;
+
+  pi.on("session_start", async (_event, ctx) => {
+    paths.ensureDirs();
+    if (isTeammate) {
+      ctx.ui.notify(`Teammate: ${agentName} (Team: ${teamName})`, "info");
+      // Use a shorter, more prominent status at the beginning if possible
+      ctx.ui.setStatus("00-pi-teams", `[${agentName.toUpperCase()}]`); 
+      
+      // Also set the tmux pane title for better visibility
+      try {
+        execSync(`tmux select-pane -T "${agentName}"`);
+      } catch (e) {
+        // ignore
+      }
+      
+      // Auto-trigger the first turn for teammates
+      setTimeout(() => {
+        pi.sendUserMessage(`I am starting my work as '${agentName}' on team '${teamName}'. Checking my inbox for instructions...`);
+      }, 1000);
+
+      // Periodically check for new messages when idle
+      setInterval(async () => {
+        if (ctx.isIdle() && teamName) {
+          const unread = await messaging.readInbox(teamName, agentName, true, false);
+          if (unread.length > 0) {
+            pi.sendUserMessage(`I have ${unread.length} new message(s) in my inbox. Reading them now...`);
+          }
+        }
+      }, 30000);
+    } else if (teamName) {
+      ctx.ui.setStatus("pi-teams", `Lead @ ${teamName}`);
+    }
+  });
+
+  let firstTurn = true;
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (isTeammate && firstTurn) {
+      firstTurn = false;
+      return {
+        systemPrompt: event.systemPrompt + `\n\nYou are teammate '${agentName}' on team '${teamName}'.\nYour lead is 'team-lead'.\nStart by calling read_inbox(team_name="${teamName}") to get your initial instructions.`,
+      };
+    }
+  });
+
+  // Tools
+  pi.registerTool({
+    name: "team_create",
+    label: "Create Team",
+    description: "Create a new agent team.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      description: Type.Optional(Type.String()),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const config = teams.createTeam(params.team_name, "local-session", "lead-agent", params.description);
+      return {
+        content: [{ type: "text", text: `Team ${params.team_name} created.` }],
+        details: { config },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "spawn_teammate",
+    label: "Spawn Teammate",
+    description: "Spawn a new teammate in a tmux pane.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      name: Type.String(),
+      prompt: Type.String(),
+      cwd: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      if (!teams.teamExists(params.team_name)) {
+        throw new Error(`Team ${params.team_name} does not exist`);
+      }
+
+      const member: Member = {
+        agentId: `${params.name}@${params.team_name}`,
+        name: params.name,
+        agentType: "teammate",
+        model: "sonnet",
+        joinedAt: Date.now(),
+        tmuxPaneId: "",
+        cwd: params.cwd,
+        subscriptions: [],
+        prompt: params.prompt,
+        color: "blue",
+      };
+
+      await teams.addMember(params.team_name, member);
+      await messaging.sendPlainMessage(params.team_name, "team-lead", params.name, params.prompt, "Initial prompt");
+
+      const piBinary = process.argv[1] ? `node ${process.argv[1]}` : "pi"; // Assumed on path
+      const cmd = `PI_TEAM_NAME=${params.team_name} PI_AGENT_NAME=${params.name} ${piBinary}`;
+      
+      let paneId = "";
+      try {
+        const tmuxCmd = `tmux split-window -h -dP -F "#{pane_id}" "cd ${params.cwd} && ${cmd}"`;
+        paneId = execSync(tmuxCmd).toString().trim();
+        execSync(`tmux select-layout even-horizontal`);
+      } catch (e) {
+        throw new Error(`Failed to spawn tmux pane: ${e}`);
+      }
+
+      // Update member with paneId
+      await teams.updateMember(params.team_name, params.name, { tmuxPaneId: paneId });
+
+      return {
+        content: [{ type: "text", text: `Teammate ${params.name} spawned in pane ${paneId}.` }],
+        details: { agentId: member.agentId, paneId },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "send_message",
+    label: "Send Message",
+    description: "Send a message to a teammate.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      recipient: Type.String(),
+      content: Type.String(),
+      summary: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      await messaging.sendPlainMessage(params.team_name, agentName, params.recipient, params.content, params.summary);
+      return {
+        content: [{ type: "text", text: `Message sent to ${params.recipient}.` }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "read_inbox",
+    label: "Read Inbox",
+    description: "Read messages from an agent's inbox.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      agent_name: Type.Optional(Type.String({ description: "Whose inbox to read. Defaults to your own." })),
+      unread_only: Type.Optional(Type.Boolean({ default: true })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const targetAgent = params.agent_name || agentName;
+      const msgs = await messaging.readInbox(params.team_name, targetAgent, params.unread_only);
+      return {
+        content: [{ type: "text", text: JSON.stringify(msgs, null, 2) }],
+        details: { messages: msgs },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_create",
+    label: "Create Task",
+    description: "Create a new team task.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      subject: Type.String(),
+      description: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const task = await tasks.createTask(params.team_name, params.subject, params.description);
+      return {
+        content: [{ type: "text", text: `Task ${task.id} created.` }],
+        details: { task },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_list",
+    label: "List Tasks",
+    description: "List all team tasks.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const taskList = await tasks.listTasks(params.team_name);
+      return {
+        content: [{ type: "text", text: JSON.stringify(taskList, null, 2) }],
+        details: { tasks: taskList },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_update",
+    label: "Update Task",
+    description: "Update a task's status or owner.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      task_id: Type.String(),
+      status: Type.Optional(StringEnum(["pending", "in_progress", "completed", "deleted"])),
+      owner: Type.Optional(Type.String()),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const updated = await tasks.updateTask(params.team_name, params.task_id, {
+        status: params.status as any,
+        owner: params.owner,
+      });
+      return {
+        content: [{ type: "text", text: `Task ${params.task_id} updated.` }],
+        details: { task: updated },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "team_delete",
+    label: "Delete Team",
+    description: "Delete a team and all its data.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const dir = paths.teamDir(params.team_name);
+      const tasksDir = paths.taskDir(params.team_name);
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true });
+      if (fs.existsSync(tasksDir)) fs.rmSync(tasksDir, { recursive: true });
+      return {
+        content: [{ type: "text", text: `Team ${params.team_name} deleted.` }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "read_config",
+    label: "Read Config",
+    description: "Read the current team configuration.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const config = await teams.readConfig(params.team_name);
+      return {
+        content: [{ type: "text", text: JSON.stringify(config, null, 2) }],
+        details: { config },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_get",
+    label: "Get Task",
+    description: "Get full details of a specific task by ID.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      task_id: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const task = await tasks.readTask(params.team_name, params.task_id);
+      return {
+        content: [{ type: "text", text: JSON.stringify(task, null, 2) }],
+        details: { task },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "force_kill_teammate",
+    label: "Force Kill Teammate",
+    description: "Forcibly kill a teammate's tmux target.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      agent_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const config = await teams.readConfig(params.team_name);
+      const member = config.members.find(m => m.name === params.agent_name);
+      if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
+      if (member.tmuxPaneId) {
+        try {
+          execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+        } catch (e) {
+          // ignore
+        }
+      }
+      await teams.removeMember(params.team_name, params.agent_name);
+      await tasks.resetOwnerTasks(params.team_name, params.agent_name);
+      return {
+        content: [{ type: "text", text: `${params.agent_name} has been stopped.` }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "check_teammate",
+    label: "Check Teammate",
+    description: "Check a single teammate's status.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      agent_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const config = await teams.readConfig(params.team_name);
+      const member = config.members.find(m => m.name === params.agent_name);
+      if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
+
+      let alive = false;
+      if (member.tmuxPaneId) {
+        try {
+          execSync(`tmux has-session -t ${member.tmuxPaneId}`);
+          alive = true;
+        } catch (e) {
+          alive = false;
+        }
+      }
+
+      const unreadCount = (await messaging.readInbox(params.team_name, params.agent_name, true, false)).length;
+
+      return {
+        content: [{ type: "text", text: JSON.stringify({ alive, unreadCount }, null, 2) }],
+        details: { alive, unreadCount },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "process_shutdown_approved",
+    label: "Process Shutdown Approved",
+    description: "Process a teammate's shutdown.",
+    parameters: Type.Object({
+      team_name: Type.String(),
+      agent_name: Type.String(),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const config = await teams.readConfig(params.team_name);
+      const member = config.members.find(m => m.name === params.agent_name);
+      if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
+      if (member.tmuxPaneId) {
+        try {
+          execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+        } catch (e) {
+          // ignore
+        }
+      }
+      await teams.removeMember(params.team_name, params.agent_name);
+      await tasks.resetOwnerTasks(params.team_name, params.agent_name);
+      return {
+        content: [{ type: "text", text: `${params.agent_name} removed from team.` }],
+      };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pi-teams",
+  "version": "0.1.0",
+  "description": "Agent teams for pi, ported from claude-code-teams-mcp",
+  "repository": "github:burggraf/pi-teams",
+  "author": "Mark Burggraf",
+  "license": "MIT",
+  "keywords": ["pi-package"],
+  "main": "extensions/index.ts",
+  "files": [
+    "extensions",
+    "skills",
+    "src",
+    "package.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "uuid": "^11.1.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": ["extensions/index.ts"],
+    "skills": ["skills"]
+  }
+}

package/skills/teams.md

@@ -0,0 +1,31 @@
+---
+description: Coordinate multiple agents working on a project using shared task lists and messaging via tmux or iTerm2.
+---
+
+# Agent Teams
+
+Coordinate multiple agents working on a project using shared task lists and messaging.
+
+## Workflow
+
+1.  **Create a team**: Use `team_create(team_name="my-team")`.
+2.  **Spawn teammates**: Use `spawn_teammate` to start additional agents. Give them specific roles and initial prompts.
+3.  **Manage tasks**: Use `task_create` to define work, and `task_update` to assign it to teammates.
+4.  **Communicate**: Use `send_message` to give instructions or receive updates. Teammates should use `read_inbox` to check for messages.
+5.  **Monitor**: Use `check_teammate` to see if they are still running and if they have sent messages back.
+
+## Teammate Instructions
+
+When you are spawned as a teammate:
+- Your status bar will show "Teammate: name @ team".
+- Always start by calling `read_inbox` to get your initial instructions.
+- Regularly check `read_inbox` for updates from the lead.
+- Use `send_message` to "team-lead" to report progress or ask questions.
+- Update your assigned tasks using `task_update`.
+
+## Best Practices for Teammates
+
+- **Update Task Status**: As you work, use `task_update` to set your tasks to `in_progress` and then `completed`.
+- **Frequent Communication**: Send short summaries of your work back to `team-lead` frequently.
+- **Context Matters**: When you finish a task, send a message explaining your results and any new files you created.
+- **Independence**: If you get stuck, try to solve it yourself first, but don't hesitate to ask `team-lead` for clarification.

package/src/utils/lock.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export async function withLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+  const lockFile = `${lockPath}.lock`;
+  let retries = 50;
+  while (retries > 0) {
+    try {
+      fs.writeFileSync(lockFile, process.pid.toString(), { flag: "wx" });
+      break;
+    } catch (e) {
+      retries--;
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+
+  if (retries === 0) {
+    throw new Error("Could not acquire lock");
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try {
+      fs.unlinkSync(lockFile);
+    } catch (e) {
+      // ignore
+    }
+  }
+}

package/src/utils/messaging.ts

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import { InboxMessage } from "./models";
+import { withLock } from "./lock";
+import { inboxPath } from "./paths";
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export async function appendMessage(teamName: string, agentName: string, message: InboxMessage) {
+  const p = inboxPath(teamName, agentName);
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  await withLock(p, async () => {
+    let msgs: InboxMessage[] = [];
+    if (fs.existsSync(p)) {
+      msgs = JSON.parse(fs.readFileSync(p, "utf-8"));
+    }
+    msgs.push(message);
+    fs.writeFileSync(p, JSON.stringify(msgs, null, 2));
+  });
+}
+
+export async function readInbox(
+  teamName: string,
+  agentName: string,
+  unreadOnly = false,
+  markAsRead = true
+): Promise<InboxMessage[]> {
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) return [];
+
+  return await withLock(p, async () => {
+    const allMsgs: InboxMessage[] = JSON.parse(fs.readFileSync(p, "utf-8"));
+    let result = allMsgs;
+
+    if (unreadOnly) {
+      result = allMsgs.filter(m => !m.read);
+    }
+
+    if (markAsRead && result.length > 0) {
+      for (const m of allMsgs) {
+        if (result.includes(m)) {
+          m.read = true;
+        }
+      }
+      fs.writeFileSync(p, JSON.stringify(allMsgs, null, 2));
+    }
+
+    return result;
+  });
+}
+
+export async function sendPlainMessage(
+  teamName: string,
+  fromName: string,
+  toName: string,
+  text: string,
+  summary: string,
+  color?: string
+) {
+  const msg: InboxMessage = {
+    from: fromName,
+    text,
+    timestamp: nowIso(),
+    read: false,
+    summary,
+    color,
+  };
+  await appendMessage(teamName, toName, msg);
+}

package/src/utils/models.ts

@@ -0,0 +1,45 @@
+export interface Member {
+  agentId: string;
+  name: string;
+  agentType: string;
+  model: string;
+  joinedAt: number;
+  tmuxPaneId: string;
+  cwd: string;
+  subscriptions: any[];
+  prompt?: string;
+  color?: string;
+  planModeRequired?: boolean;
+  backendType?: string;
+  isActive?: boolean;
+}
+
+export interface TeamConfig {
+  name: string;
+  description: string;
+  createdAt: number;
+  leadAgentId: string;
+  leadSessionId: string;
+  members: Member[];
+}
+
+export interface TaskFile {
+  id: string;
+  subject: string;
+  description: string;
+  activeForm?: string;
+  status: "pending" | "in_progress" | "completed" | "deleted";
+  blocks: string[];
+  blockedBy: string[];
+  owner?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface InboxMessage {
+  from: string;
+  text: string;
+  timestamp: string;
+  read: boolean;
+  summary?: string;
+  color?: string;
+}

package/src/utils/paths.ts

@@ -0,0 +1,29 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+export const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+export const TEAMS_DIR = path.join(CLAUDE_DIR, "teams");
+export const TASKS_DIR = path.join(CLAUDE_DIR, "tasks");
+
+export function ensureDirs() {
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR);
+  if (!fs.existsSync(TEAMS_DIR)) fs.mkdirSync(TEAMS_DIR);
+  if (!fs.existsSync(TASKS_DIR)) fs.mkdirSync(TASKS_DIR);
+}
+
+export function teamDir(teamName: string) {
+  return path.join(TEAMS_DIR, teamName);
+}
+
+export function taskDir(teamName: string) {
+  return path.join(TASKS_DIR, teamName);
+}
+
+export function inboxPath(teamName: string, agentName: string) {
+  return path.join(teamDir(teamName), "inboxes", `${agentName}.json`);
+}
+
+export function configPath(teamName: string) {
+  return path.join(teamDir(teamName), "config.json");
+}

package/src/utils/tasks.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TaskFile } from "./models";
+import { taskDir } from "./paths";
+import { teamExists } from "./teams";
+import { withLock } from "./lock";
+
+export function getTaskId(teamName: string): string {
+  const dir = taskDir(teamName);
+  const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
+  const ids = files.map(f => parseInt(path.parse(f).name, 10)).filter(id => !isNaN(id));
+  return ids.length > 0 ? (Math.max(...ids) + 1).toString() : "1";
+}
+
+export async function createTask(
+  teamName: string,
+  subject: string,
+  description: string,
+  activeForm = "",
+  metadata?: Record<string, any>
+): Promise<TaskFile> {
+  if (!subject || !subject.trim()) throw new Error("Task subject must not be empty");
+  if (!teamExists(teamName)) throw new Error(`Team ${teamName} does not exist`);
+
+  const dir = taskDir(teamName);
+  const lockPath = dir;
+
+  return await withLock(lockPath, async () => {
+    const id = getTaskId(teamName);
+    const task: TaskFile = {
+      id,
+      subject,
+      description,
+      activeForm,
+      status: "pending",
+      blocks: [],
+      blockedBy: [],
+      metadata,
+    };
+    fs.writeFileSync(path.join(dir, `${id}.json`), JSON.stringify(task, null, 2));
+    return task;
+  });
+}
+
+export async function updateTask(
+  teamName: string,
+  taskId: string,
+  updates: Partial<TaskFile>
+): Promise<TaskFile> {
+  const dir = taskDir(teamName);
+  const lockPath = path.join(dir, taskId);
+  const p = path.join(dir, `${taskId}.json`);
+
+  return await withLock(lockPath, async () => {
+    if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
+    const task: TaskFile = JSON.parse(fs.readFileSync(p, "utf-8"));
+    const updated = { ...task, ...updates };
+
+    if (updates.status === "deleted") {
+      fs.unlinkSync(p);
+      return updated;
+    }
+
+    fs.writeFileSync(p, JSON.stringify(updated, null, 2));
+    return updated;
+  });
+}
+
+export async function readTask(teamName: string, taskId: string): Promise<TaskFile> {
+  const dir = taskDir(teamName);
+  const p = path.join(dir, `${taskId}.json`);
+  if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
+  return await withLock(p, async () => {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  });
+}
+
+export async function listTasks(teamName: string): Promise<TaskFile[]> {
+  const dir = taskDir(teamName);
+  return await withLock(dir, async () => {
+    const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
+    const tasks: TaskFile[] = files
+      .map(f => {
+        const id = parseInt(path.parse(f).name, 10);
+        if (isNaN(id)) return null;
+        return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+      })
+      .filter(t => t !== null);
+    return tasks.sort((a, b) => parseInt(a.id, 10) - parseInt(b.id, 10));
+  });
+}
+
+export async function resetOwnerTasks(teamName: string, agentName: string) {
+  const dir = taskDir(teamName);
+  const lockPath = dir;
+
+  await withLock(lockPath, async () => {
+    const files = fs.readdirSync(dir).filter(f => f.endsWith(".json"));
+    for (const f of files) {
+      const p = path.join(dir, f);
+      const task: TaskFile = JSON.parse(fs.readFileSync(p, "utf-8"));
+      if (task.owner === agentName) {
+        task.owner = undefined;
+        if (task.status !== "completed") {
+          task.status = "pending";
+        }
+        fs.writeFileSync(p, JSON.stringify(task, null, 2));
+      }
+    }
+  });
+}

package/src/utils/teams.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TeamConfig, Member } from "./models";
+import { configPath, teamDir, taskDir } from "./paths";
+import { withLock } from "./lock";
+
+export function teamExists(teamName: string) {
+  return fs.existsSync(configPath(teamName));
+}
+
+export function createTeam(
+  name: string,
+  sessionId: string,
+  leadAgentId: string,
+  description = ""
+): TeamConfig {
+  const dir = teamDir(name);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tasksDir = taskDir(name);
+  if (!fs.existsSync(tasksDir)) fs.mkdirSync(tasksDir, { recursive: true });
+
+  const leadMember: Member = {
+    agentId: leadAgentId,
+    name: "team-lead",
+    agentType: "lead",
+    model: "unknown",
+    joinedAt: Date.now(),
+    tmuxPaneId: process.env.TMUX_PANE || "",
+    cwd: process.cwd(),
+    subscriptions: [],
+  };
+
+  const config: TeamConfig = {
+    name,
+    description,
+    createdAt: Date.now(),
+    leadAgentId,
+    leadSessionId: sessionId,
+    members: [leadMember],
+  };
+
+  fs.writeFileSync(configPath(name), JSON.stringify(config, null, 2));
+  return config;
+}
+
+function readConfigRaw(p: string): TeamConfig {
+  return JSON.parse(fs.readFileSync(p, "utf-8"));
+}
+
+export async function readConfig(teamName: string): Promise<TeamConfig> {
+  const p = configPath(teamName);
+  if (!fs.existsSync(p)) throw new Error(`Team ${teamName} not found`);
+  return await withLock(p, async () => {
+    return readConfigRaw(p);
+  });
+}
+
+export async function addMember(teamName: string, member: Member) {
+  const p = configPath(teamName);
+  await withLock(p, async () => {
+    const config = readConfigRaw(p);
+    config.members.push(member);
+    fs.writeFileSync(p, JSON.stringify(config, null, 2));
+  });
+}
+
+export async function removeMember(teamName: string, agentName: string) {
+  const p = configPath(teamName);
+  await withLock(p, async () => {
+    const config = readConfigRaw(p);
+    config.members = config.members.filter(m => m.name !== agentName);
+    fs.writeFileSync(p, JSON.stringify(config, null, 2));
+  });
+}
+
+export async function updateMember(teamName: string, agentName: string, updates: Partial<Member>) {
+  const p = configPath(teamName);
+  await withLock(p, async () => {
+    const config = readConfigRaw(p);
+    const m = config.members.find(m => m.name === agentName);
+    if (m) {
+      Object.assign(m, updates);
+      fs.writeFileSync(p, JSON.stringify(config, null, 2));
+    }
+  });
+}