pi-teams 0.1.0 β†’ 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +50 -95
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,127 +1,82 @@
1
- # pi-teams
1
+ # pi-teams πŸš€
2
2
 
3
- Agent teams for `pi`, ported from `claude-code-teams-mcp`.
3
+ **pi-teams** turns your single Pi agent into a coordinated software engineering team. It allows you to spawn multiple "Teammate" agents in separate terminal panes that work autonomously, communicate with each other, and manage a shared task boardβ€”all mediated through **tmux**.
4
4
 
5
- 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.
5
+ ## πŸ›  Installation
6
6
 
7
- ## Features
8
-
9
- - **Team Orchestration**: Create named teams with isolated configurations.
10
- - **Agent Spawning**: Launch teammates in background `tmux` panes.
11
- - **Messaging Protocol**: Lead can send direct messages and instructions; teammates can reply and report progress.
12
- - **Shared Task List**: Track progress across the whole team with persistent task states (`pending`, `in_progress`, `completed`).
13
- - **Identity Awareness**: Agents know if they are a Lead or a Teammate and adjust their system prompts accordingly.
14
-
15
- ## Installation
7
+ Open your Pi terminal and type:
16
8
 
17
9
  ```bash
18
10
  pi install npm:pi-teams
19
11
  ```
20
12
 
21
- Or from GitHub:
22
-
23
- ```bash
24
- pi install github:burggraf/pi-teams
25
- ```
26
-
27
- ## Getting Started (Quick Start)
13
+ ---
28
14
 
29
- To get a team up and running, follow these steps:
15
+ ## 🌟 What can it do?
30
16
 
31
- 1. **Initialize your team**:
32
- "Start a new team called 'ui-refactor' for improving the React component architecture."
33
- 2. **Define your plan**:
34
- "Create tasks for 'refactor-header', 'add-storybooks', and 'update-theme'."
35
- 3. **Spawn a specialist**:
36
- "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."
37
- 4. **Follow progress**:
38
- "Check on 'storybook-expert'. Any updates? Show me the current task list."
17
+ - **Spawn Specialists**: Create agents like "Security Expert" or "Frontend Pro" to handle sub-tasks in parallel.
18
+ - **Shared Task Board**: Keep everyone on the same page with a persistent list of tasks and their status.
19
+ - **Agent Messaging**: Agents can send direct messages to each other and to you (the Team Lead) to report progress.
20
+ - **Autonomous Work**: Teammates automatically "wake up," read their instructions, and poll their inboxes for new work while idle.
21
+ - **Beautiful UI**: Optimized vertical splits in `tmux` with clear labels so you always know who is doing what.
39
22
 
40
- ## How to Use in Pi
23
+ ---
41
24
 
42
- 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.
25
+ ## πŸ’¬ How to use it (Examples)
43
26
 
44
- ### 1. Starting a New Team
45
- **You:** "Start a new team called 'backend-migration' for refactoring our auth service."
46
- - **Pi will:** Call `team_create("backend-migration", "Refactoring auth service")`.
27
+ You don't need to learn complex code commands. Just talk to Pi in plain English!
47
28
 
48
- ### 2. Adding Teammates
49
- **You:** "Spawn a teammate named 'security-audit' in the `./auth` directory. Their goal is to find any hardcoded secrets."
50
- - **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")`.
51
- - **In your terminal:** A new `tmux` pane will open running a fresh `pi` instance with those instructions.
29
+ ### 1. Start a Team
30
+ > **You:** "Create a team named 'my-app-audit' for reviewing the codebase."
52
31
 
53
- ### 3. Coordinating via Tasks
54
- **You:** "Create a task for 'security-audit' to check the `.env` handling and set it to 'in_progress'."
55
- - **Pi will:** Call `task_create` and then `task_update` to assign it to the teammate.
32
+ ### 2. Spawn a Teammate
33
+ > **You:** "Spawn a teammate named 'security-bot' in the current folder. Tell them to scan for hardcoded API keys."
56
34
 
57
- ### 4. Checking Progress
58
- **You:** "Check on 'security-audit'. Do they have any updates for me?"
59
- - **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).
35
+ ### 3. Assign a Task
36
+ > **You:** "Create a task for security-bot: 'Check the .env.example file for sensitive defaults' and set it to in_progress."
60
37
 
61
- ### 5. Managing the Team
62
- **You:** "List all tasks and show me the team config."
63
- - **Pi will:** Call `task_list` and `read_config` to give you a status overview.
38
+ ### 4. Check on Progress
39
+ > **You:** "How is the team doing? Check my inbox for any messages from security-bot."
64
40
 
65
- ## Teammate Experience
41
+ ### 5. Shut Down the Team
42
+ > **You:** "We're done. Shut down the team and close the panes."
66
43
 
67
- When a teammate is spawned:
68
- - A new `tmux` pane will open in your terminal.
69
- - The teammate agent will be running a `pi` session with its initial instructions.
70
- - The agent's status bar (if supported by your terminal) will indicate its role and team name.
71
- - It will automatically start by checking its inbox for initial tasks or additional context.
72
- - It will periodically check for new messages from the "Lead" agent.
44
+ ---
73
45
 
