code-quorum

독립적인 리뷰는 에이전트 도구를 사용하는 방식에서 중요한 부분이 되었습니다. 비슷한 작업에서 영감을 받아 Code Quorum을 제 용도로 만들었고, 다른 사람들에게도 유용할 수 있어 공유합니다.

Code Quorum은 Claude Code와 Codex를 위한 macOS 멀티 에이전트 평의회입니다. 활성 호스트는 자체 리뷰, 평가 또는 계획을 작성하는 동안 외부 시트는 병렬로 작업합니다. 구조적 반편향 게이트는 최종 종합까지 모든 관점을 독립적으로 유지합니다.

기존 Claude Code, ChatGPT/Codex, Gemini/Antigravity 구독을 사용할 수 있습니다. OpenCode 시트는 OpenRouter를 사용하며 기본 모델은 DeepSeek V4 Flash입니다. 두 CLI 호스트 모두 지원되며, ChatGPT 데스크톱 앱의 Codex와 Claude 데스크톱 앱의 Code 표면도 지원됩니다.

호스트는 결코 하위 프로세스 시트가 되지 않습니다. 시작/대기 분할은 호스트가 q_await가 동료 출력을 노출하기 전에 자체 답변을 형성하도록 요구하며, 모든 평의회 스킬은 시작과 같은 턴에서 차단 완료 알림을 호출합니다.

외부 시트는 읽기 전용이지만, 읽기 전용이 데이터 로컬을 의미하지는 않습니다. 개인 자료에 Code Quorum을 사용하기 전에 보안 및 데이터 경계를 검토하세요.

저장소를 읽는 모든 MCP 평의회 시작에는 명시적인 절대 프로젝트 cwd가 필요합니다. MCP 도구는 서버의 플러그인 캐시나 런타임 디렉터리로 대체하지 않고 누락되거나 빈 값을 거부합니다. 호스트 스킬은 일반적인 /q-* 및 $code-quorum:q-* 사용 중에 이 값을 제공합니다. 계획 및 범위 파일도 해당 디렉터리 내에서 해석되어야 합니다. 절대 경로, .. 탐색, 심볼릭 링크 이스케이프는 내용을 읽기 전에 거부됩니다.

워크플로

호스트는 일치하는 일반 언어 요청에서 워크플로를 선택할 수 있습니다. 아래 양식을 사용하여 명시적으로 선택하세요:

uv run quorum --help는 정확한 셸 표면을 나열합니다. 주요 수정자는 다음과 같습니다:

리서치 소스 및 자격 증명

q-research는 기본적으로 6개 소스를 모두 쿼리합니다. --source <name>을 반복하여 실행을 제한하세요.

Code Quorum은 프로세스 환경에서 자격 증명을 읽고 인증 헤더에만 토큰을 보냅니다. 생성된 Codex 어댑터는 명명된 변수를 전달하지만 플러그인 아티팩트에 값을 저장하지는 않습니다. OpenAlex는 일반 사용에 키가 필요한 유일한 소스입니다. 나머지는 신뢰성이나 속도 한도를 개선합니다.

체크아웃에서 Hugging Face 검색을 확인하세요:

uv run quorum research "sentence embedding" --source huggingface --limit 5
uv run pytest tests/test_research_live.py -m live -k huggingface -q

CLI 검사는 모델 링크와 0이 아닌 HuggingFace 소스 수를 반환해야 합니다. 라이브 테스트는 직접 검색, 구성된 토큰 인증, 고유 용어 합집합, 전체 research_topic 경로를 다룹니다. 토큰이 없으면 인증 테스트는 건너뛰고 익명 검사는 계속 실행됩니다.

요구 사항

Code Quorum은 현재 macOS를 지원하며 Python 3.13+, uv 패키지 관리자, 사용하려는 시트의 바이너리가 필요합니다. 각 시트는 자체 로그인 또는 키에 의존합니다. Code Quorum은 플러그인 아티팩트에 자격 증명 값을 쓰지 않습니다. 시트 CLI는 SECURITY.md에 설명된 대로 자체 인증 및 런타임 상태를 유지합니다.

