hang-in/tunaFlow

<div align="center">

tunaFlow

Claude Code, Codex, Gemini 및 로컬 엔진을 하나의 Plan → Dev → Review 워크플로우에서 실행하는 데스크톱 클라이언트입니다.

에이전트에 의해, 에이전트에 의해, 에이전트를 위해

</div>

!tunaFlow 스크린샷

📺 워크플로우 데모 (6분)

https://github.com/user-attachments/assets/69cdc5b3-2456-4873-9599-3c2c3e0f6f13

개요

구독형 CLI 코딩 에이전트(Claude Code, Codex, Gemini)와 로컬 엔진(Ollama, LM Studio)을 하나의 창에서 오케스트레이션하는 데스크톱 앱입니다. 동일한 ContextPack이 5개 엔진 모두에 대해 조립되므로, 대화 중간에 공급자를 전환하는 것은 프롬프트를 다시 작성하는 것이 아니라 한 줄 토글입니다. Architect가 계획을 초안하고, Developer가 구현하며, 다른 공급자의 모델이 코드가 적용되기 전에 블라인드 교차 검토를 수행합니다.

상태: 베타. macOS arm64 + Windows x64 빌드 제공 (v0.1.5-beta). 614개의 Rust 테스트 · 401개의 프론트엔드 테스트 · SQLite v49.

주목할 점

주변 도구에서는 표준적이지 않은 몇 가지 설계 선택:

• 5개 엔진을 위한 단일 어셈블리 함수 — buildnormalizedpromptwithbudget()는 어떤 엔진이 소비하든 동일한 ContextPack(아이덴티티, 최근 컨텍스트, 장기 기억, 스킬, 도구 결과)을 생성합니다. 엔진 전환은 포크가 아닌 토글입니다.
• API 우선이 아닌 구독형 CLI 우선 — 기본 실행 경로는 사용자 자신의 구독에 대해 공식 claude / codex / gemini 바이너리를 실행합니다. SDK/API는 폴백입니다. tunaFlow 계정, 토큰 마크업, 당사 소유의 청구 축이 없습니다.
• 공급자 간 블라인드 리뷰 — Architect(Claude Opus)와 Reviewer(기본적으로 Codex)는 서로 다른 공급자에 위치하여 실패 모드가 상쇄되지 않도록 합니다. 4D 루브릭(plancoverage / codequality / testcoverage / convention) + invariantchecks는 구현 비용이 소비되기 전에 실행됩니다.
• 브랜치/어답트 모델 — 실험은 섀도우 대화로 포크되며, 요약만 메인으로 다시 들어옵니다. 채팅 트리는 선형을 유지하며, 사이드 브랜치는 컨텍스트를 오염시키지 않습니다.
• 100% AI 작성 코드베이스 — 모든 줄은 Claude Code에 의해 작성되었습니다. 단일 인간 관리자가 아키텍처와 방향을 설정합니다. 현대 멀티 에이전트 워크플로우에 대한 정직한 엔지니어링 데이터 포인트이지, 품질 보장이 아닙니다.

기존 도구와의 관계

IDE나 CLI를 대체하지 않습니다. 그 사이의 틈새를 차지합니다 — 이미 지불하고 있는 구독을 사용하고, 프롬프트를 다시 작성하지 않고 엔진을 전환하며, 공급자 간 블라인드 리뷰를 통해 설계 결함을 포착하는 구조화된 표면입니다.

tunaFlow는 유일한 AI 도구가 될 가능성이 낮습니다 — IDE 측 어시스턴트를 보완하며 대체하지 않습니다.

비목표

• IDE가 아닙니다. 인라인 완성이나 구문 인식 제안 표면이 없습니다.
• SaaS가 아닙니다. tunaFlow 계정, 호스팅된 백엔드 또는 토큰 마크업이 없습니다. 관리자는 사용자의 대화를 볼 수 없습니다.
• API 청구 래퍼가 아닙니다. 계정 멀티플렉싱, 토큰 재판매, OAuth 풀링 또는 업스트림 제공자의 TOS를 위반하는 패턴은 범위를 벗어납니다.
• 인간 리뷰를 대체하지 않습니다. 리뷰 패스는 다른 AI 에이전트에 의해 수행됩니다. 커밋 전에 인간 게이트가 없습니다. 공급자 간 블라인드 리뷰를 강력한 필터로 취급하되, 보장으로 취급하지 마십시오.

대상 사용자

