Claude Team - Codebase Summary

Overview

Claude Team is organized as a monorepo with two main workspaces:

Root workspace: TypeScript CLI and core modules (src/)
Dashboard workspace: Next.js 15 web application (dashboard/)

Total codebase: ~131K tokens, 99 files across CLI, core, types, utilities, workflows, and dashboard.

Directory Structure

claude-team/
├── src/                          # TypeScript CLI & Core (2246 LOC)
│   ├── cli/                      # Command implementations
│   ├── core/                     # Business logic modules
│   ├── types/                    # Zod schemas & TypeScript types
│   └── utils/                    # Utility functions
├── workflows/                    # YAML workflow configs (1157 LOC)
│   ├── basic/                    # 3-agent workflow
│   └── duo/                      # 2-agent workflow
├── dashboard/                    # Next.js 15 web application
│   ├── app/                      # Next.js App Router
│   ├── components/               # React components
│   ├── hooks/                    # Custom hooks
│   ├── lib/                      # Client utilities
│   ├── contexts/                 # React contexts
│   ├── scripts/                  # Utility scripts
│   └── plans/                    # Feature reports
├── .claude/                      # Claude Code workflows
├── docs/                         # Project documentation
├── images/                       # Assets
└── [config files]                # Build & package config

Core Modules (src/)

cli/ - Command Implementations

File	Purpose	Lines
`ct.ts`	Main CLI entry point, workflow launcher, session management	400+
`ct-send.ts`	Send messages to agents, inter-agent communication	150+
`ct-list.ts`	List tmux sessions and active roles	100+
`ct-capture.ts`	Capture session transcript to file	120+
`ct-reminder.ts`	Set periodic reminders for agents	140+
`ct-save-session.ts`	Save session state to JSON	110+

Key Exports:

ct: Launch workflows, manage sessions
ct-send:
- ct-send -r ROLE "message" - Send to current session
- ct-send -s SESSION -r ROLE "message" - Send to specific session
ct-list: List sessions and roles
ct-capture: Capture transcripts
ct-reminder: ct-reminder --message "text" --interval 5m
ct-save-session: Save current state

core/ - Business Logic

workflow.ts (Workflow Orchestration)

export class WorkflowLoader {
  loadWorkflow(workflowPath: string): WorkflowConfig
  validateWorkflow(config: WorkflowConfig): void
}

export class WorkflowLauncher {
  launchWorkflow(config: WorkflowConfig, mode: 'new'|'resume'): Promise<void>
  buildClaudeCommand(role: string, settings: RoleSettings): string
  launchRole(role: string, mode: 'new'|'resume'): Promise<void>
}

Responsibilities:

Parse YAML workflow configs
Validate against Zod schemas
Build Claude CLI commands
Orchestrate multi-agent startup

config.ts (Configuration Management)

export class ConfigManager {
  loadConfig(path: string): Config
  mergeSettings(base: Config, user: Config): Config
  resolveEnv(config: Config): Config
}

Responsibilities:

Load and parse YAML configs
Merge user settings with defaults
Environment variable resolution
Settings profile loading

tmux.ts (Tmux Integration)

export class TmuxManager {
  sessionExists(sessionName: string): boolean
  createSession(config: WorkflowConfig): void
  sendCommand(sessionName: string, pane: string, cmd: string): void
  killSession(sessionName: string): void
  getSessionLayout(sessionName: string): Layout
}

Responsibilities:

Create tmux sessions with role panes
Send commands to panes
Kill sessions
Query session status
Handle pane layout

template.ts (Template Processing)

export class TemplateEngine {
  render(template: string, context: Record<string, any>): string
  renderFile(path: string, context: Record<string, any>): string
}

Responsibilities:

Process Handlebars templates
Inject role-specific context
Render workflow instructions
Generate role prompts

logger.ts (Logging)

export class Logger {
  info(message: string, data?: Record<string, any>): void
  error(message: string, error?: Error): void
  debug(message: string, data?: Record<string, any>): void
  warn(message: string): void
}

Responsibilities:

Structured JSON logging
Color-coded console output
File-based logging
Log level control

types/ - Type Definitions & Schemas

workflow.ts

// Zod schemas for YAML validation
export const RoleSchema: ZodType<Role>
export const WorkflowConfigSchema: ZodType<WorkflowConfig>
export const SessionConfigSchema: ZodType<SessionConfig>

