npm package: @jimmy2822/claude-code-sub-agents-mode
Description: TypeScript Clean Architecture Multi-Agent Framework for Claude Code CLI Integration
Author: Jimmy
Latest version: 3.0.0

# Claude Code Multi-Agent Framework

[![Version](https://img.shields.io/npm/v/@jimmy2822/claude-code-sub-agents-mode.svg)](https://www.npmjs.com/package/@jimmy2822/claude-code-sub-agents-mode)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)
[![Clean Architecture](https://img.shields.io/badge/Clean%20Architecture-✓-green.svg)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
[![License](https://img.shields.io/npm/l/@jimmy2822/claude-code-sub-agents-mode.svg)](https://github.com/jimmy2822/claude-code-sub-agents-mode/blob/main/LICENSE)

## 🚀 Version 3.0.0 - Complete TypeScript Rewrite with Clean Architecture

A sophisticated TypeScript-based multi-agent framework that coordinates specialized AI agents to execute complex development tasks using Claude Code CLI. Built with Clean Architecture principles for maximum maintainability and scalability.

## ✨ What's New in v3.0.0

- 🎯 **100% TypeScript**: Complete rewrite in TypeScript with strict type safety
- 🏗️ **Clean Architecture**: Domain-driven design with proper layer separation
- 🔄 **Intelligent Session Management**: Optimized Claude CLI session reuse
- 📊 **Real-time Monitoring**: WebSocket-based live updates and dashboard
- 🤖 **7 Specialized Agent Types**: Each with dedicated capabilities
- 💾 **Smart Resource Management**: Automatic session pooling and cleanup
- 🚫 **No Legacy Code**: Removed all old JavaScript implementations

## 📁 Clean Architecture Structure

```
src/
├── domain/              # Core business entities and rules
│   ├── entities/       # Project, Agent, Session entities
│   └── repositories/   # Repository interfaces
├── application/        # Application business logic
│   ├── use-cases/     # CreateProject, ApproveProject, etc.
│   └── services/      # ProjectAnalyzer, RequirementAnalyzer
├── infrastructure/     # External dependencies
│   ├── repositories/  # Data persistence implementations
│   └── external/      # Claude CLI integration
└── presentation/      # User interface layer
    ├── controllers/   # HTTP REST controllers
    └── websocket/     # Real-time WebSocket handlers
```

## 🚀 Quick Start

### Installation

```bash
npm install @jimmy2822/claude-code-sub-agents-mode
```

### Running the Application

```bash
# Build TypeScript
npm run build

# Start the server
npm start
```

The application will be available at:
- **Web Interface**: http://localhost:3011
- **API Dashboard**: http://localhost:3011/api/usage
- **WebSocket**: ws://localhost:3011/ws

## 🤖 Agent Types

| Agent Type | Specialization | Primary Tools |
|------------|---------------|---------------|
| **Requirements Analyst** | Requirement analysis, user stories | Read, Grep, WebSearch |
| **Solution Architect** | System design, architecture | Read, Grep, WebSearch |
| **Senior Full-Stack** | Complete implementation | All tools |
| **Frontend Specialist** | UI/UX implementation | Read, Write, Edit, Bash |
| **Backend Specialist** | API and server logic | Read, Write, Edit, Bash |
| **QA Engineer** | Testing and quality | Read, Bash, Grep |
| **DevOps Engineer** | Deployment, infrastructure | All tools |

## 📊 Key Features

### Intelligent Session Management
- Automatic session pooling per agent type
- Health monitoring (age, tokens, requests)
- Smart selection based on task complexity
- Auto-cleanup every 5 minutes
- Uses `claude --resume` for session continuation

### Project Management
- Create and analyze project requirements
- Automatic complexity assessment
- Agent assignment based on requirements
- Real-time progress tracking
- Persistent project storage

### Clean Architecture Benefits
- **Separation of Concerns**: Each layer has a single responsibility
- **Testability**: Business logic isolated from external dependencies
- **Maintainability**: Changes in one layer don't affect others
- **Dependency Rule**: Dependencies only point inward
- **Type Safety**: Full TypeScript coverage with strict mode

## 🛠️ Development

### Prerequisites
- Node.js 18+
- TypeScript 5.5+
- Claude Code CLI (authenticated)

### Build Commands

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run build:watch

# Type checking
npm run typecheck

# Clean build
npm run clean
```

## 📚 API Documentation

### REST Endpoints

- `GET /api/status` - Get system status and projects
- `POST /api/projects` - Create new project
- `POST /api/projects/:id/approve` - Approve project
- `DELETE /api/project/:id` - Delete single project
- `DELETE /api/projects/all` - Delete all projects
- `GET /api/usage` - Get usage statistics

### WebSocket Events

- `analyze-requirements` - Submit new requirement
- `approve-breakdown` - Approve project breakdown
- `start-execution` - Start project execution
- `get-status` - Get current status

## 🔧 Configuration

The system uses intelligent defaults but can be configured through environment variables:

```bash
PORT=3011                    # Server port
MAX_SESSION_AGE=1800000     # 30 minutes
MAX_TOKENS_PER_SESSION=100000
DAILY_TOKEN_LIMIT=200000
```

## 📈 Performance

- **Session reuse rate**: > 80%
- **Average tokens/session**: < 50,000
- **Response time**: < 200ms
- **WebSocket latency**: < 50ms
- **TypeScript compilation**: < 5s

## 🔐 Security

- No API keys stored in code
- Session isolation per agent
- Automatic session cleanup
- Secure WebSocket connections
- Type-safe data validation

## 🚀 Migration from v2.x

Version 3.0.0 is a complete rewrite. Key changes:

1. **TypeScript Required**: The entire codebase is now TypeScript
2. **New Architecture**: Clean Architecture with proper layer separation
3. **Breaking Changes**: API remains compatible but internals completely changed
4. **No Legacy Support**: All old JavaScript code removed

To migrate:
1. Update to v3.0.0: `npm update @jimmy2822/claude-code-sub-agents-mode@latest`
2. Rebuild: `npm run build`
3. Start: `npm start`

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details

## 🤝 Contributing

Contributions are welcome! Please ensure:
- All code is TypeScript
- Follows Clean Architecture principles
- Includes proper type definitions
- Passes type checking

## 📧 Support

For issues and questions:
- GitHub Issues: [Report Issue](https://github.com/jimmy2822/claude-code-sub-agents-mode/issues)
- Email: jimmy2822@gmail.com

## 🏆 Acknowledgments

Built with ❤️ using:
- [TypeScript](https://www.typescriptlang.org/)
- [Express.js](https://expressjs.com/)
- [WebSocket](https://github.com/websockets/ws)
- [Claude Code CLI](https://claude.ai/code)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

---

**Version 3.0.0** - Complete TypeScript rewrite with Clean Architecture
*Released: August 2025*