claude-subagent-communication

cnguyen14/claude-subagent-communication

3.2

If you are the rightful owner of claude-subagent-communication and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Claude-Subagent-Communication MCP server facilitates persistent context and knowledge sharing for Claude Code sub-agents across sessions within projects.

Tools
5
Resources
0
Prompts
0

Claude-Subagent-Communication MCP

A Model Context Protocol (MCP) server that enables Claude Code sub-agents to maintain persistent context and share knowledge across sessions within individual projects.

Overview

The Claude-Subagent-Communication MCP solves the context isolation problem where each sub-agent starts without knowledge of previous work. It provides:

  • Context Continuity: Sub-agents inherit relevant knowledge from previous sessions
  • Pattern Reuse: Successful approaches are documented and reapplied
  • Reduced Redundancy: Avoid re-explaining project architecture and conventions
  • Learning Accumulation: Project knowledge grows over time
  • Agent-Aware Intelligence: Leverages actual sub-agents defined in .claude/agents/

Key Features

šŸ¤– Agent Management

  • Auto-detects agents from .claude/agents/*.md files
  • Automatically adds MCP access instructions to agent files
  • Tracks agent performance and specializations

šŸ§  Context Intelligence

  • Smart relevance scoring based on agent history and task keywords
  • Agent-specific context retrieval with cross-agent learning
  • Token-aware context formatting

šŸ“ Session Management

  • Template-based session creation and validation
  • Agent-specific session tracking and completion
  • Comprehensive session metadata extraction

šŸ”„ Pattern Management

  • Automatic pattern extraction from successful sessions
  • Cross-agent pattern sharing and evolution
  • Pattern applicability scoring and recommendations

šŸ“Š Performance Monitoring

  • Real-time system health checks
  • Agent performance analytics
  • Project statistics and insights

Installation & Setup

Prerequisites

One-Command Setup

# Production: Add from GitHub
claude mcp add --scope local claude-subagent-communication -- uvx --from git+https://github.com/cnguyen14/claude-subagent-communication claude-subagent-communication-mcp

# Local: Add from local directory (for development/testing)
claude mcp add --scope local claude-subagent-communication -- uvx --from /absolute/path/to/claude-subagent-communication claude-subagent-communication-mcp

# Alternative: Local development with uv run
git clone <repository-url>
cd claude-subagent-communication  
uv sync
claude mcp add --scope local claude-subagent-communication uv run python claude_subagent_communication_mcp/server.py

Verify Installation

# Check if server was added
claude mcp list

# Test server health  
claude mcp get claude-subagent-communication

Initialize Your Project

In any project directory where you want to use the MCP, open Claude Code and run:

Initialize project context for this repository

āš ļø IMPORTANT: After initialization, restart Claude Code for sub-agents to access the MCP tools.

This will:

  • Create the .claude/ directory structure
  • Detect existing agents in .claude/agents/
  • Add MCP instructions to agent files
  • Set up templates and configuration
  • Enhance Claude.md with context management protocol

Directory Structure

After initialization, your project will have:

project-root/
ā”œā”€ā”€ .claude/
ā”‚   ā”œā”€ā”€ agents/                  # Sub-agent definitions (auto-enhanced with MCP)
ā”‚   ā”‚   ā”œā”€ā”€ backend-dev.md      # Backend development specialist
ā”‚   ā”‚   ā”œā”€ā”€ frontend-dev.md     # Frontend development specialist
ā”‚   ā”‚   ā””ā”€ā”€ ...                 # Other agents
ā”‚   ā”œā”€ā”€ config.json             # MCP settings and agent metadata
ā”‚   ā”œā”€ā”€ context.md              # High-level project overview
ā”‚   ā”œā”€ā”€ sessions/               # Individual agent work logs
ā”‚   ā”‚   ā”œā”€ā”€ backend-dev-2025-08-17-14-30-user-auth.md
ā”‚   ā”‚   ā””ā”€ā”€ ...
ā”‚   ā”œā”€ā”€ patterns/               # Reusable approaches and solutions
ā”‚   ā”‚   ā”œā”€ā”€ auth-patterns.md
ā”‚   ā”‚   ā””ā”€ā”€ ...
ā”‚   ā”œā”€ā”€ summaries/              # Periodic knowledge rollups
ā”‚   ā””ā”€ā”€ templates/              # Standardized formats
ā”œā”€ā”€ Claude.md                   # Enhanced with MCP context management protocol
ā””ā”€ā”€ src/                        # Your actual project code

Usage

For Parent Agents

Before assigning tasks to sub-agents, use these tools:

// Scan available agents
const agents = await scan_agents();

// Get relevant context for a specific agent and task
const context = await get_relevant_context(
  "backend-dev",
  "Create user authentication endpoint", 
  ["src/auth/routes.py", "src/models/user.py"]
);

// Start a session for an agent
const session = await start_agent_session(
  "backend-dev",
  "Create user authentication endpoint",
  "creation"
);

For Sub-Agents

Sub-agents automatically have access to these tools (after MCP enablement):

// Get your work history
const history = await get_agent_history("backend-dev", 30, true);

// Search for relevant context
const searchResults = await search_context(
  "authentication JWT", 
  ["session", "pattern"],
  "backend-dev"
);

// Get applicable patterns for your current task
const patterns = await get_applicable_patterns(
  "backend-dev",
  "creation", 
  ["auth", "jwt", "middleware"]
);

// Save a new pattern you discovered
await save_pattern(
  "jwt-middleware-pattern",
  "Implementation approach for JWT authentication middleware",
  "backend-dev",
  "creation",
  ["jwt", "auth", "middleware"]
);

// Complete your session with learnings
await complete_session(session_id, completed_session_content);

MCP Tools Reference

Agent Management

  • scan_agents() - Detect agents from .claude/agents/
  • update_agent_instructions(agent_name) - Add MCP instructions to agent
  • ensure_all_agents_mcp_enabled() - Enable MCP for all agents
  • init_project_context() - Initialize directory structure

Context Retrieval

  • get_relevant_context(agent_name, task_description, files) - Get agent-specific context
  • search_context(query, content_types, agent_name, time_range) - Search all context

Session Management

  • start_agent_session(agent_name, task_description, domain) - Create new session
  • complete_session(session_id, session_data) - Save completed session
  • get_agent_history(agent_name, days, include_patterns) - Get agent work history

Pattern Management

  • save_pattern(name, content, agent, domain, keywords) - Save reusable pattern
  • get_applicable_patterns(agent_name, domain, keywords) - Find relevant patterns

Claude.md Enhancement

  • enhance_claude_md() - Upgrade Claude.md with MCP context management protocol
  • check_claude_md_status() - Check enhancement status and get recommendations

System Tools

  • get_system_status() - System health and diagnostics

Best Practices

For Project Setup

  1. Create agent definitions in .claude/agents/ before initialization
  2. Use descriptive agent names that reflect specializations
  3. Document agent capabilities and tech focus areas
  4. Run init_project_context() to set up the system
  5. Always restart Claude Code after initialization

For Agent Definitions

  • Include clear specialization descriptions
  • List relevant domains (creation, modification, analysis, etc.)
  • Specify technology focus areas
  • Document typical approaches and methodologies

For Session Management

  • Always call get_relevant_context() before starting work
  • Use descriptive task descriptions
  • Fill out all template sections completely
  • Document new patterns and approaches discovered
  • Mark completed tasks with [x] in checklists

For Pattern Development

  • Create patterns for any reusable approach
  • Use clear, descriptive pattern names
  • Include both successful approaches and failure cases
  • Document when and when NOT to use patterns
  • Update patterns as they evolve

Troubleshooting

MCP Server Not Appearing

  • Verify UV is installed: uv --version
  • Check that the server path is correct in MCP configuration
  • Restart Claude Code completely
  • Test server independently: uv run python claude_subagent_communication_mcp/server.py

Agent Detection Issues

  • Ensure .claude/agents/ directory exists
  • Verify agent files are in .md format
  • Check file permissions and access
  • Run scan_agents() to see detected agents

Sub-Agents Can't Access MCP Tools

  • Most common issue: Need to restart Claude Code after initialization
  • Check agent frontmatter has MCP tools listed in tools: section
  • Verify agents were updated with ensure_all_agents_mcp_enabled()

Context Retrieval Problems

  • Verify sessions and patterns directories exist
  • Check that sessions follow template format
  • Ensure adequate content for relevance scoring
  • Use search_context() for debugging

Performance Issues

  • Monitor session and pattern file counts
  • Check disk space in .claude/ directory
  • Review relevance scoring for efficiency
  • Consider archiving old sessions

Development Commands

# Install development dependencies
uv sync

# Run tests
uv run python -m pytest tests/

# Run server standalone for testing
uv run python claude_subagent_communication_mcp/server.py

# Check code style
uv run ruff check .

Contributing

This project follows the implementation plan outlined in the PRD. Key areas for contribution:

  1. Enhanced Relevance Scoring - Improve context selection algorithms
  2. Performance Optimization - Add caching and lazy loading
  3. Pattern Intelligence - Enhance pattern discovery and evolution
  4. Cross-Agent Learning - Improve knowledge sharing mechanisms
  5. Analytics and Insights - Add project analytics and recommendations

License

This project is part of the Claude Code ecosystem and follows Anthropic's usage guidelines.

Support

For issues and feature requests, please refer to the Claude Code documentation or file issues in the appropriate repository.