Gemini 시트는 macOS Seatbelt 샌드박스에 의존합니다. Claude는 대신 읽기 도구 허용 목록을 사용합니다. Codex 호스트는 Claude 및 Gemini 시트를 위해 범위가 좁은 LaunchAgent 헬퍼도 필요합니다. Codex와 OpenCode는 Seatbelt 의존성이 없지만 다른 플랫폼에서는 테스트되지 않았습니다.

설치

안정적인 체크아웃을 클론하고 시트를 구성하세요:

git clone https://github.com/sdewell/code-quorum.git
cd code-quorum
uv sync
agy  # complete Google OAuth login, then exit
uv run quorum setup-agy                    # one-time Gemini seat config
uv run quorum setup-models --host claude   # use --host codex for Codex
uv run quorum doctor --host claude         # or codex / both
uv run quorum auth-check --seat gemini --host claude

doctor는 바이너리, 구성 형태, 샌드박스 준비 상태를 확인합니다. 라이브 자격 증명은 테스트하지 않습니다. auth-check는 시트가 사용하는 것과 동일한 샌드박스에서 agy models를 실행하며 모델 프롬프트를 보내지 않고 유효한 모델 행이 하나 이상 있어야 합니다. 누락되거나 해지된 로그인은 사용자를 대화형 agy로 안내합니다. Code Quorum은 조용히 종량제 API 경로로 변경하지 않습니다.

Codex 호스트에서 Codex 인증 검사 전에 실제 터미널에서 헬퍼를 설치하고 확인하세요:

uv run quorum install-seat-helper-launchagent   # --allowed-root <dir> to widen
uv run quorum seat-helper-status
uv run quorum auth-check --seat gemini --host codex

모든 MCP 워크플로는 기본적으로 ~/Code 및 ~/src 아래의 cwd를 허용합니다. Codex 헬퍼는 Claude 또는 Gemini 요청을 수락하기 전에 동일한 루트를 적용합니다. 다른 프로젝트 루트를 사용하려면 CODE_QUORUM_HELPER_ALLOWED_ROOTS를 설정하거나 --allowed-root 옵션을 반복하여 헬퍼를 설치하세요. Code Quorum 업그레이드 후 업데이트된 안정적인 체크아웃에서 다시 설치하세요. 호환되지 않는 헬퍼 프로토콜은 실패 시 닫히며, Codex의 교체 가능한 플러그인 캐시에서 설치하는 것은 거부됩니다.

읽기 전용 경계

모든 외부 시트는 읽기 전용이며 경계를 적용할 수 없으면 실행을 거부합니다. 시트별로 적용이 다릅니다: Codex는 기본 읽기 전용 샌드박스를 사용하고, Claude는 읽기 도구만 노출하며, Gemini는 macOS Seatbelt를 사용하고, OpenCode는 제한된 권한의 격리된 HOME을 사용합니다.

Gemini의 Seatbelt 프로필은 다른 홈 디렉터리 읽기를 거부하며, agy 인증 및 런타임 상태에 대한 명시적 예외가 있습니다. $HOME 외부의 읽기 가능한 경로는 거부하지 않습니다. Code Quorum은 Claude, Codex 또는 OpenCode에 대한 보편적인 경로 펜스를 제공하지 않습니다. 평의회 자료는 사용자가 구성한 공급자 계정 아래에서 머신을 떠날 수 있습니다. 전체 경계 표, 데이터 유출 맵, 엄격한 격리 지침, 자격 증명 처리는 SECURITY.md에 있습니다.

Codex의 데이터 및 승인

Codex는 도구 승인, 파일 시스템 격리, 자료를 머신 외부로 보내는 권한을 별개의 결정으로 취급합니다. main...HEAD와 같은 대상은 준비된 리뷰 diff를 제한합니다. 외부 시트의 작업 디렉터리에 대한 읽기 전용 액세스를 제한하지는 않습니다.

