trinity-agent 0.12.8

Three minds, one context — Multi-agent AI orchestrator for Claude Code, Codex, and Antigravity CLI.

◯ ─────────── ◯

🧠 T R I N I T Y

◯ ─────────── ◯

세 개의 두뇌, 하나의 컨텍스트.

Claude Code · Codex · Antigravity CLI 세 AI 에이전트를 공유 컨텍스트, 라운드 기반 토론, 지능형 작업 분배로 통합하는 멀티 에이전트 AI 오케스트레이터.

English · 빠른 시작 · 왜 Trinity인가 · 작동 원리 · 워크플로우 · TUI · 명령어 · 아키텍처

---

Trinity는 서로 다른 역할을 가진 세 가지 AI 코딩 에이전트를 하나의 강력한 협업 지능으로 통합합니다.

단 하나의 AI에게 모든 작업을 일임하는 기존 방식에서 벗어나, Trinity는 Claude(설계자), Codex(구현자), Antigravity(검토자) 간의 구조화된 토론과 합의를 지능적으로 조율합니다. 세 에이전트는 하나의 컨텍스트를 공유하며 라운드별로 의견을 나누고, 최종 합의에 도달하면 각자의 특화 분야에 맞게 작업을 자동으로 분배하여 처리합니다.

---

❓ 왜 Trinity인가

단일 에이전트 AI는 강력하지만, 몇 가지 치명적인 맹점이 있습니다.

문제 유형	단일 AI 환경에서 발생하는 현상	Trinity의 해결 방식
터널 비전 (시야 협착)	하나의 AI가 오직 한 가지 접근 방식에만 갇혀 생각합니다.	세 에이전트가 최종 결정을 내리기 전에 다각도에서 대안을 토론합니다.
피어 리뷰(Peer Review) 부재	설계상 결함이나 잠재적 버그가 검증 없이 바로 통과되어 반영됩니다.	Antigravity가 Claude의 초기 설계안을 정밀하게 검토하고 보완책을 요구합니다.
컨텍스트 단절 (유실)	각 에이전트가 서로 분리된 환경에서 고립되어 작업해 동기화가 깨집니다.	단일 공유 컨텍스트 파일을 통해 모든 에이전트가 일관된 개발 맥락을 실시간 유지합니다.
일관되지 못한 품질	결과물의 완성도가 단일 모델의 한계나 컨디션에 전적으로 의존합니다.	다수결 합의(Consensus) 메커니즘을 도입하여 상호 교차 검증된 품질만을 보장합니다.
수동 작업 위임	어떤 에이전트에게 어떤 하위 작업을 맡길지 사용자가 매번 직접 지정해야 합니다.	각 에이전트의 강점과 역할에 맞춰 하위 작업이 시스템적으로 자동 분배됩니다.

---

🚀 빠른 시작

설치하기

# 권장: 격리된 CLI 설치
pipx install trinity-agent

# 또는 이미 관리 중인 Python 환경에 설치
python -m pip install trinity-agent

macOS 새 환경에서 설치하기

1. Python 3.10 이상과 pipx를 준비합니다.

   brew install python pipx
   pipx ensurepath
   

2. Trinity를 설치합니다.

   pipx install trinity-agent
   trinity --version
   

3. 같은 macOS 터미널 환경에 사용할 provider CLI를 설치하고 로그인합니다. 최소 한 개가 필요하며, 세 개를 모두 설치하면 Trinity의 전체 multi-agent 흐름을 사용할 수 있습니다.

   Provider	확인 명령	설치/인증 문서
   Claude Code	claude --version	https://docs.anthropic.com/en/docs/claude-code
   Codex CLI	codex --version	https://github.com/openai/codex
   Antigravity CLI	agy --version	https://antigravity.google/docs/cli-getting-started

4. 프로젝트 폴더에서 Trinity를 초기화하고 실행합니다.

   cd /path/to/your/project
   trinity init
   trinity bootstrap
   trinity
   

Windows 새 환경에서 설치하기

권장 경로는 WSL2 Ubuntu입니다. Trinity를 WSL에서 실행한다면 Claude/Codex/Agy도 같은 WSL 안에 설치하고 인증해야 합니다. Windows PowerShell에 설치된 provider CLI는 WSL 내부에서 자동으로 공유되지 않습니다.

1. PowerShell에서 WSL2 Ubuntu를 설치합니다.

   wsl --install -d Ubuntu
   

