claude-controller 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 choiwon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# Controller
+
+A shell wrapper that runs Claude Code CLI as a headless daemon. Provides FIFO pipe-based async task dispatch, Git Worktree isolation, automatic checkpointing/rewind, and a web dashboard for remote task management.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Web Dashboard (Vanilla JS)                                     │
+│  https://claude.won-space.com  <->  localhost:8420              │
+└────────────────────┬────────────────────────────────────────────┘
+                     │ REST API (Python http.server)
+┌────────────────────▼────────────────────────────────────────────┐
+│  Web Server (native-app.py)                                     │
+│  ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌───────────────────┐│
+│  │ handler  │ │ jobs.py    │ │ auth.py  │ │ checkpoint.py     ││
+│  │ (REST)   │ │ (FIFO I/O) │ │ (Bearer) │ │ (Rewind)          ││
+│  └──────────┘ └─────┬──────┘ └──────────┘ └───────────────────┘│
+└─────────────────────┼───────────────────────────────────────────┘
+                      │ JSON via FIFO (queue/controller.pipe)
+┌─────────────────────▼───────────────────────────────────────────┐
+│  Controller Daemon (service/controller.sh)                      │
+│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────────────┐ │
+│  │ executor │ │ jobs.sh  │ │ session   │ │ worktree.sh       │ │
+│  │ (claude) │ │ (state)  │ │ (conv.)   │ │ (Git isolation)   │ │
+│  └──────────┘ └──────────┘ └───────────┘ └───────────────────┘ │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ checkpoint.sh (watch changes -> auto-commit -> rewind)    │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└──────────────────────┬──────────────────────────────────────────┘
+                       │ claude -p --output-format stream-json
+                       ▼
+              Claude Code CLI (headless)
+```
+
+## Project Structure
+
+```
+controller/
+├── bin/                    # Entry points
+│   ├── controller          # Service control (start/stop/restart/status)
+│   ├── send                # CLI client — sends tasks to FIFO
+│   ├── start               # Launch service + TUI together
+│   ├── claude-sh           # Interactive shell mode entry point
+│   ├── native-app.py       # Web server with auto browser launch
+│   └── app-launcher.sh     # macOS app launcher
+├── lib/                    # Core modules (Bash)
+│   ├── executor.sh         # claude -p execution engine
+│   ├── jobs.sh             # Job registration / state / result management
+│   ├── session.sh          # Claude session ID tracking
+│   ├── worktree.sh         # Git Worktree create / remove / list
+│   └── checkpoint.sh       # Auto-checkpoint + Rewind
+├── service/
+│   └── controller.sh       # FIFO listener → dispatch persistent daemon
+├── web/                    # HTTP REST API server (Python)
+│   ├── server.py           # Module entry point
+│   ├── handler.py          # REST API handler (GET/POST/DELETE)
+│   ├── config.py           # Paths / security / SSL settings
+│   ├── auth.py             # Token-based authentication
+│   ├── jobs.py             # Job CRUD + FIFO messaging
+│   ├── checkpoint.py       # Checkpoint queries + Rewind execution
+│   ├── utils.py            # Meta file parser, service status check
+│   └── static/             # Web dashboard (Vanilla JS/CSS)
+├── config.sh               # Global config (paths, model, permissions, worktree)
+├── data/                   # Runtime data (settings.json, auth_token)
+├── logs/                   # Job output (.out) + metadata (.meta)
+├── queue/                  # FIFO pipe (controller.pipe)
+├── sessions/               # Session history (history.log)
+├── uploads/                # File upload storage
+└── worktrees/              # Git Worktree storage
+```
+
+## Getting Started
+
+### Prerequisites
+
+- macOS / Linux
+- Claude Code CLI (`claude` command or app-bundled binary)
+- Python 3.8+
+- `jq` (JSON processing)
+- Git (required for Worktree features)
+
+### Running
+
+```bash
+# Start the service only
+bin/controller start
+
+# Start service + TUI together
+bin/start
+
+# Start the web server (auto-opens browser)
+python3 bin/native-app.py
+
+# Check service status
+bin/controller status
+
+# Stop the service
+bin/controller stop
+```
+
+### Sending Tasks via CLI
+
+```bash
+# Send a basic prompt
+bin/send "Fix the bug in auth.py"
+
+# Specify a working directory
+bin/send --cwd /path/to/repo "Write test code"
+
+# Run in an isolated Git Worktree
+bin/send --worktree --repo /path/to/repo "Perform refactoring"
+
+# Specify a custom task ID
+bin/send --id my-task-1 "Write README"
+
+# Check all task statuses
+bin/send --status
+
+# View task result
+bin/send --result <task_id>
+```
+
+## Key Features
+
+### FIFO-Based Async Dispatch
+
+The service daemon listens on a Named Pipe (`queue/controller.pipe`) for JSON messages and runs `claude -p` in the background. Supports duplicate prompt detection (3-second window), max concurrent job limits, and session modes (new/resume/fork/continue).
+
+```json
+{
+  "id": "task-1",
+  "prompt": "Fix the bug",
+  "cwd": "/path/to/project",
+  "worktree": "true",
+  "session": "resume:<session_id>",
+  "images": ["/path/to/screenshot.png"]
+}
+```
+
+### Git Worktree Isolation
+
+Each task runs in an independent Git Worktree, enabling parallel work without affecting the main branch. A `controller/job-<id>` branch is automatically created and can be cleaned up after completion.
+
+### Auto-Checkpoint & Rewind
+
+Periodically monitors file changes in the Worktree and auto-commits when changes stabilize. If something goes wrong, you can `git reset --hard` to a specific checkpoint and resume work with a new prompt that includes the previous conversation context (Rewind).
+
+### Session Management
+
+Tracks Claude Code session IDs to enable conversation continuity:
+
+- **new** — Start a fresh session
+- **resume** — Continue an existing session (`--resume <session_id>`)
+- **fork** — Branch from a previous session by injecting its context
+- **continue** — Continue the most recent conversation (`--continue`)
+
+## REST API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/status` | Service running status |
+| GET | `/api/jobs` | List all jobs |
+| GET | `/api/jobs/:id/result` | Get job result |
+| GET | `/api/jobs/:id/stream` | Poll real-time stream (offset-based) |
+| GET | `/api/jobs/:id/checkpoints` | List checkpoints |
+| GET | `/api/sessions` | List sessions (Claude Code native + job meta) |
+| GET | `/api/session/:id/job` | Find job by session ID |
+| GET | `/api/config` | Get configuration |
+| GET | `/api/recent-dirs` | Get recent working directories |
+| GET | `/api/dirs?path=` | Browse filesystem directories |
+| POST | `/api/send` | Send a new task (via FIFO) |
+| POST | `/api/upload` | Upload a file (base64) |
+| POST | `/api/jobs/:id/rewind` | Rewind to a checkpoint |
+| POST | `/api/service/start` | Start the service |
+| POST | `/api/service/stop` | Stop the service |
+| POST | `/api/config` | Save configuration |
+| POST | `/api/auth/verify` | Verify auth token |
+| DELETE | `/api/jobs/:id` | Delete a job |
+| DELETE | `/api/jobs` | Bulk delete completed jobs |
+
+## Security
+
+Three-layer security model:
+
+1. **Host Header Validation** — Only allows `localhost`, `127.0.0.1`, `[::1]` to prevent DNS Rebinding attacks.
+2. **Origin Validation (CORS)** — Only accepts cross-origin requests from an allowed Origin list.
+3. **Token Authentication** — Generates a random token on server startup. When `AUTH_REQUIRED=true`, all API requests must include an `Authorization: Bearer <token>` header.
+
+### SSL/HTTPS
+
+Generate local certificates with `mkcert` to enable HTTPS mode:
+
+```bash
+mkcert -install
+mkcert -cert-file certs/localhost+1.pem -key-file certs/localhost+1-key.pem localhost 127.0.0.1
+```
+
+## Configuration
+
+Override settings via `data/settings.json` or environment variables:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `skip_permissions` | `true` | Use `--dangerously-skip-permissions` flag |
+| `model` | `""` | Claude model override (empty = default model) |
+| `max_jobs` | `10` | Max concurrent background jobs |
+| `target_repo` | `""` | Git repository path for Worktree creation |
+| `base_branch` | `main` | Base branch for Worktree |
+| `checkpoint_interval` | `5` | Checkpoint watch interval (seconds) |
+| `append_system_prompt` | `""` | Additional system prompt text |
+| `allowed_tools` | All tools | Tool allowlist for Claude |
+
+## License
+
+MIT