// TypeScript types
export interface WorkflowConfig {
  name: string
  description?: string
  roles: Role[]
  session?: SessionConfig
  monitor?: MonitorConfig
}

export interface Role {
  name: string
  model: 'opus' | 'sonnet' | 'haiku'
  settingsProfile?: string
  panePercent?: number
}

config.ts

export interface Config {
  workflows: Record<string, WorkflowConfig>
  settings: Record<string, Settings>
  defaults: DefaultConfig
}

export interface Settings {
  model?: string
  temperature?: number
  maxTokens?: number
}

tmux.ts, template.ts, logger.ts

Type definitions for tmux operations
Template context types
Logger configuration types

utils/ - Utility Functions

env.ts (Environment Resolution)

export function getProjectDir(): string
export function getPackageDir(): string
export function getWorkflowDir(workflowName: string): string
export function resolveEnv(key: string, fallback?: string): string

Responsibilities:

Resolve project root directory
Find package installation directory
Build workflow file paths
Environment variable fallbacks

session.ts (Session Management)

export interface SessionState {
  sessionName: string
  workflowName: string
  roles: string[]
  createdAt: number
  lastActive: number
}

export function loadSession(sessionName: string): SessionState | null
export function saveSession(state: SessionState): void
export function getClaudeSession(workflowName: string): SessionState | null
export function claudeSessionExists(workflowName: string): boolean
export function clearSession(sessionName: string): void

Responsibilities:

Persist session state to JSON
Load session history
Query active sessions
Clean up sessions

Workflows (workflows/)

Structure

workflows/
├── basic/
│   ├── config.yaml          # Workflow definition
│   ├── workflow.md          # Workflow instructions
│   ├── role_conductor.yaml  # CONDUCTOR role prompt
│   ├── role_engineer.yaml   # ENGINEER role prompt
│   └── role_tester.yaml     # TESTER role prompt
└── duo/
    ├── config.yaml
    ├── workflow.md
    ├── role_lead.yaml
    └── role_dev.yaml

config.yaml Format

name: basic
description: "3-agent workflow: CONDUCTOR, ENGINEER, TESTER"

roles:
  - name: CONDUCTOR
    model: opus
    settingsProfile: conductor
    panePercent: 30
  - name: ENGINEER
    model: sonnet
    settingsProfile: engineer
    panePercent: 40
  - name: TESTER
    model: sonnet
    settingsProfile: tester
    panePercent: 30

session:
  layoutType: horizontal
  pingTarget: CONDUCTOR

monitor:
  file: docs/KANBAN.md
  name: KANBAN
  staleThreshold: 5

Role YAML Files

Each role has a YAML file containing:

Role description and responsibilities
Task prioritization rules
Communication protocols
Success criteria

Location: workflows/{workflow}/role_{name}.yaml

Dashboard (dashboard/)

Architecture

Next.js 15 App Router web application for real-time chat and monitoring.

app/ - Routes

Route	Purpose
`/`	Main chat interface (page.tsx)
`/api/chat/send`	Send message endpoint
`/api/chat/rephrase`	Rephrase message endpoint
`/api/responses/poll`	Poll response messages
`/api/responses/stream`	Stream response messages
`/api/sessions`	Session management
`/api/sessions/clear`	Clear session
`/api/workflow/config`	Get workflow config
`/api/soniox/config`	Soniox API configuration
`/api/tts/vieneu`	VieNeu TTS endpoint
`/api/tts/minimax`	MiniMax TTS endpoint
`/api/ttyd/start`	Start ttyd server
`/api/capture/stream`	Capture terminal stream

components/ - React Components

Component	Purpose
`chat-message.tsx`	Render chat messages with formatting
`chat-input.tsx`	Input field with send button
`navbar.tsx`	Top navigation bar
`terminal-pane.tsx`	Embed ttyd terminal
`voice-recording-modal.tsx`	Voice input modal
`gradient-orb.tsx`	Animated gradient background
`shortcuts-help-panel.tsx`	Keyboard shortcuts help
`suggestion-card.tsx`	Quick suggestion buttons

hooks/ - Custom React Hooks

Hook	Purpose
`use-speech-recognition.ts`	STT integration
`use-tts.ts`	TTS audio playback
`use-voice-mode.ts`	Voice mode state management