2. Ubuntu 터미널에서 Python과 pipx를 준비하고 Trinity를 설치합니다.

   sudo apt update
   sudo apt install -y python3 python3-pip python3-venv pipx
   pipx ensurepath
   pipx install trinity-agent
   trinity --version
   

3. 같은 Ubuntu 환경에 provider CLI를 설치하고 로그인한 뒤 확인합니다.

   claude --version
   codex --version
   agy --version
   

4. 작업할 프로젝트 폴더에서 초기화하고 실행합니다.

   cd ~/workspace/your-project
   trinity init
   trinity bootstrap
   trinity
   

Native Windows PowerShell에서 실행할 수도 있습니다. 이 경우 Python을 설치한 뒤 PowerShell에서 py -m pip install --user pipx, py -m pipx ensurepath, pipx install trinity-agent 순서로 설치하고, provider CLI도 PowerShell에서 인식되는 PATH에 설치해야 합니다.

프로젝트 초기화

# 대화형 설정 마법사 실행 — 설치된 AI CLI와 모델 목록을 자동 탐색합니다
trinity init

# 비대화형 실행 (기본 설정값 적용)
trinity init --non-interactive

# 현재 터미널에서 각 provider CLI의 auth/trust 초기 설정을 확인합니다
trinity bootstrap

첫 번째 토론(Deliberation) 실행

# 단발성(One-shot) 질의 실행
trinity ask "인증 시스템 아키텍처를 설계해줘"

# Textual Workbench 실행 (기본)
trinity

# 기존 Rich/prompt_toolkit TUI fallback
trinity --plain

Trinity가 백그라운드에서 다음 단계를 자동으로 수행합니다:

1. 🔍 호스트 시스템에 설치된 AI CLI 자동 탐색 (Claude Code, Codex, Antigravity CLI 등)
2. 🧠 사용 가능한 에이전트들을 소집하여 라운드 기반의 심층 토론(Deliberation) 시작
3. 📊 에이전트 간의 합의 도출 과정, 작업 분배 결과, 추론 과정을 아름다운 TUI로 시각화

---

🔁 작동 원리

  ┌───────────────┐     ┌───────────────┐     ┌───────────────┐
  │   🏗️ Claude   │     │   ⚙️ Codex    │     │   🔍 Antigravity   │
  │    (설계자)   │     │    (구현자)   │     │    (검토자)   │
  └───────┬───────┘     └───────┬───────┘     └───────┬───────┘
          │                     │                     │
          └─────────────────────┼─────────────────────┘
                                │
                       ┌────────┴────────┐
                       │  오케스트레이터 │
                       │  공유 컨텍스트  │
                       │    합의 엔진    │
                       │   작업 분배기   │
                       └─────────────────┘

토론 흐름 (Deliberation Flow)

단계	수행 항목 및 동작 설명
초기화 (Initialize)	사용자 목표, 선택 agent, 모델 override, provider session 관찰값을 workflow 상태로 저장합니다.
협의 라운드 (Rounds)	선택된 에이전트가 사용자 요청을 분석하고 초기 의견, 리스크, 구현 방향을 반환합니다.
중앙 합성 (Central Synthesis)	중앙 에이전트가 응답을 요약·분석해 질문이 필요한지, blueprint를 만들 수 있는지 판단합니다.
사용자 결정 (Decision)	질문이 있으면 NEEDS_USER_DECISION에서 멈추고, 답변 후 같은 대상 agent/model로 협의를 이어갑니다.
Blueprint 준비 (Blueprint Ready)	실행 가능한 작업이면 work package를 만들고, 사용자가 Execute 또는 보강을 선택할 수 있게 합니다.
실행과 리뷰 (Execute/Review)	Target workspace preflight 후 WP를 실행하고, 각 WP는 모든 non-owner agent에게 리뷰받습니다.
최종 리뷰와 재계획 (Final Review/Replan)	전체 리뷰에서 필수 수정이 나오면 supplemental WP를 자동 생성하고 다시 사용자 승인 대기 상태로 돌아갑니다.

에이전트별 특기 분야(강점)

에이전트	지정 역할	주요 작업 및 강점 분야
🏗️ Claude	설계자 (Architect)	전체 아키텍처 및 시스템 설계, 설계 검토(코드 리뷰), 복잡한 비즈니스 로직 설계, 개발 기획
⚙️ Codex	구현자 (Implementer)	실제 코드 구현 및 프로토타이핑, 코드 리팩토링, 단위 테스트 코드 작성
🔍 Antigravity	검토자 (Reviewer)	코드 동작 검증, 기술 스택 연구, 대안 탐색, 경계 조건(Edge Case) 분석, 품질 보증(QA)