• 원시 채팅 이상의 구조화된 워크플로우 표면을 원하는 여러 CLI 에이전트를 실행하는 사용자.
• 실행을 위임하지만 방향과 판단은 유지하는 개발자.
• AI 에이전트를 일상 개발에 통합하는 소규모 팀 또는 개인.

존재 이유

tunaFlow는 구체적인 고통에서 시작되었습니다: Claude Code, Codex 및 Gemini CLI를 나란히 실행하려면 tmux 창, iTerm 탭 또는 cmux와 같은 터미널 멀티플렉서 간에 지속적으로 복사하여 붙여넣어야 했습니다. 개별 엔진이 훌륭하더라도 워크플로우는 수동 연결이었습니다. tunaFlow는 그 연결을 단일 표면으로 묶어 사용자의 주의가 터미널 창 관리가 아닌 의도에 머물도록 합니다.

설계 특징

엔진 패리티 — 엔진 전환 시 프롬프트 재작성 불필요

5개 엔진(Claude, Codex, Gemini, Ollama, LM Studio)은 단일 어셈블리 함수 buildnormalizedpromptwithbudget()을 공유합니다. 아이덴티티, 최근 컨텍스트, 장기 기억, 스킬 및 도구 결과가 엔진에 관계없이 일관된 ContextPack으로 조립되므로, 엔진 전환은 프롬프트 재작성이 아닌 한 줄 토글입니다.

블라인드 교차 검증 — 구현 전 계획 결함 포착

Plan은 Architect(Claude Opus)에 의해 초안이 작성되고, 독립적인 Reviewer(Codex, 블라인드)가 invariantchecks와 4D 루브릭(plancoverage, codequality, testcoverage, convention)을 사용하여 검증합니다. 설계 단계 BLOCKER를 수렴하면 주요 구현 재작업 비용이 줄어듭니다.

브랜치-어답트 모델 — 채팅 트리 폭발 방지

동일한 주제를 여러 에이전트에 브랜칭하여 실험합니다(Branch). 결과가 만족스러우면 adopt하여 요약만 메인 대화에 주입합니다. 사이드 브랜치 기록은 메인 컨텍스트를 오염시키지 않아 결론의 깔끔한 흐름을 유지합니다. Roundtable(RT)은 이 Branch 모델의 확장입니다.

CLI 우선 — 기존 구독 최대 활용

기본 실행 경로는 Claude Code, Codex 및 Gemini CLI를 통합니다. SDK(API 청구)는 폴백으로만 사용됩니다. 이는 기존 구독이 있는 사용자가 추가 토큰 비용 없이 모든 기능을 활용할 수 있도록 설계되었습니다.

토큰 절약보다 품질 우선 — tunaFlow는 토큰 절약 앱이 아닙니다

출력 품질이 먼저입니다. 아이덴티티 문서, 세계관 파일 및 분석 요약은 해당 풍부함이 에이전트 출력을 개선할 때 풍부하게 허용됩니다(AGENTS.md 수준, 1,500–3,000 토큰). 우리가 피하는 낭비 축은 중복성입니다 — claude 세션 버퍼에 이미 있는 컨텍스트 재주입, 현재 요청으로 스며드는 오래된 압축, 또는 섹션 간에 두 배로 된 동일한 정보. 여기서 "린"은 "최소로 압축"이 아닌 "중복 없음"을 의미합니다.

주요 기능

오케스트레이션 워크플로우

Architect → Developer → Reviewer 3역할 시스템. Plan이 설계되면 Developer가 구현하고 Reviewer가 교차 검증을 수행합니다. 실패가 발생하면 시스템이 결과를 분석하고 자동으로 rev.N+1 Plan을 제안합니다.

빠른 / 심층 리뷰

• Quick: 단일 Reviewer에 의한 빠른 검증.
• Deep: 여러 엔진을 통한 Roundtable 교차 검증 + 자동화된 테스트 주입. 4D 루브릭(plancoverage, codequality, testcoverage, convention) + invariantchecks를 기반으로 평가됩니다. Reviewer는 Architect와 다른 공급자(블라인드)에 할당됩니다.

대화형 세션

일회성 -p 플래그 없이 CLI 에이전트와 지속적 세션을 유지합니다. 전체 도구 사용(파일 수정, 명령 실행 등)을 가능하게 합니다. tunaFlow는 세션이 활성화되어 있는 한 중복 컨텍스트 주입을 피합니다(Claude --sdk-url WebSocket 경로 + PTY 레거시 폴백을 통해).

