shuyu-labs/WebCode

AI CLI, Web 세션, 모바일 및 Feishu 워크플로우를 하나의 제어판으로 통합

브라우저 또는 Feishu 카드를 통해 Claude Code, Codex, OpenCode 세션, 워크스페이스, 프로젝트 및 명령 실행을 관리합니다.

• 프로젝트 소개
• 현재 중점 기능
• 다중 AI CLI 연동
• Web, 모바일, Feishu 통합 세션 흐름
• 다중 사용자 및 권한 제어
• 외부 세션 가져오기 및 복구
• Codex
  /goal

빠른 목표 기능 - Superpowers 워크플로우

• Windows 설치 패키지 배포
  cc-switch

호스팅 모델 - 빠른 시작

• 구성 설명
• Windows 배포 유지보수
• 프로젝트 구조
• 기술 스택
• 자주 사용하는 문서

WebCode는 Blazor Server + .NET 10을 기반으로 하는 AI CLI 작업 플랫폼입니다. 이는 단순한 단일 기기용 채팅 래퍼(Shell)가 아니라, 로컬 또는 서버의 AI CLI를 관리 가능하고, 배포 가능하며, 협업 가능하고, 원격 접속 가능한 작업 시스템으로 패키징한 것입니다.

현재 저장소는 다음과 같은 핵심 시나리오를 지원합니다:

• Web 단에서 AI 세션 생성, 전환, 종료 및 복구
• 각 세션에 독립적인 워크스페이스(Workspace) 및 프로젝트 디렉토리 바인딩
• 현재 시스템 계정 하에 이미 존재하는 Claude Code, Codex, OpenCode 로컬 세션 가져오기 - WebCode 자체 메시지 아카이브에만 의존하지 않고 원본 CLI 트랜스크립트(Transcript)로부터 히스토리 메시지 복구
• 데스크톱, 모바일 및 Feishu 카드에서 동일한 세션 세트 사용
• 팀 사용자를 위한 사용 가능한 도구, 디렉토리 화이트리스트, Feishu 봇 및 권한 구성
• cc-switch를 관리형 CLI의 유일한 Provider 권위 소스로 사용

만약 당신이 필요한 것이 단순한 로컬 패키징 도구가 아니라 "배포 가능한 AI CLI 콘솔"이라면, 이 저장소는 바로 그 목적을 위해 설계되었습니다.

현재 적응(Adapted) 또는 직접 지원되는 도구:

도구	설명	상태
Claude Code	세션 관리, 스트리밍 출력, Transcript 복구	사용 가능
Codex CLI	JSONL 출력, 샌드박스/승인 모드, 세션 실행	사용 가능
OpenCode	다중 모델 워크플로우, 세션 가져오기 및 실행	사용 가능
커스텀 CLI	어댑터(Adapter) 패턴에 따라 계속 확장 가능	확장 가능

관련 구현은 주로 WebCodeCli.Domain/Domain/Service/Adapters에 위치합니다.

• 각 세션은 독립적인 워크스페이스를 바인딩할 수 있음
• 기본 디렉토리, 기존 디렉토리, 프로젝트 디렉토리 및 사용자 정의 디렉토리 지원
• 파일 브라우징, 미리보기, 업로드, 경로 복사 등 워크스페이스 작업 지원
• 히스토리 세션 전환, 종료, 격리 및 정리 지원
• 로컬 CLI 세션을 가져와 WebCode에서 계속 사용 지원
• 모바일 드로어(Drawer) 및 Feishu 세션 카드에서 직접 세션 관리 지원
• 데스크톱 Web, 모바일 및 Feishu에서 "텍스트 + 첨부 파일" 메시지 제출 지원; 첨부 파일은 도구 능력에 따라 원시 첨부 또는 워크스페이스 참조로 강등(Degradation) 처리됨
• Feishu 상위 레벨의 image/file 메시지가 먼저 "제출 대기 첨부 파일" 카드를 생성하고, 추가 설명을 보완한 후 CLI로 전송되는 방식 지원 - Feishu 리치 텍스트 post 메시지 지원
• post 메시지의 "이미지 붙여넣기 + 텍스트"를 통해 이미지와 텍스트를 함께 CLI에 제출 가능

다음 표는 세 가지 주요 엔트리(Entry)가 현재 각각 커버하는 기능 범위를 빠르게 설명합니다:

기능	데스크톱 Web	모바일	Feishu
세션 생성, 전환, 종료	지원	지원	지원
/goal 퀵 목표	지원	지원	지원
Superpowers 퀵 워크플로우	지원	지원	지원
다중 사용자 관리 및 시스템 구성	가장 완전하게 지원	가벼운 확인/조작에 적합	주요 엔트리로 사용되지 않음
설치 및 배포 유지보수	주로 문서 및 로컬 스크립트에 의존	주요 엔트리로 사용되지 않음	주요 엔트리로 사용되지 않음

추가 설명:

• 데스크톱 Web은 기능이 가장 완전한 메인 콘솔로, 관리, 디버깅, 구성 및 헤비한 세션 작업에 적합합니다.
• 모바일은 빈번한 세션 작업을 유지하며, 언제든 확인, 전환, 계속하기 및 퀵 액션을 트리거하는 데 중점을 둡니다.
• Feishu는 메시지 및 카드 기반에 더 치우쳐 있어, 채팅 컨텍스트 내에서 직접 세션을 계속하거나, 퀵 액션을 실행하고, 스트리밍 결과를 받는 데 적합합니다.

Feishu는 현재 단순히 "메시지 알림"만 하는 것이 아니라, 직접 작동 가능한 세션 및 카드 상호작용 링크를 이미 커버하고 있습니다:

• Feishu 세션을 WebCode 사용자 및 로컬/서버 측 CLI 세션에 바인딩 지원
• Feishu 카드 내에서 세션 생성, 전환, 종료, 계속하기 지원
• Feishu 단에서 외부 CLI 세션을 브라우징하고 가져오기 지원
• Feishu 카드에서 /goal, Superpowers 등 퀵 액션 트리거 지원 - 실행 과정 중 출력을 지속적으로 에코(Echo)하는 스트리밍 카드 업데이트 지원
• 이미지, 파일 메시지의 "제출 대기 첨부 파일" 카드 프로세스 지원 - 먼저 워크스페이스에 임시 저장한 후, 추가 설명을 보완하여 CLI에 제출
• 텍스트 박스에 이미지를 붙여넣어 생성된 리치 텍스트 post 지원

메시지를, 임베디드 이미지와 텍스트를 함께 CLI에 직접 제출 - 세션 레벨의 Provider 동기화를 지원하여 Feishu(飞书) 측에서도 동일한 설정을 따르도록 보장
cc-switch

현재 활성화 상태 - Reply TTS 관련 기능을 지원하여, 응답 내용을 음성으로 변환하거나 음성 서비스 호출 체인으로 연결

• 도움말 카드, 퀵 엔트리(Quick Entry) 카드, 세션 관리 카드 등 다양한 인터랙션 매개체 지원

적합한 Feishu 사용 시나리오는 다음과 같습니다:

• 그룹 채팅이나 개인 채팅에서 기존 AI CLI 세션을 즉시 이어가기

• 모바일 업무 환경에서 전체 Web 콘솔을 열지 않고 카드를 통해 빈번한 작업 수행

• 로봇 카드를 사용하여 스트리밍 출력, 퀵 액션(Quick Action), 목표 설정 및 세션 전환 처리

• 사용자 활성화/비활성화

• 사용자별 사용 가능한 CLI 도구 제한

• 사용자 화이트리스트 디렉토리 정책

• 사용자 레벨의 Feishu 로봇 설정

• 기본 공유 설정 + 사용자 오버라이드(Override) 설정

외부 CLI 세션 임포트는 현재 다음과 같은 제약 사항을 가집니다:

• 현재 운영체제 계정에서 접근 가능한 로컬 세션만 스캔
• 허용된 디렉토리 또는 화이트리스트에 포함된 워크스페이스의 세션만 표시
• 동일한 (ToolId, CliThreadId)는 단 하나의 WebCode 사용자만 점유할 수 있음 - Web 및 Feishu 양측 모두 페이지네이션 브라우징, 임포트 및 해당 세션으로의 전환을 지원

현재 버전은 Codex /goal 관련 기능을 보완하였으며, Web, 모바일 및 Feishu 카드 시나리오를 모두 커버합니다:

• WebCode는 먼저 현재 Codex CLI 버전과 goals 기능의 사용 가능 여부를 탐지합니다 - 탐지 결과 사용 가능한 경우, 세션 레벨의 .codex/config.toml에 goals = true를 자동으로 주입합니다.
• 사용자는 빠른 입력 또는 퀵 액션을 통해 일반 텍스트를 /goal ...로 자동 완성할 수 있습니다.
• /goal 기능은 세션별로 적용되며, 전역 config.toml을 수동으로 장기 유지 관리할 필요가 없습니다.