lib/ - Client Utilities

speech/ - Speech-to-text providers

web-speech-provider.ts: Browser Web Speech API
soniox-provider.ts: Soniox cloud API
factory.ts: Factory pattern provider selection
types.ts: Speech provider interfaces

tts/ - Text-to-speech providers

webspeech-provider.ts: Browser Web Speech API
vieneu-provider.ts: VieNeu Vietnamese TTS
minimax-provider.ts: MiniMax multilingual TTS
factory.ts: Factory pattern provider selection
types.ts: TTS provider interfaces

utils.ts - General utilities

formatMessage(): Format messages for display
parseMarkdown(): Convert markdown to React
generateSessionId(): Create unique session IDs

Key Features Map

1. Workflow Management

Files:

src/core/workflow.ts - Orchestration
src/types/workflow.ts - Schema validation
workflows/*/config.yaml - Configuration

Flow:

Load YAML config via WorkflowLoader
Validate against Zod schema
Create tmux session via TmuxManager
Launch Claude in each pane via WorkflowLauncher

2. Session Management

Files:

src/utils/session.ts - Session I/O
src/cli/ct-save-session.ts - Save state
dashboard/app/api/sessions - Session API

Flow:

Create/resume session
Track in-memory or JSON file
Query via session API
Persist on explicit save

3. Inter-Agent Communication

Files:

src/cli/ct-send.ts - Send messages (supports current or specific session)
src/core/tmux.ts - Pane messaging, environment variable queries
dashboard/app/api/chat/send - API endpoint

ct-send Features:

-r, --role <name>: Target role (required)
-s, --session <name>: Target session (optional, defaults to current)
Session discovery via tmux PROJECT_DIR environment variable

Flow:

User types message in dashboard or CLI
Dashboard calls /api/chat/send OR user runs ct-send
If session specified, queries tmux for PROJECT_DIR
Loads session data from project directory
Sends message to agent's tmux pane

4. Web Dashboard

Files:

dashboard/app/page.tsx - Main UI
dashboard/components/chat-*.tsx - Chat components
dashboard/lib/speech/ - STT/TTS factories

Features:

Real-time chat polling
Voice input (STT)
Voice output (TTS)
Terminal embedding (ttyd)
Workflow configuration display

5. Session Capture

Files:

src/cli/ct-capture.ts - Capture CLI
dashboard/app/api/capture/stream - Stream API

Flow:

Read tmux pane history
Format as markdown/text
Save to file or stream
Include message metadata

Dependencies

Runtime Dependencies

{
  "commander": "^12.1.0",      // CLI framework
  "js-yaml": "^4.1.0",         // YAML parsing
  "zod": "^3.23.8"             // Schema validation
}

Dashboard Dependencies

{
  "next": "15.0+",              // React framework
  "react": "18+",               // UI library
  "tailwindcss": "latest",      // CSS framework
  "soniox-sdk": "latest"        // STT provider (optional)
}

Build & Configuration

Build System

TypeScript Compilation:

tsc                              # Compile src/ → dist/
chmod +x dist/cli/*.js           # Make executables

Development:

tsx watch src/cli/ct.ts         # Watch mode with tsx

Formatting:

prettier --write "src/**/*.ts"   # Format code

Entry Points

CLI:

dist/cli/ct.js → ct command
dist/cli/ct-send.js → ct-send command
dist/cli/ct-list.js → ct-list command
dist/cli/ct-capture.js → ct-capture command
dist/cli/ct-reminder.js → ct-reminder command
dist/cli/ct-save-session.js → ct-save-session command

Dashboard:

dashboard/app/page.tsx → Root UI
dashboard/app/api/ → API endpoints

Code Organization Principles

1. Separation of Concerns

CLI (src/cli): Command parsing and routing
Core (src/core): Business logic
Types (src/types): Schemas and type definitions
Utils (src/utils): Reusable utilities

2. Type Safety

All configs validated with Zod
TypeScript strict mode enabled
Interface contracts at module boundaries

3. File Naming

kebab-case for files: ct-send.ts, use-voice-mode.ts
PascalCase for classes: WorkflowLoader, TmuxManager
camelCase for functions: loadWorkflow(), sendCommand()

4. Module Exports