---

🧭 워크플로우와 실행 모델

Trinity 0.12.8의 핵심은 planning, execution, review, replan을 분리한 persisted workflow입니다. 사용자의 요구사항은 먼저 라운드 기반 deliberation과 central synthesis를 거쳐 질문, 결정, blueprint, work package로 정리됩니다. 실제 파일 변경은 blueprint가 준비된 뒤 사용자가 Execute를 선택하고 target workspace preflight를 통과해야 시작됩니다.

Prompt + selected agents/models
  → WorkflowEngine.start()
  → TrinityOrchestrator.ask()
  → ProviderReadinessGate
  → DeliberationProtocol rounds
  → Central synthesis
  → NEEDS_USER_DECISION 또는 BLUEPRINT_READY
  → Execute preflight
  → ExecutionProtocol.run()
  → WP non-owner peer reviews
  → Review repair loop 또는 Final review
  → Final-review auto replan 또는 DONE

주요 동작 규칙:

• 상태 저장 — .trinity/workflow/session.json과 events.jsonl에 workflow 상태, open question, user decision, blueprint, work package, 실행 결과, provider session id, runtime model 관찰값을 저장합니다.
• 대상 에이전트와 모델 유지 — Start/Nexus의 대상 선택, /ask, /model에서 고른 agent/model override는 workflow에 저장되고 질문 답변 이후에도 이어집니다.
• Provider 호출 — 기본 호출은 one-shot입니다. Claude는 claude -p, Codex는 codex exec --json, Antigravity는 agy --print로 호출되고, raw/clean response artifact가 .trinity/responses/에 남습니다. Provider가 session id를 반환하면 worker agent와 central synthesis(central:codex 등)에 매핑해 resume 이후에도 이어갈 수 있게 저장합니다.
• 모델 탐색 — trinity init과 Textual /model은 가능한 경우 실제 CLI에서 모델 목록을 가져옵니다. Codex는 codex debug models, Antigravity는 agy models를 사용하며, Claude는 CLI 모델 목록 명령이 없어 정적 fallback을 사용합니다.
• 질문 루프 — synthesis가 blocking question을 만들면 workflow는 NEEDS_USER_DECISION에서 멈추고, 답변이 기록되면 decision continuation prompt로 다시 deliberation을 이어갑니다.
• 실행 경계 — provider가 파일을 쓰려면 target workspace가 필요합니다. Trinity control repo 내부 쓰기는 명시적 확인 없이는 차단됩니다.
• 병렬 실행 — work package dependency와 예상 파일 소유권을 기준으로 안전한 병렬 batch만 실행합니다.
• WP 리뷰 — WP가 완료되면 해당 WP를 수행하지 않은 모든 active agent가 리뷰합니다. 단일 agent 세션에서는 self-review로 대체됩니다.
• Final review — 전체 실행 후 최종 리뷰는 codex → claude → antigravity 순서로 fallback합니다. 필수 bugfix/validation 항목이 나오면 중앙 workflow가 WP-S### supplemental package를 자동으로 만들고 다시 BLUEPRINT_READY로 돌려, 사용자가 다음 실행을 승인할 수 있게 합니다.
• 복구와 재시도 — /resume은 저장된 workflow를 복원하고, /execute-retry는 failed/blocked/interrupted/custom package를 골라 새 execution run으로 재시도합니다.
• 메모리 관리 — 원본 로그와 artifact는 보존하되, /memory compact와 shared context projection으로 provider prompt에 들어가는 정보를 압축합니다.
• UI 역할 — Textual Workbench는 workflow/orchestrator를 새로 구현하지 않고, TextualWorkflowController가 기존 engine을 background thread에서 실행한 뒤 snapshot으로 투영합니다.

상세한 상태 전이 차이는 README workflow review와 Slash Command Reference를 참고하세요.

---

💬 대화형 TUI