설명:

• 현재 Codex CLI 버전은 0.128.0 이상이어야 합니다.
• WebCode는 Windows 환경에서 codex.exe, codex.cmd, codex.bat, codex.ps1 등의 엔트리 포인트를 자동으로 해석하여, 래퍼 스크립트(Wrapper Script)로 인한 버전 탐지 실패를 방지합니다 - 만약 Codex 자체에서 goals 기능을 제공하지 않는다면, WebCode는 해당 설정을 강제로 주입하지 않습니다.

현재 저장소는 Superpowers 워크플로우 강화 기능을 통합하여, 일반 CLI 세션을 "정책과 퀵 액션이 포함된 실행 흐름(Execution Flow)"으로 격상시킵니다:

• Web, 모바일 및 Feishu 카드에서 워크플로우형 퀵 액션 트리거 지원
• 사용자 입력을 단순히 CLI로 전달하는 것을 넘어, 구조화된 워크플로우 프롬프트로 빠르게 래핑하는 기능 지원
• 기능 탐지(Capability Detection)를 지원하여, 현재 환경에 따라 해당 워크플로우 엔트리의 표시 또는 활성화 여부를 결정
• Superpowers를 기존의 Claude Code, Codex, OpenCode 세션 흐름과 결합하여 사용 가능

현재 문서와 구현에 포함된 전형적인 워크플로우는 다음과 같습니다:

• 계획형 워크플로우: 예) plan, ralplan
• 지속 실행형 워크플로우: 예) ralph
• 심층 확인형 워크플로우: 예) deep-interview
• 협업/병렬형 워크플로우: 예) team, ultrawork
• 퀵 액션형 캡슐화: 세션 대상의 원클릭 프롬프트 및 워크플로우 명령 주입 등

설명:

Superpowers는 별도의 Web 페이지가 아니라, 기존 세션, 퀵 액션, Feishu 카드 인터랙션 위에 중첩되는 워크플로우 레이어입니다. 어떤 워크플로우를 사용할 수 있는지는 현재 도구, 환경 탐지 결과 및 세션 컨텍스트에 따라 결정됩니다.

• 관련 구현은 저장소를 참고하십시오.

저장소에는 Windows 설치 패키지 빌드 스크립트가 내장되어 있어 다음을 직접 생성할 수 있습니다:

• 설치 버전: WebCode-Setup-vX.Y.Z-win-x64.exe
• 포터블 버전: WebCode-vX.Y.Z-win-x64-portable.zip
• 검증 파일: SHA256SUMS.txt
• 릴리스 노트: RELEASE_NOTES.md
• Reply TTS 서비스 및 실행에 필요한 리소스를 포함한 tts-bundle/
• 배포 패키지 페이지: https://github.com/lusile2024/WebCode/releases

현재 버전부터 Claude Code, Codex, OpenCode 세 종류의 관리형 어시스턴트는 동일한 규칙을 따릅니다:

cc-switch가 유일한 Provider 권위 소스(Source of Truth)입니다. - WebCode는 더 이상 이 세 가지 도구에 대해 수동으로 환경 변수를 입력하거나, Provider를 편집하거나, Profile을 전환하는 것을 허용하지 않습니다. - Provider의 활성화 및 전환은 반드시 cc-switch 내에서 완료되어야 합니다. - WebCode는 오직 cc-switch의 현재 상태와 라이브 설정(live config)만을 읽습니다.

WebCode는 다음 소스를 읽습니다:

~/.cc-switch/settings.json

~/.cc-switch/cc-switch.db

cc-switch가 작성한 각 도구의 라이브 설정(live config) 파일

WebCode는 이제 "터미널 창과 같은" 세션 의미론(session semantics)을 따릅니다:

• 새 세션은 처음 실행될 때, 현재 활성화된 Provider의 라이브 설정(live config)을 해당 세션의 스냅샷(snapshot)으로 복사합니다.
• 이미 사용 중인 기존 세션은 cc-switch에서 Provider를 전환하더라도 자동으로 변경되지 않습니다. 오직 사용자가 명시적으로 "Provider 동기화(Sync Provider)"를 클릭했을 때만, 기존 세션이 cc-switch에서 현재 활성화된 Provider로 전환됩니다.

이 동기화 엔트리는 현재 다음 위치에 추가되었습니다:

• 데스크톱 Web 세션 목록
• 모바일 세션 드로어(drawer)
• Feishu(飞书) 세션 관리 카드

세션 스냅샷이 유실되거나 손상된 경우, WebCode는 조용히 기기의 현재 라이브 설정(live config)으로 되돌아가는 대신, 실행을 중단하고 명시적인 동기화를 요청합니다.

OpenCode는 Claude Code, Codex와 마찬가지로 cc-switch의 관리를 받습니다.

• 초기화 시 어떤 관리 대상 어시스턴트(managed assistant)를 활성화할지 선택할 수 있습니다.
• 초기화 시 선택하지 않았더라도, 이후 설정의 어시스턴트 관리(assistant management)에서 다시 활성화할 수 있습니다.
• 실제로 사용 가능한지 여부는 cc-switch가 해당 도구를 위해 실행 가능한 Provider와 라이브 설정(live config)을 준비했는지에 달려 있습니다.

체험판, 사내망(intranet) 배포 및 소규모 팀 사용에 적합합니다.

git clone https://github.com/lusile2024/WebCode.git
cd WebCode
docker compose up -d

실행 후 접속 주소:

http://localhost:5000

더 자세한 배포 세부 사항은 다음을 참조하십시오:

.NET SDK를 미리 설치할 필요 없이 Windows 머신에서 WebCode를 직접 실행하기에 적합합니다.

다운로드 경로:

• GitHub Releases
• 릴리스 페이지: https://github.com/lusile2024/WebCode/releases

현재 Windows 배포 자산은 다음과 같습니다:

WebCode-Setup-vX.Y.Z-win-x64.exe
WebCode-vX.Y.Z-win-x64-portable.zip
SHA256SUMS.txt
RELEASE_NOTES.md

설치 버전과 포터블(portable) 버전 모두 win-x64 자체 포함 런타임(self-contained runtime)을 사용합니다. 기본적으로 첫 실행 후 접속 주소는 다음과 같습니다:

http://localhost:6021

프로그램 디렉토리에는 기본적으로 다음 항목이 준비됩니다:

data/
logs/
workspaces/

설치 버전 업그레이드 시 기존의 appsettings.json은 유지됩니다.

디버깅, 2차 개발 및 로컬 연동 테스트에 적합합니다.

.NET 10 SDK가 설치되어 있고, cc-switch가 올바르게 설치되어 대상 관리 도구에 대한 설정이 완료된 경우:

• claude, codex, opencode 등 대상 CLI가 설치되어 있어야 함

git clone https://github.com/lusile2024/WebCode.git
cd WebCode
dotnet restore
...

기본 접속 주소:

http://localhost:6021

루트 디렉토리의 appsettings.json 또는 WebCodeCli/appsettings.json의 urls 설정을 수정했다면, 실제 리스닝(listening) 포트를 기준으로 확인하십시오.

현재 권장되는 초기화 프로세스 순서는 다음과 같습니다:

• 관리자 계정 생성
• 로그인 인증 활성화 여부 확인
• WebCode에서 활성화할 관리 대상 어시스턴트 선택
• 마법사(wizard)에서 cc-switch 준비 상태를 확인하고, 선택한 어시스턴트가 모두 실행 가능한지 확인
• 워크스페이스 루트 디렉토리 및 저장 디렉토리 검증
• Feishu 연동이 필요한 경우, Feishu 봇 파라미터 설정
• 다중 사용자가 필요한 경우, 관리 인터페이스에서 사용자, 디렉토리 화이트리스트 및 도구 권한 설정
• 기존 컨텍스트를 복구해야 하는 경우, 로컬 외부 CLI 세션 임포트

초기화 마법사는 더 이상 다음의 책임을 지지 않습니다:

• 관리 대상 도구의 환경 변수 수동 입력
• 관리 대상 도구의 Provider 수동 전환
• 관리 대상 도구의 라이브 설정(live config) 수동 편집

이러한 작업은 이제 반드시 cc-switch에서 완료해야 합니다.

Claude Code, Codex, OpenCode의 경우:

• Provider 전환은 cc-switch에서만 가능합니다. WebCode 설정 페이지에서는 cc-switch의 상태를 조회할 수만 있으며, 환경 변수를 수동으로 편집할 수 없습니다.
• 어시스턴트 관리 페이지에서 어시스턴트를 활성화하거나 비활성화할 수 있지만, cc-switch를 대신하여 Provider를 관리하지는 않습니다.
• 세션 수준의 "Provider 동기화(Sync Provider)"는 현재 cc-switch의 활성화 상태를 지정된 세션에 복사할 뿐, cc-switch 자체를 수정하지 않습니다.

