Skip to main content

Multi-Session Agent Development Guide

Overview​

This guide explains how to run multiple AI agent sessions in parallel without conflicts using CODITECT's agent system and CODI monitoring.

Agent Types​

🎯 CODITECT Agents (Primary - Strategic)​

Located in agents/coditect/:

  1. orchestrator - Multi-agent coordination, task distribution, quality gates
  2. rust-developer - Rust backend, API implementation, business logic
  3. frontend-developer - React/TypeScript UI, components, state management
  4. database-specialist - FoundationDB schemas, multi-tenant patterns
  5. cloud-architect - GCP infrastructure, CI/CD, deployment
  6. security-specialist - Authentication, hardening, vulnerability assessment
  7. testing-specialist - Test coverage (95%), TDD, integration tests
  8. monitoring-specialist - Observability, metrics, logging infrastructure
  9. qa-reviewer - Documentation quality, ADR compliance (40/40)
  10. ai-specialist - AI provider integration, MCP, routing

🤖 Claude Sub-Agents (Tactical - Deep Analysis)​

Located in agents/claude-subagents/:

Used by CODITECT agents for specialized analysis via Task tool delegation.

Starting Multiple Sessions​

1. Session Naming Convention​

# Format: [AGENT-TYPE]-SESSION-[DATE]-[SEQUENCE/PURPOSE]
export SESSION_ID="ORCHESTRATOR-SESSION-2025-09-21-01"
export SESSION_ID="RUST-DEVELOPER-SESSION-2025-09-21-API"
export SESSION_ID="FRONTEND-DEVELOPER-SESSION-2025-09-21-UI"

2. terminal Setup (Each Session)​

# terminal 1: Orchestrator
cd /home/halcasteel/v4
export SESSION_ID="ORCHESTRATOR-SESSION-$(date +%Y-%m-%d)-01"
source .codi/scripts/infrastructure/session-start-hook.sh
source .codi/scripts/set-session-identity.sh "$SESSION_ID"
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Starting orchestration session" "SESSION_START"

# terminal 2: Rust Developer  
cd /home/halcasteel/v4
export SESSION_ID="RUST-DEVELOPER-SESSION-$(date +%Y-%m-%d)-API"
source .codi/scripts/set-session-identity.sh "$SESSION_ID"
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Starting API development" "SESSION_START"

# terminal 3: Frontend Developer
cd /home/halcasteel/v4
export SESSION_ID="FRONTEND-DEVELOPER-SESSION-$(date +%Y-%m-%d)-UI"
source .codi/scripts/set-session-identity.sh "$SESSION_ID"
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Starting UI development" "SESSION_START"

3. Preventing Collisions​

File Ownership Claims​

Each agent should claim their working files:

# Rust Developer claims API files
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID claiming src/api/ for development" "FILE_CLAIM"

# Frontend Developer claims UI files  
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID claiming src/frontend/ for development" "FILE_CLAIM"

Check Active Sessions​

# See who's working where
grep "FILE_CLAIM" .codi/logs/codi-ps.log | tail -20
grep "SESSION_START" .codi/logs/codi-ps.log | tail -10

Coordination Protocol​

# Before modifying shared files
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Requesting coordination for shared file X" "COORDINATE"

# Hand off work
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: API endpoints complete, ready for frontend integration" "HANDOFF"

# Report conflicts
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: CONFLICT detected in shared config file" "CONFLICT"

Orchestrator Usage​

Starting an Orchestrator Session​

# The orchestrator coordinates other agents
export SESSION_ID="ORCHESTRATOR-SESSION-$(date +%Y-%m-%d)-MAIN"
source .codi/scripts/infrastructure/session-start-hook.sh
source .codi/scripts/set-session-identity.sh "$SESSION_ID"

# Log orchestration start
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Starting multi-agent orchestration" "ORCHESTRATE"

Task Distribution Example​

# Orchestrator assigns tasks
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Assigning authentication module to RUST-DEVELOPER-SESSION-01" "TASK_ASSIGN"
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Assigning login UI to FRONTEND-DEVELOPER-SESSION-01" "TASK_ASSIGN"

# Monitor progress
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Monitoring integration between API and UI teams" "MONITOR"

# Quality gates
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Enforcing 95% test coverage requirement" "QUALITY_GATE"

Delegation to Claude Sub-Agents​

When CODITECT agents need deep analysis:

# Example: Rust developer needs security review
Task(
    description="Security audit of authentication module",
    prompt="Review src/api/auth/ for OWASP compliance and multi-tenant isolation",
    subagent_type="security-specialist"
)

Session Lifecycle​

1. Session Start​

./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Starting work on [specific task]" "SESSION_START"

2. Progress Updates (Every 30 mins)​

./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Progress update - completed X, working on Y" "PROGRESS"

3. Session Handoff​

./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Handing off to [NEXT-SESSION] - [summary]" "HANDOFF"

4. Session End​

./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Session complete - [summary]" "SESSION_END"

Monitoring Tools​

Real-time Activity​

# Watch all agent activity
tail -f .codi/logs/codi-ps.log | jq '. | select(.actor.type == "agent")'

# Filter by session
tail -f .codi/logs/codi-ps.log | jq '. | select(.sessionId == "RUST-DEVELOPER-SESSION-01")'

Web Dashboard​

# Start web interface (if not already running)
cd .codi/tools && node api-server.js > server.log 2>&1 &

# Access tools
open http://localhost:8080/agent-dashboard.html
open http://localhost:8080/activity-timeline.html

Best Practices​

  1. Always Set Session Identity - Every terminal needs a unique SESSION_ID
  2. Claim Files Early - Prevent conflicts by claiming ownership
  3. Log Regularly - Progress updates every 30 minutes minimum
  4. Coordinate Shared Resources - Use COORDINATE action for shared files
  5. Use Orchestrator for Complex Tasks - Let orchestrator manage multi-agent workflows
  6. Delegate Specialized Analysis - Use Claude sub-agents for deep dives

Example: Three-Agent Workflow​

# terminal 1: Orchestrator plans the work
ORCHESTRATOR: "Breaking down user authentication feature into tasks"
ORCHESTRATOR: "Assigning backend to RUST-DEVELOPER"
ORCHESTRATOR: "Assigning frontend to FRONTEND-DEVELOPER"

# terminal 2: Rust Developer implements API
RUST-DEVELOPER: "Claiming src/api/auth/"
RUST-DEVELOPER: "Implementing JWT authentication"
RUST-DEVELOPER: "Tests passing, 96% coverage"

# terminal 3: Frontend Developer builds UI
FRONTEND-DEVELOPER: "Claiming src/frontend/pages/auth/"
FRONTEND-DEVELOPER: "Building login/register forms"
FRONTEND-DEVELOPER: "Integrating with API endpoints"

# Orchestrator monitors and coordinates
ORCHESTRATOR: "Integration test between API and UI"
ORCHESTRATOR: "Quality gate passed - ready for review"

Troubleshooting​

Session Conflicts​

# Check who owns a file
grep "FILE_CLAIM.*filename" .codi/logs/codi-ps.log | tail -5

# Request coordination
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Requesting ORCHESTRATOR coordination for conflict" "HELP"

Lost Session​

# Recover session identity
export SESSION_ID="[YOUR-PREVIOUS-SESSION-ID]"
./.codi/scripts/logging/actors/codi-log-ai.sh "$SESSION_ID: Session recovered, resuming work" "SESSION_RECOVER"

For individual agent capabilities, see the specific guides in agents/coditect/ and agents/claude-subagents/.