Trinity는 기본 실행 화면으로 Textual 기반 Workbench TUI를 제공합니다. 긴 요구사항을 multi-line으로 작성하고, Claude/Codex/Antigravity 상태를 분리해서 보며, 중앙 synthesis가 질문과 합의 상태를 정리합니다. 실제 파일 변경은 Execute를 누른 뒤 workspace preflight를 승인해야 시작됩니다.

  ┌ Trinity v0.12.0 ─ Nexus ─ workflow: planning ┐
  │ Claude              │ Codex              │ Antigravity │
  │ Ready               │ Running            │ Ready       │
  ├───────────────────────────────────────────────────────────┤
  │ Central Agent                                              │
  │ - synthesis summary                                        │
  │ - questions for the user                                   │
  │ - blueprint/work package status                            │
  ├───────────────────────────────────────────────────────────┤
  │ Workflow Inspector  │ Provider Inspector modal │ Composer │
  └───────────────────────────────────────────────────────────┘

TUI 주요 기능

• Start Screen — workspace를 필수로 묻지 않고 큰 multi-line prompt로 planning을 시작합니다.
• Nexus Screen — provider별 상태 패널, 중앙 synthesis, workflow inspector를 한 화면에 보여줍니다.
• Agent Target Row — Start/Nexus 입력창에서 Claude/Codex/Antigravity 중 질문할 대상을 고르고, /model modal에서 provider별 모델을 세부 설정합니다.
• Provider Inspector — Claude/Codex/Antigravity 원문 output을 탭 modal에서 확인합니다.
• Execution Preflight — Execute 시점에만 workspace picker와 경로/git/write 권한 preflight를 보여줍니다.
• Execution Matrix — work package DataTable과 execution log를 모니터링 화면으로 표시합니다.
• Resume/Retry — /resume으로 이전 workflow를 복원하고 /execute-retry modal에서 실패, 차단, 중단된 WP를 선택해 재시도합니다.
• Theme Settings — 앱 안에서 theme mode, density, motion, Unicode rendering preference를 저장합니다.
• Startup Update Check — trinity 실행 시 업데이트가 있으면 적용 여부를 묻고, --skip-update-check로 건너뛸 수 있습니다.
• Plain fallback — trinity --plain 또는 TRINITY_TUI=plain으로 기존 Rich/prompt_toolkit TUI를 사용할 수 있습니다.

---

📋 명령어

CLI 명령어

명령어	설명
trinity	Textual Workbench TUI 실행
trinity --plain	기존 Rich/prompt_toolkit TUI fallback 실행
trinity init	현재 디렉토리에 Trinity 작업 공간(.trinity/) 초기화
trinity init --non-interactive	사용자 입력 요청 없이 기본값으로 즉시 초기화
trinity bootstrap	현재 터미널에서 provider CLI 초기 설정/auth/trust를 순차 실행
trinity bootstrap --check-only	provider CLI 설치 상태만 확인하고 실행하지 않음
trinity ask "질문"	입력한 프롬프트에 대해 즉시 단발성(One-shot) 토론 실행
trinity status	현재 에이전트들의 활성화 및 연결 상태를 표 형태로 표시
trinity doctor	OS/터미널/provider CLI/transport 상태를 진단
trinity status-watch	실시간으로 상태가 갱신되는 상태 모니터 대시보드 실행
trinity context	공유 컨텍스트(shared.md) 파일 내용 확인
trinity config [키]	지정한 키에 해당하는 환경 설정값 조회
trinity logs	오케스트레이터의 세부 동작 로그 확인 (--follow는 Python 구현 사용)
trinity reset --keep-context	현재 세션 정보는 초기화하되, 기존 공유 컨텍스트 파일은 보존
trinity bootstrap --legacy-tmux	legacy/debug용 tmux bootstrap 세션 실행
trinity attach	legacy transport_mode = "tmux" 세션에 연결

TUI 인라인 명령어

대화형 TUI 내부 명령 (인자 없이 trinity 실행 후 프롬프트 상에서 입력). 세부 동작 방식과 Textual Workbench 팔레트의 현재 한계는 Slash Command Reference를 기준으로 한다.