// Each module exports public API
export class WorkflowLoader { /* ... */ }
export const loadWorkflow = async (path: string) => { /* ... */ }
export type WorkflowConfig = { /* ... */ }

Performance Characteristics

Startup Time

Workflow creation: ~1-2 seconds
Agent initialization: ~5-10 seconds per agent
Dashboard page load: ~500ms

Resource Usage

CLI process: ~20-30 MB
Each Claude instance: ~50-100 MB
tmux session overhead: ~2-5 MB

Scalability

Tested up to 10 agents in single session
Message batching recommended for >5 agents
Session files grow ~1 KB per message

Testing & Quality

Test Coverage

Current status: Unit tests in progress

Planned:

Config validation tests
Workflow parsing tests
Tmux integration tests
API endpoint tests
Component tests (React)

Code Quality Tools

yarn type-check               # TypeScript validation
prettier --check              # Code formatting
# No linter currently configured

Configuration Files

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "bundler"
  }
}

.prettierrc

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 4
}

package.json scripts

yarn build                    # Compile TypeScript
yarn dev                      # Watch mode
yarn type-check              # Type validation
yarn format                  # Format code
yarn start                   # Run CLI
yarn dashboard              # Run web app

Integration Points

Claude Code CLI

Invoked by: WorkflowLauncher.buildClaudeCommand()
Protocol: Spawn process in tmux pane
Environment: Role-specific prompt injection
Return: Agent's terminal output

tmux

Used by: TmuxManager class
Operations: Create sessions, send commands, query layout
Format: tmux send-keys protocol
Output: Capture via tmux capture-pane

External APIs

Soniox (Speech-to-text):

POST /api/transcribe - Transcribe audio
Configured via dashboard/app/api/soniox/config

VieNeu (Text-to-speech):

POST /api/tts - Convert text to speech
Vietnamese language optimized

MiniMax (Text-to-speech):

POST /api/synthesis - Convert text to speech
Multilingual support

Key Files by Function

Use Case	Key Files
Launch workflow	`src/cli/ct.ts`, `src/core/workflow.ts`
Send message	`src/cli/ct-send.ts`, `src/core/tmux.ts`
Manage config	`src/core/config.ts`, `src/types/workflow.ts`
Use dashboard	`dashboard/app/page.tsx`, `dashboard/components/chat-*.tsx`
Voice I/O	`dashboard/lib/speech/`, `dashboard/lib/tts/`
Capture session	`src/cli/ct-capture.ts`, `dashboard/app/api/capture/*`
Save state	`src/cli/ct-save-session.ts`, `src/utils/session.ts`

External Resources

GitHub: https://github.com/hongbietcode/claude-team
Documentation: See /docs directory
KANBAN: docs/KANBAN.md - Current task tracking

FilesExpand file tree

codebase-summary.md

Latest commit

History

codebase-summary.md

File metadata and controls

Claude Team - Codebase Summary

Overview

Directory Structure

Core Modules (src/)

cli/ - Command Implementations

core/ - Business Logic

workflow.ts (Workflow Orchestration)

config.ts (Configuration Management)

tmux.ts (Tmux Integration)

template.ts (Template Processing)

logger.ts (Logging)

types/ - Type Definitions & Schemas

workflow.ts

config.ts

tmux.ts, template.ts, logger.ts

utils/ - Utility Functions

env.ts (Environment Resolution)

session.ts (Session Management)

Workflows (workflows/)

Structure

config.yaml Format

Role YAML Files

Dashboard (dashboard/)

Architecture

app/ - Routes

components/ - React Components

hooks/ - Custom React Hooks

lib/ - Client Utilities

Key Features Map

1. Workflow Management

2. Session Management

3. Inter-Agent Communication

4. Web Dashboard

5. Session Capture

Dependencies

Runtime Dependencies

Dashboard Dependencies

Build & Configuration

Build System

Entry Points

Code Organization Principles

1. Separation of Concerns

2. Type Safety

3. File Naming

4. Module Exports

Performance Characteristics

Startup Time

Resource Usage

Scalability

Testing & Quality

Test Coverage

Code Quality Tools

Configuration Files

tsconfig.json

.prettierrc

package.json scripts

Integration Points

Claude Code CLI

tmux

External APIs

Key Files by Function

External Resources