package/bin/app-launcher.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/cmux.app/Contents/Resources/bin:$PATH"
+_src="$0"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+CONTROLLER_DIR="$(cd "$(dirname "$_src")/.." && pwd)"
+cd "$CONTROLLER_DIR" || exit 1
+source config.sh
+mkdir -p "$LOGS_DIR" "$QUEUE_DIR" "$SESSIONS_DIR" "$WORKTREES_DIR"
+
+# 서비스 시작
+if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then true; else
+  rm -f "$FIFO_PATH" "$PID_FILE" 2>/dev/null
+  bash service/controller.sh start >> "$LOGS_DIR/service.log" 2>&1 &
+  sleep 2
+fi
+
+# 네이티브 앱 실행
+exec /opt/homebrew/bin/python3 bin/native-app.py 2>> "$LOGS_DIR/app.log"

package/bin/claude-sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# ============================================================
+# claude-sh — Claude Shell Controller 진입점
+#
+# 사용법:
+#   claude-sh                     인터랙티브 쉘 모드
+#   claude-sh "프롬프트"          단일 명령 실행
+#   claude-sh "프롬프트" &        백그라운드 실행
+#   echo "프롬프트" | claude-sh   파이프라인 입력
+# ============================================================
+
+_src="${BASH_SOURCE[0]}"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+SCRIPT_DIR="$(cd "$(dirname "$_src")/.." && pwd)"
+exec bash "${SCRIPT_DIR}/claude-shell.sh" "$@"