74
- ## Communication Flow
75
- 1. **Lead to Teammate**: Use `send_message`. The teammate is programmed to check their inbox.
76
- 2. **Teammate to Lead**: Teammates are instructed to use `send_message` with `recipient="team-lead"`.
77
- 3. **Checking Messages**: You can ask Pi "Read my messages" or "Check for new messages from the team".
46
+ ## πŸͺŸ Requirement: tmux
78
47
 
79
- ### Team Management
80
- - `team_create(team_name, description?)`: Initialize a new team.
81
- - `team_delete(team_name)`: Remove all team data and configuration.
82
- - `read_config(team_name)`: View the current team members and status.
48
+ To show multiple agents on one screen, **pi-teams** requires `tmux` (a terminal multiplexer).
83
49
 
84
- ### Teammate Operations
85
- - `spawn_teammate(team_name, name, prompt, cwd)`: Spawn a new `pi` agent in a `tmux` pane with specific instructions.
86
- - `check_teammate(team_name, agent_name)`: Check if an agent is still alive in `tmux` and see their unread message count.
87
- - `force_kill_teammate(team_name, agent_name)`: Forcibly terminate an agent's `tmux` pane and remove them from the team.
50
+ ### 1. Install tmux
51
+ - **macOS**: `brew install tmux`
52
+ - **Linux**: `sudo apt install tmux`
88
53
 
89
- ### Communication
90
- - `send_message(team_name, recipient, content, summary)`: Send a message to any team member.
91
- - `read_inbox(team_name, unread_only?)`: Check for incoming messages. Teammates use this to get their orders.
92
-
93
- ### Task Management
94
- - `task_create(team_name, subject, description)`: Add a new task to the team board.
95
- - `task_list(team_name)`: List all tasks and their owners/status.
96
- - `task_get(team_name, task_id)`: Get full details for a specific task.
97
- - `task_update(team_name, task_id, status?, owner?)`: Update status or assign/reassign a task.
98
-
99
- ## Troubleshooting
100
-
101
- - **Tmux not found**: Ensure `tmux` is installed on your system.
102
- - **Tmux pane doesn't open**: Make sure you have a `tmux` session active when spawning teammates.
103
- - **Pi not in path**: Teammates are spawned with the command `pi`. Ensure the `pi` binary is in your PATH.
104
- - **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/`.
105
-
106
- ## Safety and Concurrency
54
+ ### 2. How to run it
55
+ Before you start a team, you **must** be inside a tmux session. Simply type:
56
+ ```bash
57
+ tmux
58
+ ```
59
+ Then start `pi` inside that window.
107
60
 
108
- `pi-teams` is designed for high reliability in multi-agent environments:
61
+ ### 3. Navigating Panes (Vanilla tmux)
62
+ When your screen splits into multiple agents, you use "Prefix" commands to move around. By default, the prefix is **`Ctrl+b`**.
109
63
 
110
- - **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.
111
- - **Atomic Operations**: All state changes are wrapped in atomic file operations with automatic retries and exponential backoff.
112
- - **Identity Protection**: Teammate sessions are isolated with their own environment variables (`PI_TEAM_NAME`, `PI_AGENT_NAME`) and tailored system prompts.
113
- - **Tmux Integration**: Leverages `tmux` for robust process management and visual separation of agent activities.
64
+ - **Switch to next agent**: Press `Ctrl+b` then `o`.
65
+ - **Switch using arrows**: Press `Ctrl+b` then any **Arrow Key**.
66
+ - **How to Scroll**: Vanilla tmux does not use the mouse wheel by default.
67
+ 1. Press `Ctrl+b` then `[` to enter "Copy Mode".
68
+ 2. Use your **Arrow Keys** or **Page Up/Down** to scroll.
69
+ 3. Press `q` to exit scroll mode and go back to typing.
114
70
 
115
- ## Requirements
71
+ *Note: You can greatly improve this experience by enabling "mouse mode" in your `~/.tmux.conf` file.*
116
72
 
117
- - **tmux**: Must be installed on your system.
118
- - **pi**: The `pi` binary must be accessible in your environment.
73
+ ---
119
74
 
120
- ## Credits and Attribution
75
+ ## πŸ“œ Credits & Attribution
121
76
 
122
- 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.
77
+ This project is a port of the excellent [claude-code-teams-mcp](https://github.com/cs50victor/claude-code-teams-mcp) by [cs50victor](https://github.com/cs50victor).
123
78
 
124
- Special thanks to the original author for the architectural inspiration and for deep-diving into the agent coordination patterns that make this package possible.
79
+ We have adapted the original MCP coordination protocol to work natively as a **Pi Package**, adding features like auto-starting teammates, balanced vertical UI layouts, and automatic inbox polling to make the experience seamless for Pi users.
125
80
 
126
- ## License
81
+ ## πŸ“„ License
127
82
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-teams",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Agent teams for pi, ported from claude-code-teams-mcp",
5
5
  "repository": "github:burggraf/pi-teams",
6
6
  "author": "Mark Burggraf",