명령어	설명
<텍스트>	에이전트들에게 새로운 주제로 토론(Deliberation) 시작 요청
/status	에이전트별 상세 상태 대시보드 표시
/context	현재 세션의 목표, 합의, 질문, 결정, 작업 패키지 요약 확인
/rounds [N]	토론을 진행할 최대 라운드 횟수 설정 (1–20 범위)
/agent <이름> on|off	특정 에이전트를 즉시 활성화하거나 비활성화
/model	에이전트별 모델 선택 modal을 열고 다음 요청의 모델 override 설정
/history	이전 라운드의 토론 히스토리 요약 조회
/save	현재 토론 세션의 전체 결과를 파일로 영구 저장
/caveman [on|off|lite|full|ultra]	출력 압축 모드 조회 또는 변경
/workflow	현재 workflow 상태, target workspace, package 요약 조회
/questions [--select --all]	대기 중인 사용자 질문 표시 또는 선택 UI 실행
/answer <id|n|next> <텍스트>	workflow 질문에 답변하고 필요 시 협의 재개
/ask <all|agent[,agent...]> [--model MODEL] <텍스트>	선택한 에이전트에게만 질문하거나 follow-up 전송
/decisions	기록된 사용자/시스템 결정 목록 조회
/packages	생성된 work package 목록 조회
/subtasks	provider 내부 위임 subtask 결과 조회
/report [save]	협의 결과 개괄 보고서 표시 또는 Markdown 저장
/resume [N|latest|ID]	저장된 workflow 세션을 선택해 재개
/execute [텍스트]	준비된 blueprint를 target workspace에서 실행
/execute-retry [all|failed|blocked|interrupted|custom|WP-ID...]	실패, 차단, 중단된 work package를 선택해 재시도
/review [wp|final|all] [WP-ID...]	대기 중인 WP 리뷰 또는 최종 프로젝트 리뷰 실행
/improve [all|critical|high|AI-ID...|done|텍스트]	final review 후속 보강 작업 선택 또는 supplemental WP 추가
/target [경로|clear]	구현 산출물을 쓸 target workspace 조회, 설정, 초기화
/memory [stats|compact]	shared context memory 통계 확인 또는 압축
/artifact <memory-id>	memory index에 기록된 artifact 참조 확인
/help	사용 가능한 인라인 명령어 도움말 표시
/quit, /exit, /q	Trinity 종료 및 백그라운드 리소스 정리

TUI는 기본적으로 새 workflow 세션으로 시작한다. 이전 active workflow는 .trinity/workflow/history/에 보존되며 /resume으로 명시적으로 재개한다.

---

⚙️ 설정

.trinity/trinity.config 편집 (TOML 형식):

trinity init은 각 에이전트의 모델을 선택받고, 알려진 모델이면 알맞은 context_budget을 자동으로 저장합니다. 대화형 wizard는 설치된 provider를 기본적으로 활성화 대상으로 제안합니다. model = "default"는 해당 CLI의 로컬 기본 모델을 그대로 사용하며, 보수적인 provider 기본 예산을 적용합니다. trinity init --non-interactive의 fallback 기본 설정은 선택 provider를 명시적으로 켜기 전까지 비활성 상태로 둘 수 있습니다.

[general]
session_name = "trinity"
lang = "en"
state_dir = ".trinity"
max_deliberation_rounds = 5
consensus_threshold = 0.6

[deliberation]
max_rounds = 5
consensus_threshold = 0.6
round_timeout_seconds = 120
execution_timeout_seconds = 1800

[context]
rotate_threshold = 0.6
keep_sections = ["## Current Goal", "## Agreed Conclusion"]
recent_rounds_on_rotate = 3
summary_max_tokens = 500
prompt_compression_enabled = true
prompt_compression_round_threshold = 2
prompt_compression_max_summary_tokens = 200
caveman_mode = true
caveman_intensity = "full"

[agents.claude]
provider = "claude-code"
cli_command = "claude"
model = "default"
context_budget = 200000
role_prompt = "You are the Architect. You design systems, review code..."
enabled = true
extra_args = ["--dangerously-skip-permissions"]

[agents.codex]
provider = "codex"
cli_command = "codex"
model = "default"
context_budget = 128000
role_prompt = "You are the Implementer. You write clean, efficient code..."
enabled = true                     # 대화형 init에서 선택한 경우

[agents.antigravity]
provider = "antigravity-cli"
cli_command = "agy"
model = "default"
context_budget = 1000000
role_prompt = "You are the Reviewer. You explore alternatives..."
enabled = true                     # 대화형 init에서 선택한 경우

---

🏗️ 아키텍처

