Omnigent 딥다이브
— "모든 AI 에이전트를 하나로 묶는" 메타-하네스

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

핵심을 한 문장으로: "에이전트들의 운영체제(OS)"를 표방한다. 개별 에이전트 CLI가 "앱"이라면, Omnigent는 그 앱들을 띄우고·관리하고·서로 통신시키고·권한을 통제하는 바탕 레이어다.

2왜 주목받는가

트렌딩 이유와 경쟁 제품 대비 장점.

① "벤더 록인(lock-in)" 깨기 — 하네스 추상화

지금 코딩 에이전트 시장은 Claude Code, Codex, Cursor, Gemini CLI 등으로 파편화돼 있다. 각자 다른 CLI·설정·세션 포맷을 쓴다. Omnigent는 이들을 하네스라는 공통 추상으로 감싸서, 코드를 다시 짜지 않고 에이전트를 바꿔 끼우거나 섞어 쓸 수 있게 한다. --harness pi 한 줄로 같은 에이전트를 다른 백엔드에서 돌린다.

② 멀티 에이전트 오케스트레이션이 "예제로" 들어있다

레포에 딸린 Polly(코드를 직접 안 짜고 하위 에이전트에 위임하는 테크리드형 오케스트레이터)와 Debby(Claude·GPT 두 머리로 같은 질문에 답하고 토론시키는 브레인스토밍 파트너)가 "멀티 에이전트를 어떻게 설계하는지"를 그대로 보여 준다. 한 벤더가 짠 코드를 다른 벤더 에이전트에게 리뷰시키는 교차 검증 패턴이 핵심이다.

③ 어디서나 같은 세션 — 모바일 퍼스트

터미널에서 시작한 세션을 브라우저·폰에서 이어받는다. 메시지·하위 에이전트·터미널·파일이 전부 동기화된다. omnigent attach로 팀원이 내 머신에서 도는 세션에 합류해 같이 운전(co-drive)하거나, --fork로 대화를 복제해 따로 이어갈 수 있다.

3기술 스택 전체 지도

백엔드 · 프론트엔드 · 인프라를 각각 뜯어본다.

백엔드 (Python 3.12+, 약 23만 줄)

본체는 순수 파이썬이다. pyproject.toml의 의존성에서 설계 의도가 드러난다.

프론트엔드 (ap-web — React 18 + TypeScript + Vite)

ap-web/는 423개 TS 파일의 웹 UI다. 단순 채팅창이 아니라 터미널·코드 에디터·다이어그램까지 품은 풀 IDE급 SPA다.

거기에 ap-web/electron/으로 macOS 데스크탑 앱(코드사이닝·DMG 빌드 포함)을 같은 UI로 감싼다. 즉 같은 React 앱이 웹·폰·데스크탑 세 형태로 배포된다.

인프라 / 배포

deploy/ 하나에 10가지 배포 타깃이 다 들어 있다: Docker(Caddy 리버스프록시 포함), Render(원클릭), Fly.io, Railway, Kubernetes, Hugging Face Spaces, Modal·Daytona·Islo·CoreWeave 샌드박스. 루트의 render.yaml·railway.toml이 그 증거다. 의존 관리·빌드는 uv(uv.lock, uv.toml), 타입체크는 pyrefly(pyrefly.toml)를 쓴다.

4아키텍처 심화 분석

시스템 구조도 + 핵심 설계 패턴.

전체 시스템 구조

설계 패턴 1 — 하네스 어댑터(Adapter) 패턴

runtime/harnesses/와 runtime/executors/base.py가 핵심이다. 모든 하네스는 동일한 Executor 인터페이스를 구현하고, harness_aliases.py가 사용자가 쓰는 별칭(claude)을 내부 정식 이름(claude-sdk)으로 정규화한다.

# harness_aliases.py — 사용자 표기를 내부 정식 이름으로
HARNESS_ALIASES = {
    "claude": "claude-sdk",
    "native-pi": "pi-native",
    "openai-agents-sdk": "openai-agents",
}
NATIVE_HARNESSES = frozenset({
    "claude-native", "codex-native", "pi-native", ...
})

여기서 중요한 구분이 "native 하네스"다. claude-native/codex-native는 실제 CLI를 진짜 터미널 프로세스에 띄우고 화면을 미러링한다(사람이 UI에서 열어 직접 타이핑·인수인계 가능). 반면 claude-sdk는 SDK를 인-프로세스로 호출한다. 그래서 runner는 native 에이전트에겐 히스토리를 재생하지 않는 등 동작이 달라진다 — 이 미묘한 분기를 코드 주석으로 명시해 둔 점이 인상적이다.

