Project-Claude Session Management System Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Enable dedicated tmux Claude sessions per business project, managed by Jarvis, with a communication protocol between Jarvis and project-Claudes, health monitoring via LaunchAgent, and progressive workload delegation.

Architecture: Each project gets a tmux session running claude --teammate-mode in-process --chrome from the project's directory, inheriting that project's CLAUDE.md context. Communication flows through the existing Worker API (POST /prompt with session parameter) for Jarvis-to-project messaging, and a lightweight file-based reply protocol for project-to-Jarvis responses. A LaunchAgent runs every 30 minutes to verify session health and auto-recover downed sessions.

Tech Stack: Bash (spawn/health scripts), Node.js/Fastify (Worker API extensions), macOS LaunchAgent (plist), tmux

Current State Analysis

Existing Infrastructure

Already working:

Worker process (projects/jarvis-system/apps/worker/) runs on port 5555
POST /prompt endpoint accepts session parameter to target any tmux session by name
TmuxSession class handles session lifecycle: isAlive(), ensureSession(), injectPrompt(), captureOutput()
Multi-bot support: BOT1-BOT10 env vars, each with TMUX_SESSION, TARGET_DIR, LAUNCH_CMD
contents-builder is already running as a project-Claude session (BOT6, separate directory)
start-vice-claude.sh — template for session spawning
vp_prompt_inject.sh — template for prompt injection
vice-reply.sh — template for reply/reporting protocol

Current tmux sessions:

vice-claude — Jarvis (Musk VP's managed session), CWD: business-builder/
contents-builder — IU (content specialist), CWD: contents-builder/

Key patterns from contents-builder (existing project-Claude):

Has its own CLAUDE.md with role, communication rules, telegram scripts
Uses ceo-reply.sh (2nd arg = bot name) for CEO replies
Uses vice-reply.sh (3rd arg = prefix emoji) for VP reports
Bot token mapped in worker .env as BOT6_*
No Jarvis-to-IU direct communication protocol exists yet

Communication Gap

Currently there is no protocol for Jarvis <-> project-Claude bidirectional communication. The CEO talks to each bot via Telegram (separate bot tokens), and VP wakes Jarvis via OpenClaw. But Jarvis cannot instruct project-Claudes, and project-Claudes cannot report back to Jarvis.

Design Decisions

D1: Communication Protocol — Hybrid (Worker API + File-based)

Jarvis -> Project-Claude: Use existing Worker POST /prompt with session parameter.

Already works, battle-tested, handles session recovery
Example: curl -X POST localhost:5555/prompt -d '{"text":"SEO 블로그 3편 작성","session":"richbukae-claude"}'

Project-Claude -> Jarvis: File-based message drop with vice-claude tmux injection.

Project-Claude writes a response file to memory/project-messages/{session-name}/{timestamp}.md
Then injects a notification to vice-claude tmux session via vp_prompt_inject.sh
Script: scripts/project-reply.sh "메시지" "프로젝트명"

Rationale: Worker API already exists for inbound. File-based is simplest for outbound since both sessions are on the same machine. No new server endpoints needed.

D2: Session Lifecycle — On-demand with Registry

Sessions are spawned by Jarvis when needed and stopped when idle. A JSON registry file tracks configured sessions.

Registry file: config/project-sessions.json

{
  "sessions": [
    {
      "name": "richbukae-claude",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/richbukae-store",
      "auto_start": false,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "🛍️ [리치부캐]",
      "description": "richbukae.com e-commerce project"
    }
  ]
}

Why not always-on: Claude sessions consume API credits even when idle. On-demand saves cost. The LaunchAgent only monitors sessions that are supposed to be running (checked against registry auto_start flag).

D3: LaunchAgent Health Check — 30-minute interval

A single plist that runs scripts/healthcheck-project-sessions.sh every 1800 seconds. The script reads the registry, checks which sessions should be alive, and restarts any that are down.

D4: Project CLAUDE.md Template

Each project-Claude gets instructions for:

Its role and project scope
How to reply to Jarvis (via project-reply.sh)
How to reply to CEO (via ceo-reply.sh)
What it should NOT do (no cross-project work, no DB schema changes)

Implementation Tasks

Task 1: Create project-reply.sh (Project-Claude -> Jarvis communication)

Files:

Create: scripts/project-reply.sh

Step 1: Write the script

#!/bin/bash
set -euo pipefail
# Project-Claude → Jarvis 메시지 전달 스크립트
# 프로젝트 Claude가 자비스에게 결과/상태 보고할 때 사용
#
# 사용법:
#   ./scripts/project-reply.sh "메시지 내용" "프로젝트명"
#   → vice-claude tmux 세션에 메시지 주입 + 로컬 로그 저장

TEXT="${1:-}"
PROJECT="${2:-unknown}"
TIMESTAMP=$(date +"%Y-%m-%d-%H%M")

if [ -z "$TEXT" ]; then
  echo "Usage: ./scripts/project-reply.sh \"메시지 내용\" \"프로젝트명\""
  exit 1
fi

PROJECT_ROOT="/Users/nbs22/(Claude)/(claude).projects/business-builder"
MSG_DIR="${PROJECT_ROOT}/memory/project-messages/${PROJECT}"
mkdir -p "$MSG_DIR"

# 1) 로컬 메시지 로그 저장
FILENAME="${TIMESTAMP}.md"
cat > "${MSG_DIR}/${FILENAME}" <<MDEOF
# Project Message: ${PROJECT}
**Date:** $(date +"%Y-%m-%d %H:%M")
**From:** ${PROJECT}

## Content
${TEXT}
MDEOF

echo "[1/2] 메시지 로그 저장: memory/project-messages/${PROJECT}/${FILENAME}"

# 2) vice-claude tmux 세션에 알림 주입
JARVIS_SESSION="vice-claude"
INJECT_TEXT="[PROJECT-REPLY:${PROJECT}] ${TEXT}"

if tmux has-session -t "$JARVIS_SESSION" 2>/dev/null; then
  # tmux set-buffer + paste-buffer 방식 (TmuxSession.injectPrompt과 동일)
  tmux set-buffer -- "$INJECT_TEXT"
  tmux paste-buffer -t "$JARVIS_SESSION"
  sleep 0.3
  tmux send-keys -t "$JARVIS_SESSION" Enter
  sleep 0.5
  tmux send-keys -t "$JARVIS_SESSION" Enter
  echo "[2/2] vice-claude 세션에 알림 주입 완료"
else
  echo "[2/2] WARNING: vice-claude 세션 없음 — 로그만 저장됨"
fi

Step 2: Make executable and test syntax

Run: chmod +x /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/project-reply.sh && bash -n /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/project-reply.sh Expected: No syntax errors

Step 3: Commit

git add scripts/project-reply.sh
git commit -m "feat: add project-reply.sh for project-Claude to Jarvis communication"

Task 2: Create spawn-project-claude.sh (Session spawning)

Files:

Create: scripts/spawn-project-claude.sh

Step 1: Write the script

#!/bin/bash
set -euo pipefail
# 프로젝트 전용 Claude 세션 스폰 스크립트
# 자비스 또는 LaunchAgent에서 호출
#
# 사용법:
#   ./scripts/spawn-project-claude.sh <session-name> <project-path> [launch-cmd]
#
# 예시:
#   ./scripts/spawn-project-claude.sh richbukae-claude /path/to/projects/richbukae-store
#   ./scripts/spawn-project-claude.sh content-claude /path/to/contents-builder "claude --teammate-mode in-process --chrome"

SESSION="${1:-}"
TARGET_DIR="${2:-}"
CMD="${3:-claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome}"

if [ -z "$SESSION" ] || [ -z "$TARGET_DIR" ]; then
  echo "Usage: $0 <session-name> <project-path> [launch-cmd]"
  echo ""
  echo "Examples:"
  echo "  $0 richbukae-claude /Users/nbs22/(Claude)/(claude).projects/business-builder/projects/richbukae-store"
  echo "  $0 apppro-claude /Users/nbs22/(Claude)/(claude).projects/business-builder/projects/apppro-kr"
  exit 1
fi

# Validate project directory exists
if [ ! -d "$TARGET_DIR" ]; then
  echo "ERROR: Project directory does not exist: $TARGET_DIR"
  exit 1
fi

# Check if session already exists
if tmux has-session -t "$SESSION" 2>/dev/null; then
  # Check if Claude is running in the session
  FG=$(tmux display-message -t "$SESSION" -p '#{pane_current_command}' 2>/dev/null || echo "unknown")
  if [ "$FG" = "claude" ] || [ "$FG" = "node" ]; then
    echo "Session '$SESSION' already running (fg: $FG) — skipping"
    exit 0
  fi
  echo "Session '$SESSION' exists but Claude not running (fg: $FG) — relaunching"
  tmux send-keys -t "$SESSION" "cd $(printf '%q' "$TARGET_DIR")" Enter
  sleep 0.5
  tmux send-keys -t "$SESSION" "$CMD" Enter
  sleep 3
  echo "Relaunched Claude in existing session: $SESSION"
  exit 0
fi

# Create new detached tmux session
tmux new-session -d -s "$SESSION" -x 200 -y 50
tmux send-keys -t "$SESSION" "cd $(printf '%q' "$TARGET_DIR")" Enter
sleep 0.5
tmux send-keys -t "$SESSION" "$CMD" Enter
sleep 3

echo "Started tmux session: $SESSION"
echo "  Directory: $TARGET_DIR"
echo "  Command: $CMD"
echo "  Attach (read-only): tmux attach -r -t $SESSION"
echo "  Attach (interactive): tmux attach -t $SESSION"

Step 2: Make executable and test syntax

Run: chmod +x /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/spawn-project-claude.sh && bash -n /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/spawn-project-claude.sh Expected: No syntax errors

Step 3: Commit

git add scripts/spawn-project-claude.sh
git commit -m "feat: add spawn-project-claude.sh for project session lifecycle"

Task 3: Create stop-project-claude.sh (Session teardown)

Files:

Create: scripts/stop-project-claude.sh

Step 1: Write the script

#!/bin/bash
set -euo pipefail
# 프로젝트 Claude 세션 종료 스크립트
#
# 사용법:
#   ./scripts/stop-project-claude.sh <session-name>

SESSION="${1:-}"

if [ -z "$SESSION" ]; then
  echo "Usage: $0 <session-name>"
  exit 1
fi

# Safety: never kill core sessions
if [ "$SESSION" = "vice-claude" ] || [ "$SESSION" = "contents-builder" ]; then
  echo "ERROR: Cannot stop core session '$SESSION' — use direct tmux commands if needed"
  exit 1
fi

if tmux has-session -t "$SESSION" 2>/dev/null; then
  # Send graceful /exit first
  tmux send-keys -t "$SESSION" "/exit" Enter
  sleep 3

  # Check if still alive
  if tmux has-session -t "$SESSION" 2>/dev/null; then
    tmux kill-session -t "$SESSION"
    echo "Session '$SESSION' force-killed"
  else
    echo "Session '$SESSION' exited gracefully"
  fi
else
  echo "Session '$SESSION' not found — already stopped"
fi

Step 2: Make executable and test syntax

Run: chmod +x /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/stop-project-claude.sh && bash -n /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/stop-project-claude.sh Expected: No syntax errors

Step 3: Commit

git add scripts/stop-project-claude.sh
git commit -m "feat: add stop-project-claude.sh for graceful session teardown"

Task 4: Create project session registry (config/project-sessions.json)

Files:

Create: config/project-sessions.json

Step 1: Create config directory and registry

Run: mkdir -p /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/config

Step 2: Write the registry file

{
  "_comment": "프로젝트별 Claude 세션 레지스트리. auto_start=true인 세션은 LaunchAgent가 자동 복구.",
  "sessions": [
    {
      "name": "contents-builder",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/contents-builder",
      "auto_start": true,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "🩷 [아이유]",
      "description": "콘텐츠 전략/제작 + CEO 비서 (IU)"
    },
    {
      "name": "richbukae-claude",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/richbukae-store",
      "auto_start": false,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "🛍️ [리치부캐]",
      "description": "richbukae.com 이커머스 프로젝트"
    },
    {
      "name": "apppro-claude",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/apppro-kr",
      "auto_start": false,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "🏢 [앱프로]",
      "description": "apppro.kr B2B 홈페이지 + 블로그 + 견적"
    },
    {
      "name": "obituary-claude",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/obituary-notification-service",
      "auto_start": false,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "🕯️ [부고장]",
      "description": "부고 알림 서비스"
    },
    {
      "name": "content-pipeline-claude",
      "project_path": "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/content-pipeline",
      "auto_start": false,
      "launch_cmd": "claude --teammate-mode in-process --chrome --continue 2>/dev/null || claude --teammate-mode in-process --chrome",
      "prefix": "📝 [파이프라인]",
      "description": "AI 블로그 콘텐츠 자동 생성 파이프라인"
    }
  ]
}

Step 3: Commit

git add config/project-sessions.json
git commit -m "feat: add project session registry (config/project-sessions.json)"

Task 5: Create healthcheck-project-sessions.sh (LaunchAgent target)

Files:

Create: scripts/healthcheck-project-sessions.sh

Step 1: Write the health check script

#!/bin/bash
set -euo pipefail
# 프로젝트 Claude 세션 헬스체크 스크립트
# LaunchAgent에서 30분마다 호출
# config/project-sessions.json에서 auto_start=true인 세션만 감시
#
# 동작:
#   1. 레지스트리 읽기
#   2. auto_start=true 세션의 tmux 상태 확인
#   3. 다운된 세션 자동 복구 (spawn-project-claude.sh 호출)
#   4. 결과 로그 출력

export PATH="/usr/local/bin:/usr/bin:/bin:$HOME/.nvm/versions/node/v22.12.0/bin:$PATH"

PROJECT_ROOT="/Users/nbs22/(Claude)/(claude).projects/business-builder"
REGISTRY="${PROJECT_ROOT}/config/project-sessions.json"
SPAWN_SCRIPT="${PROJECT_ROOT}/scripts/spawn-project-claude.sh"
LOG_FILE="$HOME/.openclaw/logs/project-sessions-health.log"

mkdir -p "$(dirname "$LOG_FILE")"

log() {
  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"
  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
}

if [ ! -f "$REGISTRY" ]; then
  log "ERROR: Registry not found: $REGISTRY"
  exit 1
fi

if ! command -v jq &>/dev/null; then
  log "ERROR: jq not installed — cannot parse registry"
  exit 1
fi

# Read auto_start sessions from registry
SESSIONS=$(jq -r '.sessions[] | select(.auto_start == true) | "\(.name)|\(.project_path)|\(.launch_cmd)"' "$REGISTRY")

if [ -z "$SESSIONS" ]; then
  log "No auto_start sessions configured — nothing to check"
  exit 0
fi

RECOVERED=0
HEALTHY=0
TOTAL=0

while IFS='|' read -r NAME PATH CMD; do
  TOTAL=$((TOTAL + 1))

  if tmux has-session -t "$NAME" 2>/dev/null; then
    FG=$(tmux display-message -t "$NAME" -p '#{pane_current_command}' 2>/dev/null || echo "unknown")
    if [ "$FG" = "claude" ] || [ "$FG" = "node" ] || [ "$FG" = "npm" ]; then
      HEALTHY=$((HEALTHY + 1))
      log "OK: $NAME (fg: $FG)"
    else
      log "WARN: $NAME exists but Claude not running (fg: $FG) — recovering"
      "$SPAWN_SCRIPT" "$NAME" "$PATH" "$CMD"
      RECOVERED=$((RECOVERED + 1))
    fi
  else
    log "DOWN: $NAME — recovering"
    "$SPAWN_SCRIPT" "$NAME" "$PATH" "$CMD"
    RECOVERED=$((RECOVERED + 1))
  fi
done <<< "$SESSIONS"

log "Health check complete: total=$TOTAL, healthy=$HEALTHY, recovered=$RECOVERED"

# If any sessions were recovered, notify Jarvis (non-blocking)
if [ "$RECOVERED" -gt 0 ]; then
  NOTIFY_TEXT="[LaunchAgent] 프로젝트 세션 헬스체크: ${RECOVERED}개 세션 자동 복구됨 (total=${TOTAL}, healthy=${HEALTHY})"
  if tmux has-session -t "vice-claude" 2>/dev/null; then
    tmux set-buffer -- "[SYSTEM] $NOTIFY_TEXT"
    tmux paste-buffer -t "vice-claude"
    sleep 0.3
    tmux send-keys -t "vice-claude" Enter
    sleep 0.5
    tmux send-keys -t "vice-claude" Enter
    log "Jarvis notified of recovery"
  fi
fi

Step 2: Make executable and test syntax

Run: chmod +x /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/healthcheck-project-sessions.sh && bash -n /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/healthcheck-project-sessions.sh Expected: No syntax errors

Step 3: Commit

git add scripts/healthcheck-project-sessions.sh
git commit -m "feat: add healthcheck-project-sessions.sh for LaunchAgent auto-recovery"

Task 6: Create LaunchAgent plist for health check

Files:

Create: config/com.macclaw.project-sessions-health.plist

Step 1: Write the plist file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.macclaw.project-sessions-health</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/nbs22/(Claude)/(claude).projects/business-builder/scripts/healthcheck-project-sessions.sh</string>
    </array>
    <key>StartInterval</key>
    <integer>1800</integer>
    <key>StandardOutPath</key>
    <string>/Users/nbs22/.openclaw/logs/project-sessions-health.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/nbs22/.openclaw/logs/project-sessions-health.stderr.log</string>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Step 2: Commit (do NOT install yet — VP approval required)

git add config/com.macclaw.project-sessions-health.plist
git commit -m "feat: add LaunchAgent plist for project session health check (30min)"

Step 3: Installation instructions (for post-approval)

After VP approval, install with:

cp config/com.macclaw.project-sessions-health.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.macclaw.project-sessions-health.plist

Task 7: Create list-project-sessions.sh (Status overview)

Files:

Create: scripts/list-project-sessions.sh

Step 1: Write the status script

#!/bin/bash
set -euo pipefail
# 프로젝트 Claude 세션 현황 조회
#
# 사용법:
#   ./scripts/list-project-sessions.sh

PROJECT_ROOT="/Users/nbs22/(Claude)/(claude).projects/business-builder"
REGISTRY="${PROJECT_ROOT}/config/project-sessions.json"

if [ ! -f "$REGISTRY" ]; then
  echo "ERROR: Registry not found: $REGISTRY"
  exit 1
fi

if ! command -v jq &>/dev/null; then
  echo "ERROR: jq not installed"
  exit 1
fi

echo "=== Project Claude Sessions ==="
echo ""

# Also check core sessions
for CORE in vice-claude contents-builder; do
  if tmux has-session -t "$CORE" 2>/dev/null; then
    FG=$(tmux display-message -t "$CORE" -p '#{pane_current_command}' 2>/dev/null || echo "?")
    echo "  [CORE]  $CORE  — RUNNING (fg: $FG)"
  else
    echo "  [CORE]  $CORE  — DOWN"
  fi
done

echo ""

SESSIONS=$(jq -r '.sessions[] | "\(.name)|\(.project_path)|\(.auto_start)|\(.description)"' "$REGISTRY")

while IFS='|' read -r NAME PATH AUTO DESC; do
  if tmux has-session -t "$NAME" 2>/dev/null; then
    FG=$(tmux display-message -t "$NAME" -p '#{pane_current_command}' 2>/dev/null || echo "?")
    STATUS="RUNNING (fg: $FG)"
  else
    STATUS="STOPPED"
  fi

  AUTO_LABEL=""
  if [ "$AUTO" = "true" ]; then
    AUTO_LABEL=" [auto]"
  fi

  echo "  ${STATUS}${AUTO_LABEL}  $NAME  — $DESC"
done <<< "$SESSIONS"

echo ""
echo "Total tmux sessions: $(tmux ls 2>/dev/null | wc -l | tr -d ' ')"

Step 2: Make executable and test syntax

Run: chmod +x /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/list-project-sessions.sh && bash -n /Users/nbs22/\(Claude\)/\(claude\).projects/business-builder/scripts/list-project-sessions.sh Expected: No syntax errors

Step 3: Commit

git add scripts/list-project-sessions.sh
git commit -m "feat: add list-project-sessions.sh for session status overview"

Task 8: Create project-sessions.md skill (Jarvis management reference)

Files:

Create: .claude/skills/project-sessions.md

Step 1: Write the skill file

# Project Sessions Management Skill

## 개요
프로젝트별 전용 Claude 세션을 관리하는 스킬. 자비스가 프로젝트 Claude를 스폰/중지/통신하는 방법.

## 세션 레지스트리
- **파일**: `config/project-sessions.json`
- 프로젝트별 세션 이름, 경로, 자동시작 여부, 실행 명령어 정의
- 새 프로젝트 추가 시 이 파일에 항목 추가

## 자비스 → 프로젝트 Claude 메시지 전달

Worker API를 통해 특정 세션에 프롬프트 주입:

```bash
curl -s -X POST http://localhost:5555/prompt \
  -H "Content-Type: application/json" \
  -d '{"text":"작업 지시 내용","session":"richbukae-claude","source":"JARVIS"}'

또는 tmux 직접 주입 (Worker가 다운된 경우):

./scripts/vp_prompt_inject.sh "작업 지시" "richbukae-claude"

프로젝트 Claude → 자비스 응답

프로젝트 Claude가 결과를 보고할 때:

'./scripts/project-reply.sh' "완료 보고 내용" "richbukae-claude"

memory/project-messages/{프로젝트명}/ 에 로그 저장
vice-claude 세션에 [PROJECT-REPLY:프로젝트명] 태그로 알림 주입

세션 관리 스크립트

스크립트	용도
`scripts/spawn-project-claude.sh <이름> <경로> [CMD]`	세션 생성
`scripts/stop-project-claude.sh <이름>`	세션 종료 (graceful)
`scripts/list-project-sessions.sh`	전체 세션 현황
`scripts/healthcheck-project-sessions.sh`	헬스체크 + 자동복구

세션 스폰 예시

# richbukae.com 전용 세션 스폰
./scripts/spawn-project-claude.sh richbukae-claude \
  "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/richbukae-store"

# apppro.kr 전용 세션 스폰
./scripts/spawn-project-claude.sh apppro-claude \
  "/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/apppro-kr"

프로젝트 Claude의 CLAUDE.md 필수 포함 내용

각 프로젝트 CLAUDE.md에 아래 섹션 추가 필요:

자비스 통신 규칙: project-reply.sh 사용법
CEO 직접 회신: ceo-reply.sh 사용법 (bot name = 세션명)
VP 보고: vice-reply.sh 사용법 (prefix = 프로젝트 이모지)
금지 사항: 타 프로젝트 파일 수정 금지, DB 스키마 변경 금지

LaunchAgent 헬스체크

plist: config/com.macclaw.project-sessions-health.plist
주기: 30분 (1800초)
동작: auto_start=true 세션만 감시, 다운 시 자동 복구
로그: ~/.openclaw/logs/project-sessions-health.log

주의사항

비용: 각 Claude 세션은 API 크레딧 소비. 불필요한 세션은 반드시 stop.
안전장치: stop-project-claude.sh는 vice-claude/contents-builder 종료 차단
Worker 연동: 프로젝트 세션을 Worker 멀티봇에 등록하면 텔레그램 직통 가능 (BOTn_* env vars)


**Step 2: Commit**

```bash
git add .claude/skills/project-sessions.md
git commit -m "feat: add project-sessions.md skill for session management reference"

Task 9: Update CLAUDE.md skill table with new skill

Files:

Modify: CLAUDE.md (add project-sessions skill to the skills reference table)

Step 1: Add the skill entry

Find the skill reference table in CLAUDE.md and add:

| project-sessions | `project-sessions.md` | 프로젝트별 Claude 세션 관리 — 스폰/종료/통신/헬스체크 |

Add it after the obsidian-vault entry in the table.

Step 2: Commit

git add CLAUDE.md
git commit -m "chore: add project-sessions skill to CLAUDE.md reference table"

Task 10: Create project CLAUDE.md communication template

Files:

Create: config/project-claude-template.md

Step 1: Write the template

# {{PROJECT_NAME}} — 프로젝트 Claude

## 역할
이 세션은 **{{PROJECT_NAME}}** 전용 Claude입니다. 프로젝트 범위 내 개발/유지보수/QA를 담당합니다.

## 자비스(총괄이사)와의 통신

### 자비스로부터 지시 수신
- `[JARVIS]` 또는 `[PROJECT-INSTRUCTION]` 태그가 붙은 메시지는 자비스의 지시
- 즉시 작업 착수, 완료 후 결과 보고

### 자비스에게 결과 보고
```bash
'/Users/nbs22/(Claude)/(claude).projects/business-builder/scripts/project-reply.sh' "보고 내용" "{{SESSION_NAME}}"

경로에 괄호 있으므로 반드시 작은따옴표로 감쌀 것

CEO에게 직접 회신 (텔레그램)

[TELEGRAM:chat_id:XXX] 태그가 있는 메시지 회신 시:

'/Users/nbs22/(Claude)/(claude).projects/business-builder/scripts/ceo-reply.sh' "{{PREFIX}}\n회신 내용" "{{BOT_NAME}}"

VP(머스크)에게 보고

'/Users/nbs22/(Claude)/(claude).projects/business-builder/scripts/vice-reply.sh' "보고 내용" "태그" "{{PREFIX}}"

금지 사항

이 프로젝트 디렉토리 외부 파일 수정 금지
DB 스키마 변경 (CREATE/ALTER/DROP TABLE) 금지 — 자비스에게 요청
다른 프로젝트 세션에 메시지 주입 금지
Telegram API 직접 호출 금지
LaunchAgent/시스템 설정 변경 금지

운영 원칙

MVP 우선: 완벽보다 빠른 배포
커밋 자주: 작은 단위로 git commit + push
보고 간결하게: 핵심 결과 2~3줄
프로덕션 배포는 반드시 자비스/VP 승인 후


**Step 2: Commit**

```bash
git add config/project-claude-template.md
git commit -m "feat: add project Claude CLAUDE.md communication template"

Execution Roadmap

Phase 1: Core Infrastructure (Tasks 1-7) — Day 1

Deliverables:

scripts/project-reply.sh — project-to-Jarvis communication
scripts/spawn-project-claude.sh — session spawning
scripts/stop-project-claude.sh — graceful teardown
scripts/healthcheck-project-sessions.sh — health monitoring
scripts/list-project-sessions.sh — status overview
config/project-sessions.json — session registry
config/com.macclaw.project-sessions-health.plist — LaunchAgent (not installed)

Verification:

Run list-project-sessions.sh — should show vice-claude and contents-builder as RUNNING
Spawn a test session: spawn-project-claude.sh test-session /tmp (then immediately stop it)
Run healthcheck-project-sessions.sh — should report contents-builder as OK

Phase 2: Management Layer (Tasks 8-10) — Day 1-2

Deliverables:

.claude/skills/project-sessions.md — Jarvis reference skill
CLAUDE.md skill table updated
config/project-claude-template.md — template for project CLAUDE.md files

Phase 3: LaunchAgent Installation — After VP Approval

Steps:

VP approves the plist configuration
Copy plist to ~/Library/LaunchAgents/
launchctl load to activate
Monitor logs at ~/.openclaw/logs/project-sessions-health.log

Phase 4: Progressive Delegation — Week 2+

Steps (each requires individual VP approval):

Set up richbukae-claude — e-commerce project delegation
Set up apppro-claude — B2B homepage delegation
Set up content-pipeline-claude — automated content generation delegation
Register project sessions as Worker bots (BOTn_* env vars) for Telegram access

Risk Assessment

R1: API Credit Consumption (MEDIUM)

Risk: Each always-on Claude session consumes credits continuously
Mitigation: Default auto_start: false, on-demand spawning, aggressive session teardown
Monitor: Track via /api/usage endpoint

R2: tmux Session Conflicts (LOW)

Risk: Session name collision if two spawn attempts overlap
Mitigation: spawn-project-claude.sh checks existing sessions before creating

R3: Message Loss in Project-Reply (LOW)

Risk: If vice-claude is busy, injected messages may be lost
Mitigation: File-based log in memory/project-messages/ ensures durability. Jarvis can read logs if injection was missed.

R4: Runaway Recovery Loop (MEDIUM)

Risk: LaunchAgent keeps restarting a session that immediately crashes (e.g., auth failure)
Mitigation: TmuxSession class already has 30s cooldown between launch attempts. Health script only runs every 30 minutes, limiting restart frequency to 2/hour per session.

R5: Cross-Project Context Leakage (LOW)

Risk: Project-Claude accidentally modifies files outside its project
Mitigation: CLAUDE.md template explicitly forbids external file access. Each session starts in its own directory.

VP Review Points

Communication protocol choice: Worker API + file-based hybrid vs. alternative approaches (e.g., Redis pub/sub, Unix sockets)
LaunchAgent installation: plist review before launchctl load
Session cost model: Which sessions should be auto_start: true? Currently only contents-builder
Worker bot registration: Should project sessions get Telegram bot tokens (BOTn_*)? Adds CEO direct access but increases complexity
Security: Project-Claude sessions have access to parent business-builder directory via relative paths. Template CLAUDE.md forbids it but enforcement is honor-system only