만약 cc-switch로 관리되지 않는 커스텀 CLI를 통합하려는 경우, 여전히 CliTools.Tools를 통해 도구 정의를 확장할 수 있습니다. 관련 문서는 다음을 참고하십시오:

docker-compose.yml

기본적으로 다음 디렉토리들이 마운트됩니다:

./webcodecli-data：데이터베이스 및 실행 데이터
./webcodecli-workspaces：워크스페이스 (Workspace) 디렉토리
./webcodecli-logs：로그

기본 데이터베이스는 SQLite입니다:

WebCodeCli.db

로컬 개발 시 기본 연결 문자열 (Connection String)은 루트 디렉토리의 appsettings.json에서 가져옵니다.

저장소에는 설치 패키지 빌드 스크립트가 내장되어 있습니다:

powershell -ExecutionPolicy Bypass -File .\tools\build-windows-installer.ps1

만약 "Reply TTS / Kokoro 기능이 포함된" 로컬 Windows 설치 패키지를 생성하려면, 별도로 dotnet publish를 실행하는 대신 이 스크립트를 우선적으로 사용해야 합니다. 그 이유는 설치 패키지 스크립트가 메인 프로그램을 게시하는 것 외에도 다음과 같은 작업을 추가로 처리하기 때문입니다:

• 게시 디렉토리 내의 appsettings.json 조정
• tools/sherpa-kokoro-service 복사
• tts-bundle 조립
• Inno Setup 설치 패키지 및 Portable ZIP 생성

스크립트는 Directory.Build.props의 버전 번호를 읽어 artifacts/windows-installer/vX.Y.Z/ 아래에 다음 항목들을 생성합니다:

publish/
WebCode-vX.Y.Z-win-x64-portable.zip
installer/WebCode-Setup-vX.Y.Z-win-x64.exe
SHA256SUMS.txt
RELEASE_NOTES.md
tts-bundle/

Windows 머신에서 기본 출력 디렉토리에 이전 파일이 잠겨 있거나, Inno Setup이 긴 경로 (Long Path) 문제에 직면할 경우, 다음과 같이 명시적으로 짧은 출력 디렉토리를 지정할 수 있습니다:

powershell -ExecutionPolicy Bypass -File .\tools\build-windows-installer.ps1 -OutputRoot D:\wci

이 방식 역시 완전한 설치 버전, 휴대용(Portable) 버전 및 TTS 리소스 디렉토리를 생성하므로, 로컬에서 빠르게 패키지를 만드는 데 적합합니다.

빌드 머신 요구 사항:

• Windows
• .NET 10 SDK
• Inno Setup 6

WebCode/
├── WebCodeCli/ # Web 애플리케이션 (Blazor Server)
├── WebCodeCli.Domain/ # 도메인 서비스 (Domain Service), 리포지토리 (Repository), CLI/Feishu 어댑터
...

현재 실제 프로젝트 이름은 다음과 같습니다:

WebCodeCli
WebCodeCli.Domain

만약 이전 문서나 과거 노트에서 WebCode 또는 WebCode.Domain과 같은 이전 경로 설명을 보셨더라도, 저장소의 실제 디렉토리를 기준으로 삼아 주시기 바랍니다.

카테고리	기술
Web 프레임워크	Blazor Server
...

• QUICKSTART.md
• DEPLOY_DOCKER.md
• docs/QUICKSTART_CodeAssistant.md
• docs/README_CodeAssistant.md
• docs/superpowers/plans/2026-04-30-superpowers-plan-quick-actions-implementation.md
• docs/superpowers/specs/2026-04-30-superpowers-plan-quick-actions-design.md
• docs/superpowers/plans/2026-04-24-ralph-runtime-implementation.md
• docs/superpowers/specs/2026-04-24-ralph-runtime-design.md
• docs/workspace-management-guide.md
• docs/workspace-management-deployment-guide.md

본 프로젝트는 AGPLv3를 채택합니다.

• 오픈 소스 사용: AGPLv3를 준수합니다.
• 상업적 라이선스: 저장소 유지 관리자 또는 관련 비즈니스 채널로 문의하십시오.

AI CLI를 "로컬 명령"에서 "관리 가능하고, 배포 가능하며, 협업 가능한 워크 플랫폼"으로 업그레이드하십시오.