From b0211e5e089f4143f9558af9e820080e36ed07bc Mon Sep 17 00:00:00 2001 From: iliya Date: Fri, 6 Mar 2026 16:02:33 +0200 Subject: [PATCH] feat: enhance README and UI components for improved user experience - Updated README to clarify that the app runs entirely locally and added a comprehensive table of contents. - Enhanced the description of the Claude Agent Teams UI to better convey its functionality and target audience. - Improved the SortableTab component to ensure immediate rendering of team colors based on available data. - Filtered out team lead members in the TeamDetailView to streamline member display. - Eagerly patched team data in the state management to improve UI responsiveness and data accuracy. --- README.md | 131 +++++--- mcp-server/README.md | 301 ++++++++++++++++++ .../components/layout/SortableTab.tsx | 7 +- .../components/team/TeamDetailView.tsx | 2 +- src/renderer/store/slices/teamSlice.ts | 20 ++ 5 files changed, 418 insertions(+), 43 deletions(-) create mode 100644 mcp-server/README.md diff --git a/README.md b/README.md index 1cb536fe..4c3bb632 100644 --- a/README.md +++ b/README.md @@ -14,53 +14,87 @@

- 100% free, open source. No API keys. No configuration. + 100% free, open source. No API keys. No configuration. Runs entirely locally.