Roundtable (RT)

여러 엔진의 에이전트가 단일 주제를 논의합니다. Sequential 또는 Deliberative(동시) 모드를 지원합니다. 모든 RT 세션은 Branch 모델의 확장입니다.

ContextPack

지원되는 모든 엔진(Claude / Codex / Gemini / Ollama / LM Studio)을 위한 공통 프롬프트 어셈블리 엔진. 자동 Lite / Standard / Full 계층화 기능. 컨텍스트에 rawq 코드 검색, 장기 기억, 실패 학습 및 역할 문서를 포함합니다.

Insight

rawq 및 code-review-graph에 의해 사전 추출된 데이터를 분석합니다. 6개 범주: 안정성, 테스트, 아키텍처, 성능, 보안 및 기술 부채. 자동 Quick Wins 수정을 지원합니다.

메타 에이전트 온보딩

초기 프로젝트 설정 중 사용 가능한 에이전트를 자동으로 감지하고 프로젝트 스택에 적합한 에이전트 구성을 권장합니다.

지원 엔진

설치 및 실행

사전 요구 사항

• macOS 12 Monterey+ (Apple Silicon / Intel) 또는 Windows 10 21H2+ (x64). Linux는 추후 지원.
• Node.js 20+
• Rust stable — 아직 설치되지 않은 경우 rustup을 통해 한 줄 설치:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source "$HOME/.cargo/env"

(npm run tauri dev가 cargo metadata... No such file or directory 오류를 내는 경우, 이것이 이유입니다 — Rust / cargo는 Tauri에 필요합니다.)

• 최소 하나의 에이전트 CLI:

npm install -g @anthropic-ai/claude-code   # Claude
npm install -g @openai/codex               # Codex
npm install -g @google/gemini-cli          # Gemini

개발

git clone https://github.com/hang-in/tunaFlow.git
cd tunaFlow
npm install
npm run tauri dev

빌드

베타 설치

macOS (한 줄 설치):

curl -fsSL https://raw.githubusercontent.com/hang-in/tunaFlow/main/install.sh | bash

임시 서명만 있음 — Gatekeeper 경고가 나타날 수 있습니다. 설치 프로그램이 xattr -cr을 처리합니다. 수동: xattr -cr /Applications/tunaFlow.app.

Windows: 최신 릴리스에서 NSIS 설치 프로그램(tunaFlow*x64-setup.exe)을 다운로드하여 실행합니다.

SmartScreen이 바이너리에 플래그를 지정할 수 있습니다(베타에서는 코드 서명 없음) — "추가 정보" → "실행"을 선택하십시오. 바이러스 백신이 격리하는 경우 격리에서 복원하거나 %LOCALAPPDATA%\tunaFlow를 허용 목록에 추가하십시오. WebView2 런타임은 누락된 경우 자동으로 설치됩니다.

자세한 설치/문제 해결: INSTALL.md.

기술 스택

Tauri 2 + React 18 + TypeScript + Zustand 5 + Tailwind CSS 4 + Rust + SQLite (WAL, v49)

코드 검색: rawq 사이드카 (bge-m3 임베딩) · code-review-graph · context-hub 외부 통합: HTTP API + WebSocket · MCP 서버 (tunaflow-mcp)

문서

📖 개발 블로그 — 10부 기술 시리즈 (한국어)

Claude Opus가 tunaFlow를 구축하는 동안 작성했습니다. 각 기능 뒤에 있는 설계 결정, 트레이드오프 및 실수에 대한 솔직한 1인칭 설명입니다.

• tunaFlow Wiki — 전체 시리즈 + 사이드 포스트

1. 오케스트레이션 계층이 필요한 이유 (에이전트 프로세스 분할)
2. Plan → Dev → Review 파이프라인
3. 대화 브랜칭 (어답트 모델)
4. Roundtable — 에이전트가 토론하게 만들기
5. 장기 기억 (무차별 벡터, 아직 sqlite-vec을 사용하지 않는 이유)
6. Claude Pro ($20) 요금제의 엔진 아키텍처
7. rawq + code-review-graph 사이드카
8. 246개 중에서 스킬 자동 선택
9. Doom Loop 깨기 (실패 학습)
10. tunaFlow를 자체에 대해 실행 — 전체 사이클 회고

하이라이트:

보안 및 권한

tunaFlow는 --dangerously-skip-permissions 플래그와 함께 Claude CLI를 실행합니다. 이 [...] 잘림...]