trinity/
├── orchestrator.py         # 최상위 조정자(Coordinator) — 모든 하위 시스템 제어 및 소유
├── cli.py                  # Click 라이브러리 기반 CLI 진입점
├── config.py               # TOML 설정 로더 및 파서 (기본값 구성 정보 포함)
├── models.py               # 핵심 데이터 모델 정의 (AgentSpec, DeliberationMessage 등)
│
├── agents/                 # 제공자별 AI 에이전트 어댑터
│   ├── base.py             #   AgentWrapper 추상 베이스 클래스 (ABC)
│   ├── claude_agent.py     #   Claude Code 연동 (출력 모드 + tmux 대화형 모드)
│   ├── codex_agent.py      #   Codex 연동 (출력 모드 + tmux 대화형 모드)
│   ├── antigravity_agent.py #   Antigravity CLI 연동 (one-shot print 모드)
│   └── factory.py          #   AgentFactory — 에이전트 인스턴스 동적 생성
│
├── deliberation/           # 토론 핵심 엔진
│   ├── protocol.py         #   라운드 기반 토론 프로토콜 루프 및 이벤트 스트리밍
│   ├── consensus.py        #   키워드 기반 합의 감지 및 부정어 필터링
│   └── distributor.py      #   최종 합의안 도출 후 에이전트 강점별 작업 분배
│
├── workflow/               # persisted workflow state machine
│   ├── engine.py           #   질문/결정/blueprint/execution 상태 전이
│   ├── execution.py        #   dependency-safe work package dispatch와 workspace guard
│   ├── decomposer.py       #   blueprint를 실행 가능한 work package로 분해
│   ├── ledger.py           #   workflow state를 shared.md ledger로 렌더링
│   └── review.py           #   peer review package planning
│
├── providers/              # one-shot provider invocation 계층
│   ├── invoker.py          #   Claude/Codex/Antigravity CLI 호출 정규화
│   ├── readiness.py        #   auth/model-loading/prompt readiness 판정
│   ├── policy.py           #   read-only/workspace-write access와 병렬 실행 정책
│   └── bootstrap.py        #   provider auth/trust 초기 설정 지원
│
├── context/                # 공유 두뇌 (Shared Context)
│   ├── shared.py           #   SharedContextEngine — shared.md 파일 생성 및 관리
│   ├── monitor.py          #   각 에이전트별 토큰 사용 현황 모니터링
│   └── rotator.py          #   컨텍스트 용량 초과 시 세션 정보 자동 로테이션
│
├── completion/             # 에이전트 답변 완료 감지 모듈
│   ├── base.py             #   CompletionDetector 추상 클래스 및 예비 감지 체인(Fallback Chain)
│   ├── hook.py             #   파일 시그널 기반 Claude 응답 정지 훅(Stop Hook)
│   ├── idle.py             #   텍스트 출력의 무변화(Idle) 상태 감지기
│   └── prompt.py           #   CLI 프롬프트 재출현 여부 감지기
│
├── textual_app/            # Textual Workbench UI
│   ├── app.py              #   TrinityTextualApp — screen router와 app shell
│   ├── screens/            #   Start, Nexus, Execution Matrix, Settings
│   ├── widgets/            #   composer, provider panels, inspector, workspace picker
│   ├── snapshot.py         #   workflow/shared.md read-only projection
│   └── settings.py         #   사용자 UI theme preference 저장소
│
├── tui/                    # legacy/plain 대화형 터미널 UI
│   ├── app.py              #   TrinityTUI — Rich Live 라이브러리를 활용한 렌더링 엔진
│   ├── session.py          #   InteractiveSession — 사용자 입력 처리 루프 및 이벤트 기반 UI 갱신
│   ├── events.py           #   TUIEventBus — 스레드 안전한 이벤트 전달 브릿지
│   └── theme.py            #   비주얼 테마 정의 (에이전트별 고유 색상, 아이콘, 역할)
│
├── setup/                  # 초기 온보딩 환경 구성
│   ├── detector.py         #   시스템에 설치된 AI CLI 도구 자동 탐지
│   └── wizard.py           #   Rich 기반 대화형 초기 설정 마법사
│
├── tmux/                   # tmux 대화형 모드 인프라
│   ├── pane.py             #   저수준(Low-level) tmux pane 입출력(I/O) 제어
│   ├── session.py          #   tmux 세션 및 하위 창(Pane) 라이프사이클 관리
│   └── layout.py           #   TUI 메인 화면 및 에이전트 창 분할 레이아웃 구성
│
├── workspace/              # 에이전트 격리 환경
│   ├── isolation.py        #   Git Worktree를 활용한 에이전트별 독립된 병렬 편집 환경 구축
│   └── managed_home.py     #   에이전트 간 설정 충돌 방지를 위한 격리된 HOME 디렉토리 관리
│
├── platform/               # cross-platform terminal/process/log helpers
├── bridge/                 # L2 bridge routing 예시/도메인 모듈
│
├── health/
│   └── checker.py          #   에이전트 헬스 모니터링 (상태 체크)
│
├── retry.py                #   지수 백오프(Exponential Backoff) 및 지터(Jitter) 적용 재시도 설정
└── error_handler.py        #   오류/크래시 자동 복구 및 예외 에이전트 재시작