package/bin/controller

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Controller service entry point
+# Usage:
+#   controller start    — 서비스 시작
+#   controller stop     — 서비스 중지
+#   controller restart  — 재시작
+#   controller status   — 상태 확인
+
+_src="${BASH_SOURCE[0]}"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+SCRIPT_DIR="$(cd "$(dirname "$_src")/.." && pwd)"
+source "${SCRIPT_DIR}/config.sh"
+
+case "${1:-start}" in
+  start)
+    exec bash "${SCRIPT_DIR}/service/controller.sh" start
+    ;;
+  stop)
+    exec bash "${SCRIPT_DIR}/service/controller.sh" stop
+    ;;
+  restart)
+    bash "${SCRIPT_DIR}/service/controller.sh" stop
+    sleep 1
+    exec bash "${SCRIPT_DIR}/service/controller.sh" start
+    ;;
+  status)
+    exec bash "${SCRIPT_DIR}/service/controller.sh" status
+    ;;
+  *)
+    echo "사용법: controller {start|stop|restart|status}"
+    exit 1
+    ;;
+esac

package/bin/native-app.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Claude Controller — 웹 서버 실행 + 브라우저 자동 오픈
+SSL/HTTPS 지원 + 토큰 인증
+"""
+import http.server
+import os
+import ssl
+import subprocess
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+CONTROLLER_DIR = Path(__file__).resolve().parent.parent
+SERVICE_SCRIPT = CONTROLLER_DIR / "service" / "controller.sh"
+PID_FILE = CONTROLLER_DIR / "service" / "controller.pid"
+LOGS_DIR = CONTROLLER_DIR / "logs"
+PORT = int(os.environ.get("PORT", 8420))
+
+
+def is_service_running():
+    if not PID_FILE.exists():
+        return False, None
+    try:
+        pid = int(PID_FILE.read_text().strip())
+        os.kill(pid, 0)
+        return True, pid
+    except (ValueError, ProcessLookupError, PermissionError, OSError):
+        return False, None
+
+
+def main():
+    for d in ["logs", "queue", "sessions", "uploads", "data", "certs"]:
+        (CONTROLLER_DIR / d).mkdir(parents=True, exist_ok=True)
+
+    # 서비스 시작
+    ok, pid = is_service_running()
+    if not ok:
+        log_fh = open(LOGS_DIR / "service.log", "a")
+        subprocess.Popen(["bash", str(SERVICE_SCRIPT), "start"],
+            stdout=log_fh, stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL, start_new_session=True, cwd=str(CONTROLLER_DIR))
+        log_fh.close()
+        for _ in range(30):
+            time.sleep(0.1)
+            ok, pid = is_service_running()
+            if ok:
+                break
+
+    # 웹 모듈 임포트
+    sys.path.insert(0, str(CONTROLLER_DIR / "web"))
+    from server import ControllerHandler
+    from config import SSL_CERT, SSL_KEY, PUBLIC_URL
+    from auth import generate_token
+
+    # 토큰 생성 (매 시작 시 새로 발급)
+    token = generate_token()
+
+    # SSL 인증서 확인
+    use_ssl = os.path.isfile(SSL_CERT) and os.path.isfile(SSL_KEY)
+    scheme = "https" if use_ssl else "http"
+
+    server = http.server.HTTPServer(("127.0.0.1", PORT), ControllerHandler)
+
+    if use_ssl:
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        ctx.load_cert_chain(SSL_CERT, SSL_KEY)
+        server.socket = ctx.wrap_socket(server.socket, server_side=True)
+
+    # 시작 배너
+    print(f"""
+  ┌──────────────────────────────────────────────┐
+  │  Claude Controller                           │
+  ├──────────────────────────────────────────────┤
+  │  API   : {scheme}://localhost:{PORT:<24s}│
+  │  App   : {PUBLIC_URL:<35s}│
+  │  SSL   : {'ON' if use_ssl else 'OFF (HTTP 모드)':<35s}│
+  ├──────────────────────────────────────────────┤
+  │  Auth Token (아래 토큰을 프론트엔드에 입력):  │
+  │  {token:<43s}│
+  ├──────────────────────────────────────────────┤
+  │  종료  : Ctrl+C                              │
+  └──────────────────────────────────────────────┘
+""")
+
+    if not use_ssl:
+        print(f"  [참고] HTTPS를 사용하려면 mkcert로 인증서를 생성하세요:")
+        print(f"    mkcert -install && mkcert -cert-file certs/localhost+1.pem \\")
+        print(f"      -key-file certs/localhost+1-key.pem localhost 127.0.0.1\n")
+
+    webbrowser.open(PUBLIC_URL)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n  종료됨.")
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

package/bin/send

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# ============================================================
+# send — Controller 서비스에 명령을 전송하는 클라이언트
+# ============================================================
+# Usage:
+#   send "Fix the bug in auth.py"
+#   send --cwd /path/to/repo "Fix the bug"
+#   send --id my-task-1 "Fix the bug"
+#   send --status
+#   send --result <job_id>
+#   send --stop
+# ============================================================
+
+set -euo pipefail
+
+_src="${BASH_SOURCE[0]}"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+SCRIPT_DIR="$(cd "$(dirname "$_src")" && pwd)"
+source "${SCRIPT_DIR}/../config.sh"
+source "${SCRIPT_DIR}/../lib/jobs.sh"
+
+# ── 사용법 출력 ─────────────────────────────────────────────
+usage() {
+  cat <<'USAGE'
+사용법:
+  send "프롬프트"                         프롬프트 전송
+  send --cwd <경로> "프롬프트"            작업 디렉토리 지정하여 전송
+  send --id <작업ID> "프롬프트"           사용자 지정 ID로 전송
+  send --worktree [--repo <경로>] "프롬프트"  worktree에서 격리 실행
+  send --status                           전체 작업 상태 조회
+  send --result <작업ID>                  작업 결과 조회
+  send --stop                             서비스 종료
+  send --help                             이 도움말 출력
+USAGE
+}
+
+# ── UUID 생성 ───────────────────────────────────────────────
+generate_id() {
+  echo "$(date +%s)-$$-${RANDOM}"
+}
+
+# ── 서비스 실행 여부 확인 ───────────────────────────────────
+check_service() {
+  if [[ ! -p "$FIFO_PATH" ]]; then
+    echo "[오류] 서비스가 실행 중이 아닙니다. (FIFO 없음: $FIFO_PATH)" >&2
+    echo "       먼저 서비스를 시작하세요." >&2
+    exit 1
+  fi
+}
+
+# ── 플래그 파싱 ─────────────────────────────────────────────
+CWD=""
+JOB_ID=""
+ACTION="send"   # send | status | result | stop
+USE_WORKTREE=""
+REPO_PATH=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd)
+      CWD="$2"
+      shift 2
+      ;;
+    --id)
+      JOB_ID="$2"
+      shift 2
+      ;;
+    --worktree)
+      USE_WORKTREE="true"
+      shift
+      ;;
+    --repo)
+      REPO_PATH="$2"
+      shift 2
+      ;;
+    --status)
+      ACTION="status"
+      shift
+      ;;
+    --result)
+      ACTION="result"
+      RESULT_JOB_ID="$2"
+      shift 2
+      ;;
+    --stop)
+      ACTION="stop"
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "[오류] 알 수 없는 옵션: $1" >&2
+      usage
+      exit 1
+      ;;
+    *)
+      PROMPT="$1"
+      shift
+      ;;
+  esac
+done
+
+# ── 액션 실행 ───────────────────────────────────────────────
+case "$ACTION" in
+
+  status)
+    jobs_list
+    ;;
+
+  result)
+    if [[ -z "${RESULT_JOB_ID:-}" ]]; then
+      echo "[오류] --result 에 작업 ID를 지정하세요." >&2
+      exit 1
+    fi
+    job_result "$RESULT_JOB_ID"
+    ;;
+
+  stop)
+    if [[ ! -f "$PID_FILE" ]]; then
+      echo "[오류] PID 파일을 찾을 수 없습니다. ($PID_FILE)" >&2
+      echo "       서비스가 실행 중이 아닌 것 같습니다." >&2
+      exit 1
+    fi
+    SERVICE_PID=$(cat "$PID_FILE")
+    if kill -0 "$SERVICE_PID" 2>/dev/null; then
+      kill -TERM "$SERVICE_PID"
+      echo "[완료] 서비스(PID: $SERVICE_PID)에 종료 신호를 전송했습니다."
+    else
+      echo "[알림] 서비스(PID: $SERVICE_PID)는 이미 종료된 상태입니다."
+      rm -f "$PID_FILE"
+    fi
+    ;;
+
+  send)
+    if [[ -z "${PROMPT:-}" ]]; then
+      echo "[오류] 전송할 프롬프트를 입력하세요." >&2
+      usage
+      exit 1
+    fi
+
+    check_service
+
+    # ID가 없으면 자동 생성
+    [[ -z "$JOB_ID" ]] && JOB_ID=$(generate_id)
+
+    # CWD 기본값: 현재 디렉토리
+    [[ -z "$CWD" ]] && CWD="$(pwd)"
+
+    # JSON 페이로드 구성 (jq 사용 — 특수문자 안전 처리)
+    JQ_ARGS=(
+      --arg id "$JOB_ID"
+      --arg prompt "$PROMPT"
+      --arg cwd "$CWD"
+    )
+    JQ_EXPR='{id: $id, prompt: $prompt, cwd: $cwd}'
+
+    if [[ -n "$USE_WORKTREE" ]]; then
+      JQ_ARGS+=(--arg worktree "true")
+      JQ_EXPR='{id: $id, prompt: $prompt, cwd: $cwd, worktree: $worktree}'
+      if [[ -n "$REPO_PATH" ]]; then
+        JQ_ARGS+=(--arg repo "$REPO_PATH")
+        JQ_EXPR='{id: $id, prompt: $prompt, cwd: $cwd, worktree: $worktree, repo: $repo}'
+      fi
+    fi
+
+    PAYLOAD=$(jq -cn "${JQ_ARGS[@]}" "$JQ_EXPR")
+
+    # FIFO에 전송
+    echo "$PAYLOAD" > "$FIFO_PATH"
+
+    echo "[전송 완료] 작업이 서비스로 전달되었습니다."
+    echo "  작업 ID : $JOB_ID"
+    echo "  디렉토리: $CWD"
+    [[ -n "$USE_WORKTREE" ]] && echo "  워크트리: ON${REPO_PATH:+ (repo: $REPO_PATH)}"
+    display_prompt="${PROMPT:0:80}"
+    [[ ${#PROMPT} -gt 80 ]] && display_prompt="${display_prompt}..."
+    echo "  프롬프트: $display_prompt"
+    ;;
+esac

package/bin/start

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# ============================================================
+# start — Controller 서비스 + TUI 일괄 실행
+# Usage: ./start [--repo /path/to/git/repo]
+# ============================================================
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+SCRIPT_DIR="$(cd "$(dirname "$_src")/.." && pwd)"
+source "${SCRIPT_DIR}/config.sh"
+
+# 옵션 파싱
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      export TARGET_REPO="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# 사전 검증
+if [[ -z "$CLAUDE_BIN" ]]; then
+  echo "[오류] claude CLI를 찾을 수 없습니다."; exit 1
+fi
+if ! command -v python3 &>/dev/null; then
+  echo "[오류] python3가 필요합니다."; exit 1
+fi
+
+mkdir -p "$LOGS_DIR" "$QUEUE_DIR" "$SESSIONS_DIR" "$WORKTREES_DIR"
+
+echo ""
+echo "  ╔══════════════════════════════════════════╗"
+echo "  ║   Controller Service + TUI               ║"
+echo "  ╚══════════════════════════════════════════╝"
+echo ""
+
+# 컨트롤러 서비스 시작
+if [[ -f "$PID_FILE" ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  echo "  [서비스] 이미 실행 중 (PID: $(cat "$PID_FILE"))"
+else
+  echo "  [서비스] 컨트롤러 데몬 시작 중..."
+  bash "${SCRIPT_DIR}/service/controller.sh" start &
+  sleep 2
+  if [[ -f "$PID_FILE" ]]; then
+    echo "  [서비스] 시작됨 (PID: $(cat "$PID_FILE"))"
+  fi
+fi
+
+echo ""
+echo "  [TUI] 터미널 프로그램을 시작합니다..."
+echo "  [TUI] 종료: q 키"
+echo ""
+
+# Ctrl+C로 서비스도 함께 종료
+cleanup_all() {
+  if [[ -f "$PID_FILE" ]]; then
+    kill "$(cat "$PID_FILE")" 2>/dev/null
+  fi
+  echo ""
+  echo "  종료됨."
+}
+trap cleanup_all INT TERM
+
+# TUI 포그라운드 실행
+sleep 1
+exec python3 "${SCRIPT_DIR}/bin/tui"