+## Table of Contents + +- [What is this](#what-is-this) +- [Quick start](#quick-start) +- [Installation](#installation) +- [FAQ](#faq) +- [Development](#development) +- [Roadmap](#roadmap) +- [Links](#links) +- [Contributing](#contributing) +- [Security](#security) +- [License](#license) + +--- + ## What is this -A new approach to task management with AI agents. +**Claude Agent Teams UI** is a desktop app that turns Claude Code's "Orchestrate Teams" feature into a full task management experience. Create agent teams, watch them work on a kanban board, review their code changes, and stay in control — all running locally on your machine. -- **Assemble your team** — create agent teams with different roles that work autonomously in parallel -- **Agents talk to each other** — they communicate, create and manage their own tasks, and leave comments -- **Sit back and watch** — tasks change status on the kanban board while agents handle everything on their own -- **Review changes like in Cursor** — see what code each task changed, then approve, reject, or comment -- **Full tool visibility** — inspect exactly which tools an agent used to complete each task -- **Live process section** — see which agents are running processes and open URLs directly in the browser -- **Stay in control** — send a direct message to any agent, drop a comment on a task, or pick a quick action right on the kanban card whenever you want to clarify something or add new work +### Who is this for + +- **Developers** who want AI agents to handle tasks in parallel while they oversee progress +- **Teams** using Claude Code and needing a shared task board, code review workflow, and team messaging +- **Anyone** who wants to browse and analyze Claude Code session history without running agents + +### How it works + +1. **Create a team** — Define roles (e.g. lead, frontend, backend) and a provisioning prompt. The app spawns Claude Code sessions as autonomous team members. +2. **Tasks flow automatically** — Agents create tasks, assign each other, move cards, leave comments, and send messages. You see everything on the kanban board in real time. +3. **Review like in Cursor** — When a task is done, you see the diff, approve, reject, or request changes. Agents get notified and can fix issues. +4. **Stay in control** — Send a direct message to any agent, add a comment on a task, or use quick actions on cards whenever you need to clarify or add work. + +### Key features + +| Feature | Description | +|---------|-------------| +| **Kanban board** | Tasks move through columns as agents work. Drag-and-drop, filters, quick actions. | +| **Code review** | Full diff view per task. Approve, reject, or request changes. Agents get notified. | +| **Team messaging** | Agents send direct messages. Inbox, notifications, clarification flags. | +| **Tool visibility** | See exactly which tools agents used (Bash, Read, Edit, etc.) for each task. | +| **Live processes** | See which agents are running. Open URLs directly in the browser. | +| **Session analysis** | Deep breakdown of each Claude session: commands, reasoning, subprocesses. |
More features
-- **Recent tasks across projects** — browse the latest completed tasks from all your projects in one place -- **Deep session analysis** — detailed breakdown of what happened in each Claude session: bash commands, reasoning, subprocesses -- **Solo mode** — a one-member team: a single agent (regular claude process) that creates its own tasks, leaves comments, and shows live progress on the kanban board — saves tokens compared to a full team and can be expanded to a full team at any time -- **Advanced context monitoring system** — comprehensive breakdown of what consumes tokens at every step: user messages, Claude.md instructions, tool outputs, thinking text, and team coordination. Token usage, percentage of context window, and session cost are displayed for each category, with detailed views by category or size. -- **Smart task-to-log matching** — automatically links Claude session logs to specific tasks based on status change timestamps, even when a task moves back and forth between states -- **Zero-setup onboarding** — built-in Claude Code installation and authentication, ready to go out of the box -- **Built-in code editor** — edit project files with Git support and other essential features without leaving the app -- **Branch strategy control** — choose via prompt whether all agents work on a single branch or each gets its own git worktree -- **Team member stats** — global performance statistics for every member of the team -- **Attach code context** — reference files or code snippets in your messages, just like in Cursor -- **Notification system** — configurable alerts when tasks complete, agents need attention, or errors occur +- **Recent tasks across projects** — Browse the latest completed tasks from all your projects in one place +- **Solo mode** — One-member team: a single agent that creates its own tasks and shows live progress. Saves tokens; can expand to a full team anytime +- **Advanced context monitoring** — Token breakdown: user messages, CLAUDE.md, tool outputs, thinking text, team coordination. See usage, context window %, and cost per category +- **Smart task-to-log matching** — Links Claude session logs to tasks by status change timestamps, even when tasks move back and forth +- **Zero-setup onboarding** — Built-in Claude Code installation and authentication +- **Built-in code editor** — Edit project files with Git support without leaving the app +- **Branch strategy** — Choose via prompt: single branch or git worktree per agent +- **Team member stats** — Global performance statistics per member +- **Attach code context** — Reference files or snippets in messages, like in Cursor +- **Notification system** — Configurable alerts when tasks complete, agents need attention, or errors occur +- **MCP integration** — Built-in [mcp-server](./mcp-server) for Cursor, Claude Desktop, and other MCP clients. 13 tools for task CRUD, kanban, reviews, and messaging — see [mcp-server/README.md](./mcp-server/README.md)
---- +### Tech stack - ## Installation @@ -102,6 +136,8 @@ No prerequisites — Claude Code can be installed and configured directly from t +**System requirements:** macOS 10.15+, Windows 10+, or Linux (glibc 2.28+). Node.js is not required for the desktop app. + --- ## FAQ @@ -115,19 +151,19 @@ No. The app includes built-in installation and authentication — just launch an
Does it read or upload my code?
-No. Everything runs locally on your machine. The app reads Claude Code's session logs from ~/.claude/ — your source code is never sent anywhere. +No. Everything runs locally. The app reads Claude Code's session logs from ~/.claude/ — your source code is never sent anywhere.
Can agents communicate with each other?
-Yes. Agents send direct messages, create shared tasks, and leave comments — all coordinated automatically through Claude Code's team protocol. +Yes. Agents send direct messages, create shared tasks, and leave comments — all coordinated through Claude Code's team protocol.
Is it free?
-Yes, completely free and open source. The app itself requires no API keys or subscriptions. You only need a Claude Code plan from Anthropic to run agents. +Yes, completely free and open source. The app requires no API keys or subscriptions. You only need a Claude Code plan from Anthropic to run agents.
@@ -139,13 +175,13 @@ Yes. Every task shows a full diff view where you can accept, reject, or comment
What happens if an agent gets stuck?
-You can send a direct message to any agent at any time to course-correct, or stop and restart it from the process dashboard. If an agent needs your input, you'll get a notification and the task will be marked with a distinct badge on the board so you won't miss it. +Send a direct message to course-correct, or stop and restart from the process dashboard. If an agent needs your input, you'll get a notification and the task will show a distinct badge on the board.
Can I use it just to view past sessions without running agents?
-Yes. The app works as a session viewer too — browse, search, and analyze any Claude Code session history. +Yes. The app works as a session viewer — browse, search, and analyze any Claude Code session history.
@@ -172,9 +208,9 @@ pnpm install pnpm dev ``` -The app auto-discovers your Claude Code projects from `~/.claude/`. +The app auto-discovers Claude Code projects from `~/.claude/`. -#### Build for Distribution +### Build for distribution ```bash pnpm dist:mac:arm64 # macOS Apple Silicon (.dmg) @@ -184,32 +220,45 @@ pnpm dist:linux # Linux (AppImage/.deb/.rpm/.pacman) pnpm dist # macOS + Windows + Linux ``` -#### Scripts +### Scripts | Command | Description | |---------|-------------| | `pnpm dev` | Development with hot reload | | `pnpm build` | Production build | | `pnpm typecheck` | TypeScript type checking | +| `pnpm lint` | Lint (no auto-fix) | | `pnpm lint:fix` | Lint and auto-fix | +| `pnpm format` | Format code with Prettier | | `pnpm test` | Run all tests | | `pnpm test:watch` | Watch mode | | `pnpm test:coverage` | Coverage report | +| `pnpm test:coverage:critical` | Critical path coverage | | `pnpm check` | Full quality gate (types + lint + test + build) | +| `pnpm fix` | Lint fix + format | +| `pnpm quality` | Full check + format check + knip |
--- -## TODO +## Roadmap -- [ ] CLI runtime: Run not only on a local PC but in any headless/console environment (web UI), e.g. VPS, remote server, etc. +- [ ] CLI runtime: Run in headless/console environments (web UI), e.g. VPS, remote server - [ ] Visual workflow editor ([@xyflow/react](https://github.com/xyflow/xyflow)) for building and orchestrating agent pipelines with drag & drop - [ ] Install skills, MCP, and integrations via an intuitive UI, and only for selected agents - [ ] Planning mode to organize agent plans before execution -- [ ] Сurate what context each agent sees (files, docs, MCP servers, skills) +- [ ] Curate what context each agent sees (files, docs, MCP servers, skills) - [ ] Multi-model support: proxy layer to use other popular LLMs (GPT, Gemini, DeepSeek, Llama, etc.), including offline/local models -- [ ] + +--- + +## Links + +- [Homepage](https://github.com/777genius/claude_agent_teams_ui) +- [Releases](https://github.com/777genius/claude_agent_teams_ui/releases) +- [Issues](https://github.com/777genius/claude_agent_teams_ui/issues) +- [MCP Server](./mcp-server) — Use Claude Agent Teams UI tools from Cursor, Claude Desktop, and other MCP clients --- @@ -223,4 +272,4 @@ IPC handlers validate all inputs with strict path containment checks. File reads ## License -[MIT](LICENSE) +[AGPL-3.0](LICENSE) diff --git a/mcp-server/README.md b/mcp-server/README.md new file mode 100644 index 00000000..f6b0d7de --- /dev/null +++ b/mcp-server/README.md @@ -0,0 +1,301 @@ +# @claude-team/mcp-server + +**Model Context Protocol (MCP) server for managing Claude Agent Teams kanban board and tasks.** + +Exposes 13 tools so AI agents (Claude, Cursor, or any MCP-compatible client) can create tasks, manage the kanban board, conduct code reviews, and send messages — backed by the same `teamctl.js` CLI that powers the Claude Agent Teams UI desktop app. + +--- + +## Table of Contents + +- [Overview](#overview) +- [Relationship to Claude Agent Teams UI](#relationship-to-claude-agent-teams-ui) +- [Quick start](#quick-start) +- [Prerequisites](#prerequisites) +- [Installation](#installation) +- [Configuration](#configuration) +- [Tools Reference](#tools-reference) +- [Data Storage](#data-storage) +- [Development](#development) +- [Testing](#testing) +- [Troubleshooting](#troubleshooting) +- [License](#license) + +--- + +## Overview + +Implements the [Model Context Protocol](https://modelcontextprotocol.io/) over **stdio**. All operations are delegated to `teamctl.js`, which: + +- Stores task data as JSON under `~/.claude/tasks/{teamName}/` +- Stores team config under `~/.claude/teams/{teamName}/` +- Is installed automatically when you run Claude Agent Teams UI at least once + +### Use cases + +| Scenario | Description | +|----------|-------------| +| **Cursor / Claude Desktop** | Add the server to MCP config so AI assistants can create tasks, assign owners, move cards, and send messages without leaving the chat | +| **Automation scripts** | Programmatic interface to the same task board that Claude Code agents use | +| **Multi-agent workflows** | Multiple AI agents sharing one task board, coordinating via comments and messages | + +### Architecture + +``` +┌─────────────────────┐ stdio ┌──────────────────────┐ spawn ┌─────────────────┐ +│ MCP Client │ ◄────────────► │ @claude-team/ │ ◄────────────► │ teamctl.js │ +│ (Cursor, Claude, │ │ mcp-server │ │ ~/.claude/ │ +│ custom scripts) │ │ (FastMCP + 13 tools) │ │ tools/ │ +└─────────────────────┘ └──────────────────────┘ └─────────────────┘ +``` + +--- + +## Relationship to Claude Agent Teams UI + +| Component | Role | +|-----------|------| +| **Claude Agent Teams UI** | Desktop app (Electron). Visualizes sessions, kanban board, code review, team messaging. Installs `teamctl.js` on first run. | +| **teamctl.js** | CLI at `~/.claude/tools/teamctl.js`. Reads/writes task JSON, manages kanban, inboxes, reviews. Used by both the app and agents. | +| **@claude-team/mcp-server** | MCP server wrapping `teamctl.js` so Cursor, Claude Desktop, and other MCP clients can call the same operations as tools. | + +Agents in Claude Code use `teamctl.js` via Bash. Agents in Cursor or Claude Desktop use this MCP server. Both operate on the same data. + +--- + +## Quick start + +1. Run **Claude Agent Teams UI** at least once (installs `teamctl.js`) +2. Build the MCP server: `cd mcp-server && pnpm install && pnpm build` +3. Add to Cursor MCP config (`~/.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "claude-team-tools": { + "command": "node", + "args": ["/absolute/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"] + } + } +} +``` + +4. Restart Cursor. The 13 tools will appear for the AI assistant. + +--- + +## Prerequisites + +- **Node.js 20+** +- **Claude Agent Teams UI** run at least once (installs `teamctl.js` to `~/.claude/tools/teamctl.js`) + +If `teamctl.js` is missing, the server throws at startup: + +``` +teamctl.js not found at ~/.claude/tools/teamctl.js. +Make sure Claude Agent Teams UI has been run at least once, +or set the TEAMCTL_PATH environment variable. +``` + +--- + +## Installation + +### From the monorepo (development) + +```bash +cd mcp-server +pnpm install +pnpm build +``` + +### As a dependency + +```bash +pnpm add @claude-team/mcp-server +# or +npm install @claude-team/mcp-server +``` + +--- + +## Configuration + +### Cursor + +Add to `~/.cursor/mcp.json` or project `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "claude-team-tools": { + "command": "node", + "args": ["/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"] + } + } +} +``` + +With global install (`pnpm link` or `npm link`): + +```json +{ + "mcpServers": { + "claude-team-tools": { + "command": "team-mcp-server" + } + } +} +``` + +### Claude Desktop + +Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent: + +```json +{ + "mcpServers": { + "claude-team-tools": { + "command": "node", + "args": ["/absolute/path/to/mcp-server/dist/index.js"] + } + } +} +``` + +### Environment variables + +| Variable | Description | +|----------|-------------| +| `TEAMCTL_PATH` | Path to `teamctl.js` if not at `~/.claude/tools/teamctl.js` | + +--- + +## Tools Reference + +All tools require a `team` parameter (team name, folder under `~/.claude/teams/`). + +### Task CRUD + +| Tool | Description | +|------|-------------| +| `task_create` | Create a task. Optional: `owner`, `description`, `blocked_by`, `related`, `status`, `notify`, `from` | +| `task_get` | Get a task by ID. Returns full JSON (status, owner, comments, dependencies, work intervals, history) | +| `task_list` | List all tasks. Returns JSON array (filter internal tasks client-side if needed) | +| `task_set_status` | Set status: `pending` → `in_progress` → `completed` → `deleted`. Records work intervals | +| `task_set_owner` | Assign or unassign owner. Use `owner="clear"` to unassign. Optional: `notify`, `from` | + +### Task collaboration + +| Tool | Description | +|------|-------------| +| `task_comment` | Add a comment. Sends inbox notification to owner (unless commenter is owner). Optional: `from` | +| `task_link` | Link/unlink dependencies. Types: `blocked-by`, `blocks`, `related`. Bidirectional; circular deps rejected | +| `task_briefing` | Human-readable briefing for a member: their assigned tasks vs full board | +| `task_attach` | Attach a file. Modes: `copy`, `link`. MIME auto-detected (PNG, JPEG, GIF, WebP, PDF, ZIP). Max 20 MB | + +### Kanban board + +| Tool | Description | +|------|-------------| +| `kanban_move` | Move to `review` or `approved`, or `clear` from board. Moving to column sets status to `completed` | +| `kanban_reviewers` | Manage reviewers: `list` (JSON array), `add`, `remove` | + +### Code review + +| Tool | Description | +|------|-------------| +| `review_action` | `approve` — mark approved (optional comment, `notify_owner`). `request-changes` — remove from kanban, reset to `in_progress`, notify owner (comment required) | + +### Messaging + +| Tool | Description | +|------|-------------| +| `message_send` | Send inbox message to a member. Optional: `summary`, `from`. Triggers notifications | + +--- + +## Data Storage + +| Location | Contents | +|----------|----------| +| `~/.claude/tasks/{teamName}/` | Task JSON files (`1.json`, `2.json`, …) | +| `~/.claude/teams/{teamName}/` | Team config, kanban reviewers, inboxes | + +Task IDs are numeric (highwatermark). Team and member names must be safe path segments (no `.`, `..`, `/`, `\`, null bytes). + +--- + +## Development + +### Scripts + +| Command | Description | +|---------|-------------| +| `pnpm build` | Build with tsup → `dist/index.js` | +| `pnpm dev` | Run with tsx (no build) | +| `pnpm test` | Run Vitest tests | +| `pnpm test:watch` | Watch mode | +| `pnpm typecheck` | TypeScript check | + +### Project structure + +``` +mcp-server/ +├── src/ +│ ├── index.ts # FastMCP server, registers all tools +│ ├── teamctl-runner.ts # Spawns teamctl.js subprocess +│ ├── output-parser.ts # Parses JSON / "OK ..." from teamctl stdout +│ ├── schemas.ts # Zod schemas (team, taskId, member, etc.) +│ └── tools/ +│ ├── index.ts # registerAllTools() +│ ├── task-create.ts +│ ├── task-get.ts +│ ├── ... +│ └── message-send.ts +├── test/ +│ ├── tools/ # Per-tool tests +│ ├── teamctl-runner.test.ts +│ ├── output-parser.test.ts +│ └── schemas.test.ts +├── package.json +├── tsup.config.ts +└── vitest.config.ts +``` + +### Adding a new tool + +1. Create `src/tools/your-tool.ts` with `register(server, runner)` +2. Add to `ALL_TOOLS` in `src/tools/index.ts` +3. Add Zod parameters and map to `teamctl` CLI args +4. Use `parseJsonOutput`, `parseOkOutput`, or `parseTextOutput` from `output-parser.ts` +5. Add tests in `test/tools/your-tool.test.ts` + +--- + +## Testing + +Tests use a mock `ITeamctlRunner` (no real `teamctl.js` required): + +```bash +pnpm test +``` + +For integration tests with real `teamctl.js`, use the main app: `test/main/services/team/teamctl.test.ts`. + +--- + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| **teamctl.js not found** | Run Claude Agent Teams UI at least once, or set `TEAMCTL_PATH` | +| **Invalid team/member name** | Names: 1–128 chars, no `.`, `..`, `/`, `\`, null bytes | +| **MCP client not discovering tools** | Check server starts without errors; use absolute path in config; some clients require it | +| **Timeout errors** | Default 10s. Increase via `TeamctlRunnerOptions.timeoutMs` (code change) | + +--- + +## License + +Same as the parent project: [AGPL-3.0](../LICENSE). diff --git a/src/renderer/components/layout/SortableTab.tsx b/src/renderer/components/layout/SortableTab.tsx index 2f2e3f64..7fafcfd5 100644 --- a/src/renderer/components/layout/SortableTab.tsx +++ b/src/renderer/components/layout/SortableTab.tsx @@ -70,7 +70,12 @@ export const SortableTab = ({ const teamColor = useStore((s) => { if (tab.type !== 'team' || !tab.teamName) return null; const team = s.teamByName[tab.teamName]; - return team?.color ?? null; + if (team?.color) return team.color; + // Fallback: selectedTeamData may be available before teamByName is populated + if (s.selectedTeamName === tab.teamName && s.selectedTeamData?.config.color) { + return s.selectedTeamData.config.color; + } + return null; }); const teamColorSet = teamColor ? getTeamColorSet(teamColor) : null; diff --git a/src/renderer/components/team/TeamDetailView.tsx b/src/renderer/components/team/TeamDetailView.tsx index c4dffc6b..f80056e7 100644 --- a/src/renderer/components/team/TeamDetailView.tsx +++ b/src/renderer/components/team/TeamDetailView.tsx @@ -1662,7 +1662,7 @@ export const TeamDetailView = ({ teamName }: TeamDetailViewProps): React.JSX.Ele currentName={data.config.name} currentDescription={data.config.description ?? ''} currentColor={data.config.color ?? ''} - currentMembers={data.members} + currentMembers={data.members.filter((m) => m.agentType !== 'team-lead')} projectPath={data.config.projectPath} onClose={() => setEditDialogOpen(false)} onSaved={() => void selectTeam(teamName)} diff --git a/src/renderer/store/slices/teamSlice.ts b/src/renderer/store/slices/teamSlice.ts index 1ca674fc..c00da33a 100644 --- a/src/renderer/store/slices/teamSlice.ts +++ b/src/renderer/store/slices/teamSlice.ts @@ -602,6 +602,26 @@ export const createTeamSlice: StateCreator = (set, if (get().selectedTeamName !== teamName) { return; } + // Eagerly patch teamByName with color/displayName from detailed data + // so that tab color renders immediately without waiting for fetchTeams() + const prevByName = get().teamByName; + const existingEntry = prevByName[teamName]; + const configColor = data.config.color; + if (configColor && (!existingEntry || existingEntry.color !== configColor)) { + const patched: TeamSummary = existingEntry + ? { ...existingEntry, color: configColor, displayName: data.config.name || teamName } + : { + teamName, + displayName: data.config.name || teamName, + description: data.config.description ?? '', + color: configColor, + memberCount: data.members.length, + taskCount: 0, + lastActivity: null, + }; + set({ teamByName: { ...prevByName, [teamName]: patched } }); + } + set({ selectedTeamName: teamName, selectedTeamData: data,