EQMUX

EQMUX

*한국어 · [English](README.en.md)*

**하나의 git 저장소를 AI 에이전트 팀이 함께 작업하고, 사람이 그것을 관제하는 데스크톱 앱.**

EQMUX는 터미널 멀티플렉서(MUX)에 에이전트 팀 관제를 얹은 Windows 데스크톱 앱입니다. 워크스페이스(= git repo 1개 = 팀 1개 = 탭 1개)마다 Claude Code 세션을 기본 4개(설정에서 6·8까지) 병렬로 띄우고, 관제 대시보드에서 상태를 보고, 임무를 배정하고, 필요할 때 개입합니다.


핵심 원칙

• 관제가 핵심이다. 대시보드에서 팀 상태(busy / waiting / dead)를 보고, 임무를 배정하고, 개입한다.
• 터미널 페인이 작업 공간이다. 실제 일은 각 페인의 에이전트 CLI(Claude Code)가 한다.
• 앱은 API 키를 보유하지 않는다. 자체 AI 루프 없이 외부 CLI를 실행할 뿐이다.
• 파일이 원본이다. 팀·역할·임무의 원본은 .eqmux/ 아래 파일이고, DB는 캐시다. 불일치 시 파일이 이긴다.
• 자동 실행 경로는 없다. 상태를 바꾸는 것은 언제나 사용자의 버튼이다. 재시작 후에도 자동 재개 대신 재개 제안만 띄운다.

도메인 모델

앱  ─────────────────── 워크스페이스 최대 10개 동시 오픈
└─ 워크스페이스 ──────── = git repo 1개 = 팀 1개 = 탭 1개
   ├─ 세션 1~N ───────── = 에이전트 1명 = 터미널 페인 1개
   │  └─ 역할 ────────── = 직무(job) + 페르소나(persona)
   └─ 임무 ───────────── = repo 안의 작업 단위 (브랜치 + 목표)

세션 슬롯 N은 기본 4개이고 설정에서 6·8로 올릴 수 있습니다. 기본값이 4인 것은 리소스가 아니라 **가독성** 때문입니다 — 1920×1080 기준 2×2 분할이 에이전트 TUI를 읽을 수 있는 한계입니다. 팀 편성(`team.json`)은 이 설정과 무관하게 최대 8슬롯을 허용합니다. 에디터·diff·브라우저 같은 보조 페인은 세션 슬롯을 소비하지 않습니다.

주요 기능

• 관제 대시보드 — 워크스페이스×세션 그리드, 주의 필요 순 정렬, waiting/dead 우선 표시, 상태 전이·서브에이전트·임무 이벤트 피드, OS 알림
• 터미널 워크스페이스 — ConPTY + xterm.js, 페인 배치 6종 + 분할선 드래그 + 줌, 터미널 내 검색(Ctrl+F), 링크 감지, 클립보드·드래그 앤 드롭
• 에이전트 런타임 — Claude Code 세션 기동(--session-id·권한 플래그), 레지스트리 watch + 훅 기반 상태 감지, 재개(resume)·권한 재시작, degraded 관측 저하 표시
• 팀·역할·임무 — 편성 프리셋, 직무/페르소나 라이브러리(전역 + 워크스페이스 오버라이드), 역할 파일 frontmatter가 실행 권한을 결정, 세션별 git 워크트리 격리 옵트인
• 세션 영속성 — SQLite(WAL) 스크롤백 저장, 재시작 시 마지막 500줄 재생(SGR 색 보존) + 재개 제안, FTS 전문 검색, Job Object로 자식 프로세스 트리 정리, 웹뷰 크래시 생존
• 메시지 버스 — 에이전트 간 강제 타입 메시지(ask / handoff / report / review / escalate), 상태 기반 전달(유휴면 즉시, 작업 중이면 턴 종료 시), 사람도 @세션·@all로 참여, 대화 원장 전체를 Markdown 파일로 저장
• 개발 도구 패널 — git(상태·워크트리·체크아웃)·탐색기(파일 CRUD)·포트·로그·diff 뷰어·localhost 브라우저
• 트랜스크립트 뷰 — Claude Code JSONL 로그를 턴 단위로 열람(참조만), 도구 호출 접기, 스크