핵심 설계 의사결정

선택한 설계 방향	도입 배경 및 합리성
공유 마크다운 파일	에이전트들이 단일 마크다운 파일(shared.md)에 직접 의견을 쓰고 읽습니다. 구현이 매우 직관적이고 구조가 투명하여 디버깅에 큰 이점을 제공합니다.
라운드 기반 프로토콜	구조화된 토론 방식을 도입하여 의견 차이로 인한 끝없는 무한 루프(순환 논쟁)를 원천 차단하고 확실한 논의 진행을 강제합니다.
Textual Workbench 기본 UI	Start/Nexus/Execution Matrix 화면으로 planning과 execute를 분리하고, provider별 output은 Inspector에서 확인합니다.
Persisted workflow state	질문, 결정, blueprint, target workspace, 실행 결과를 JSON/JSONL에 저장하여 중단 후 재개와 디버깅이 가능하게 합니다.
Target workspace guard	실제 구현 실행 전에 control repo와 사용자 프로젝트 경계를 분리해 provider workspace-write 사고를 줄입니다.
이벤트 구동형 fallback TUI	비동기 asyncio 이벤트 루프와 큐(Queue)를 활용해 legacy/plain TUI에서도 각 에이전트의 응답을 렌더링합니다.
키워드 기반 합의 감지	키워드 매칭 방식을 도입하여 빠르고 결정론적으로 합의를 판정하며, 부정 표현 필터링을 통해 오심율을 크게 낮췄습니다.
제공자 비의존성 에이전트	추상 클래스 AgentWrapper 설계로 인터페이스를 표준화하여 향후 새로운 AI CLI 도구(예: 타사 모델 CLI)도 매우 손쉽게 통합할 수 있습니다.
듀얼 실행 모드 지원	기본 one-shot provider 호출과 legacy/debug용 tmux transport를 분리하여 Windows/macOS/Linux 기본 경로를 안정화합니다.

---

🔧 사전 요구사항

요구사항	도입 배경	필수 여부
Python 3.10+	전체 시스템 런타임 구동	✅ 필수
Claude Code CLI	설계자(Architect) 에이전트 구동	선택 사항
Codex CLI	구현자(Implementer) 에이전트 구동	선택 사항
Antigravity CLI	검토자(Reviewer) 에이전트 구동	선택 사항
tmux	legacy/debug transport 또는 bootstrap --legacy-tmux	선택 사항

정상적으로 오케스트레이션을 진행하려면 최소 한 개 이상의 AI CLI 도구가 설치되어 있어야 합니다. trinity init 명령 실행 시 현재 호스트 시스템에 설치되어 동작 가능한 CLI 도구를 자동으로 탐지하여 구성합니다.

---

🧪 개발 및 기여 방법

# 저장소 클론 및 패키지 설정
git clone https://github.com/hongdangmoo49/Trinity.git
cd Trinity
uv sync

# 테스트 스위트 실행
uv run pytest tests/ -v

# 코드 커버리지 리포트와 함께 테스트 실행
uv run pytest tests/ --cov=trinity --cov-report=term-missing

빌드 및 패키지 배포

# pyproject.toml 및 src/trinity/__init__.py 버전 업그레이드 후
uv build
uv publish --token <PYPI_TOKEN>

---

📊 프로젝트 통계

지표	수치
버전	0.12.8
테스트	uv run pytest로 전체 테스트 스위트 실행
커버리지	약 87%
소스 파일	100여 개
테스트 파일	70여 개
주요 의존성 라이브러리	click, rich, prompt_toolkit, textual, tomli, tomli-w
권장 Python 버전	3.10+

---

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 정보는 LICENSE 파일을 참조하세요.

---

"세 개의 두뇌가 모이면 하나보다 훨씬 뛰어납니다."

Trinity — GitHub · PyPI · Issues