approvals_reviewer = "auto_review"가 활성화되면 평의회 시작에 페이로드와 수신자를 명명하는 명시적 승인이 필요할 수 있습니다. 무인 액세스를 원하는 사용자는 도구별로 옵트인할 수 있지만, Code Quorum은 자체적으로 해당 승인 항목을 작성하지 않습니다.

SECURITY.md에는 일회성 인증 예제, 6개의 Codex 승인 블록(공유 q_await 도구 포함), 프로젝트 AGENTS.md 지침, 경로 제한 한계, 승인 보존 업데이트 절차가 포함되어 있습니다. 무인 워크플로를 활성화하기 전에 검토하세요.

구성

각 시트는 하나의 사다리를 통해 모델을 결정하며, 첫 번째로 일치하는 항목이 우선합니다: 실행별 플래그 -> 환경 변수 -> quorum setup-models에 기록된 선택 -> 제공된 고정값. 기록된 선택은 조용히 변경되지 않습니다. 이를 따를 수 없는 시트는 크게 실패를 알리며, 나머지 평의회는 계속 진행됩니다.

uv run quorum setup-models --host claude
uv run quorum setup-models --seat codex --model gpt-5.6-terra --effort medium

OpenCode 구성

OpenCode 시트는 OPENROUTER_API_KEY가 필요하며 개인 OpenCode 구성을 로드하지 않습니다. 격리된 HOME을 사용하며 매 실행 전에 이 생성된 구성을 다시 빌드합니다. 제공된 모델은 openrouter/deepseek/deepseek-v4-flash이며, OpenRouter chunkTimeout은 90000 밀리초입니다.

Code Quorum은 OPENCODE_DISABLE_PROJECT_CONFIG=1 및 OPENCODE_PURE=1을 설정합니다. 생성된 평의회 에이전트는 Read, glob, list만 허용하고, 셸 및 변형 도구를 거부하며, .env 및 .env.*를 차단하고 .env.example을 허용합니다. 실패하거나 빈 실행은 CODE_QUORUM_OPENCODE_DEBUG=0이 설정되지 않은 경우 원시 stdout/stderr 캡처를 ~/.cache/code-quorum/opencode-debug에 기록합니다. 디렉터리는 0700, 캡처 파일은 0600이며, 프롬프트 텍스트는 명령 메타데이터에서 생략되고 최신 20개의 캡처만 유지됩니다. 원시 스트림에는 여전히 검토된 자료가 포함될 수 있습니다. 전체 경계 설계는 ARCHITECTURE.md 및 SECURITY.md를 참조하세요.

시트 비활성화

라이브 프로브가 시트가 없거나 로그아웃되어 실패하면 quorum setup-models가 models.toml에서 해당 시트를 disabled로 표시할 수 있습니다. 비활성화된 시트는 기본 명단에서 건너뛰고 doctor가 보고하지만, 명시적인 --agent <seat> 요청은 여전히 실행합니다.

플러그인으로 설치

Claude Code:

/plugin marketplace add sdewell/code-quorum
/plugin install code-quorum@code-quorum

Claude Code CLI의 경우 호스트를 시작하기 전에 OPENROUTER_API_KEY 및 선택적 연구 키를 로드하세요. 예를 들어:

source ~/.zshrc.local
claude

Claude 데스크톱 앱의 경우 앱을 열기 전에 현재 macOS 로그인 세션에서 키를 사용할 수 있게 하세요:

source ~/.zshrc.local
launchctl setenv OPENROUTER_API_KEY "$OPENROUTER_API_KEY"

launchctl 값은 해제되거나 로그아웃하거나 시스템이 재부팅될 때까지 이후에 시작되는 모든 애플리케이션에 상속됩니다. Claude Code를 시작한 다음 로그인 세션 복사본을 제거하세요. 이미 실행 중인 앱은 플러그인 하위 프로세스를 위해 자체 복사본을 유지합니다:

launchctl unsetenv OPENROUTER_API_KEY

플러그인을 설치하거나 업그레이드한 후, 또는 키를 변경한 후에는 Claude Code를 완전히 종료하고 새 Claude Code 세션을 시작하세요. 플러그인 리로드는 코드 변경 사항을 반영할 수 있지만 실행 중인 호스트가 상속한 환경은 변경할 수 없습니다.