설계 패턴 2 — 3계층 정책 엔진 (Allow / Deny / Ask)

policies/는 에이전트의 모든 행동(셸 실행·파일 쓰기·토큰 소비)을 가로채 ALLOW · DENY · ASK 셋 중 하나로 판정한다. 정책은 세 계층에서 쌓이며, 더 엄격한 세션 정책이 먼저 평가돼 단락(short-circuit)된다.

# 에이전트 YAML에 정책 선언 (builtins)
policies:
  approve_shell:
    handler: omnigent.policies.builtins.safety.ask_on_os_tools
  budget:
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00          # 하드 상한
      ask_thresholds_usd: [3.00]  # 소프트 경고

정책은 함수형(function.py)과 CEL 식(cel-expr-python) 두 방식을 지원한다. CEL을 고른 이유가 명확하다 — 튜링 불완전·부작용 없음·종료 보장이라, 신뢰할 수 없는 정책 문자열을 안전하게 평가할 수 있다.

설계 패턴 3 — 선언형 AgentSpec (YAML)

에이전트는 코드가 아니라 짧은 YAML 한 장이다(spec/의 파서·검증기). 프롬프트·실행 하네스·도구·하위 에이전트를 선언만 하면 된다. 파이썬 함수는 시그니처에서 스키마를 자동 생성한다.

name: my_agent
prompt: You are a helpful data analyst.
executor:
  harness: claude-sdk
tools:
  word_count:
    type: function
    callable: mypackage.mymodule.word_count
  researcher:            # 슈퍼바이저가 위임할 수 있는 서브에이전트
    type: agent
    prompt: Search and summarize.
    tools: { word_count: inherit }

설계 패턴 4 — 멀티 에이전트 오케스트레이션 (Polly)

예제 Polly의 YAML이 패턴의 정수다. 오케스트레이터는 코드를 직접 안 짜고(spawn: true로 자식 세션 생성), 모든 코딩을 claude_code/codex/pi 서브에이전트에 위임한 뒤, 다른 벤더의 리뷰어에게 교차 검증시킨다. 각 구현자는 자기 PR을 열고, 머지는 사람이 한다.

5디렉토리 구조 해부

어디에 무엇이 있는지 큰 지도부터.

6학습 포인트 (기술별)

이 레포에서 구체적으로 무엇을 배울 수 있나.

① 어댑터/추상화 설계

서로 다른 외부 도구(Claude·Codex·Cursor·Pi)를 하나의 인터페이스로 묶는 법. executors/base.py의 추상 메서드와 각 하네스 구현을 비교하며 "공통점을 어떻게 인터페이스로 뽑아내는가"를 배운다.

② 정책 엔진 / 권한 모델

AI 에이전트의 "행동 게이트"를 어떻게 설계하나. ALLOW/DENY/ASK 3-verdict, 다계층 평가, CEL로 안전한 식 평가 — 이건 그대로 다른 자동화 시스템(CI 봇, 운영 자동화)에 응용 가능하다.

③ 터미널 미러링 (pexpect + pyte)

CLI 프로세스를 띄우고 그 화면을 브라우저 xterm.js로 실시간 미러링하는 기술. pexpect로 프로세스 제어, pyte로 가상 터미널 화면 버퍼를 파싱한다. "원격 터미널 공유"의 실전 구현이다.

④ OS 샌드박싱

macOS seatbelt와 Linux bwrap(bubblewrap)로 에이전트 터미널을 격리하는 법. 신뢰할 수 없는 코드를 돌릴 때 파일·네트워크 접근을 제한하는 실전 보안 패턴.

⑤ FastAPI 실시간 서버 + WebSocket 스트림

세션 스트림을 WebSocket으로 다중 클라이언트에 브로드캐스트하고, 멀티유저 인증(JWT·argon2·OIDC), 호스트 레지스트리(원격 머신 등록)를 붙이는 풀스택 서버 설계.

⑥ React로 IDE급 SPA 만들기

xterm(터미널)·Monaco(에디터)·React Flow(그래프)·streamdown(스트리밍 마크다운)을 한 앱에 통합하고, 같은 코드를 웹·Electron 데스크탑으로 동시 배포하는 프론트엔드 아키텍처.

7하드웨어 / 시스템 요구사항

돌리려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

난이도별로 손을 더럽혀 보자.

9관련 기술 심화 학습 로드맵

주차별로 차근차근.

10핵심 키워드 사전

자주 나오는 용어 정리.

11참고 링크

더 깊이 파고들 자료.