Claude 플러그인은 uv run --directory ${CLAUDE_PLUGIN_ROOT} quorum-mcp로 MCP 서버를 시작하므로 uv와 Python 3.13+가 PATH에 있어야 합니다.

Codex:

공개 마켓플레이스를 등록하고 플러그인을 설치하세요:

codex plugin marketplace add sdewell/code-quorum --ref main
codex plugin add code-quorum@code-quorum
codex plugin list

ChatGPT 데스크톱 앱의 경우 마켓플레이스를 등록한 후 앱을 완전히 종료하고 다시 여세요. 플러그인을 열고 개인을 선택한 다음 Code Quorum을 선택하고 설치를 클릭하세요.

Codex 표면 중 하나가 플러그인을 설치한 후 실제 터미널에서 안정적인 체크아웃을 준비하세요:

uv sync
uv run quorum install-seat-helper-launchagent
uv run quorum seat-helper-status

Codex 런처는 해당 체크아웃의 준비된 .venv를 직접 시작합니다. 따라서 MCP 시작은 쓰기 가능한 uv 캐시, 네트워크 다운로드 또는 교체 가능한 플러그인 디렉터리 내부의 환경에 의존하지 않습니다. 업그레이드할 때마다 체크아웃을 가져오고 uv sync를 실행한 후 새 Codex 스레드를 시작하기 전에 헬퍼를 다시 설치하세요.

Codex CLI에서 /hooks를 열어 각 code-quorum 명령 훅을 검토하고 신뢰하세요. Codex는 각 현재 정의 해시가 신뢰될 때까지 플러그인 훅을 건너뜁니다. 변경된 정의는 해당 변경된 정의에 대한 재검토와 신뢰가 필요합니다.

생성된 런처는 최소 PATH를 가진 데스크톱 앱을 위해 표준 사용자 및 Homebrew 바이너리 디렉터리(~/.local/bin, ~/.opencode/bin, /opt/homebrew/bin, /usr/local/bin)를 복구합니다.

Codex CLI의 경우 Codex를 시작하기 전에 키 환경을 소싱하세요. ChatGPT 데스크톱 앱의 경우 현재 macOS 로그인 세션에서 키를 설정하세요:

source ~/.zshrc.local
launchctl setenv OPENROUTER_API_KEY "$OPENROUTER_API_KEY"

이 값은 제거될 때까지 이후에 시작되는 모든 애플리케이션에 표시됩니다. Codex를 시작한 다음 로그인 세션 복사본을 제거하세요. 실행 중인 앱은 이미 상속한 값을 유지합니다:

launchctl unsetenv OPENROUTER_API_KEY

플러그인 업그레이드 또는 키 변경 후 Codex를 완전히 종료하고 다시 연 다음 완전히 새로운 Codex 스레드를 시작하세요. 재시작 전에 생성된 스레드를 재개하지 마세요. 해당 스레드의 도구 레지스트리는 이전 플러그인 프로세스를 참조할 수 있습니다.

승인 보존 업데이트의 경우 일반 경로로 codex plugin remove를 사용하지 마세요. SECURITY.md의 검증된 절차를 따르세요.

설계

ARCHITECTURE.md는 공유 CLI/MCP 스파인, 시트 어댑터, 라운드 모델, 반편향 메커니즘, 패키징 및 실패 경계를 설명합니다. 간단히 말하면: 1라운드에는 동료 출력이 없고, 이후 라운드는 동료를 입장별로 익명화하며, 호스트는 q_await까지 평의회 매트릭스를 받지 않습니다.

기여

다음 프로젝트가 워크플로 형태에 영감을 주었습니다. 코드, 프롬프트 또는 문서는 복사되지 않았습니다:

• SnakeO/claude-co-commands - 동료 출력 전의 독립 호스트 작업.

• agentic-box/owlex - 다중 에이전트 평의회 아키텍처 및 인지 역할.

• karpathy/llm-council - 모델 정체성보다 내용에 기반한 익명 동료 검토.

라이선스

MIT.