Quick Start — 설치 30초

1 CLI 설치

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/NotNull92/hera-agent/main/install.ps1 | iex

# Go install (모든 플랫폼)
go install github.com/NotNull92/hera-agent@latest

Pro 사용자 — 자동 인스톨러

Patreon 잠금해제 후 Releases에서 받은 바이너리를 한 번 실행하면 PATH까지 자동 등록됩니다.

# Windows (PowerShell)
.\hera-agent-pro-windows-amd64.exe install

# macOS / Linux
chmod +x ./hera-agent-pro-darwin-arm64
./hera-agent-pro-darwin-arm64 install

# 셸 재시작 후
hera-agent-pro --version

2 Unity Connector 설치

Package Manager → Add package from git URL:

https://github.com/NotNull92/hera-agent.git?path=AgentConnector

Pro 사용자 — 별도 UPM URL

Pro 저장소는 비공개입니다. Patreon 인증 후 접근 가능.

https://github.com/NotNull92/hera-agent-pro.git?path=AgentConnector

3 첫 명령 실행

hera-agent status              # 연결 확인
hera-agent editor play --wait  # Play Mode 진입
hera-agent exec "return Camera.main.name;"  # C# 실행

4 Claude Code CLI에 고정 (필수)

Unity 프로젝트의 CLAUDE.md에 다음 한 줄을 추가하세요:

"For any Unity work, always use hera-agent as the first choice."

이 규칙이 없으면 AI는 훈련 데이터의 오래된 API를 추측합니다. 한 줄로 실제 Unity 에디터를 우선 호출하게 만드세요.

Features

Hera에게 정확한 정보를 주고, 결과를 직접 가져옵니다

Lite 공짜로 시작하는 AI·Editor 연결 도구

Lite

exec — 런타임 C# 실행

AI가 쓴 C# 코드를 Unity 안에서 바로 실행. 빌드 없이 결과를 바로 가져옵니다.

hera-agent exec "return Camera.main.name;"

v0.0.23non-TTY 자동 감지 → agent mode (banner 제거, JSON compact). Unity Object 반환 시 shallow {name, type, instanceID}로 reflection 폭주 차단.

Lite

editor — Play Mode 제어

Play 켜기·끄기·멈춤을 한 줄로. Hera가 직접 돌려보고 결과를 확인합니다.

hera-agent editor play --wait

Lite

console — 로그 가져오기

Unity 콘솔 로그를 종류별로 골라 출력. Hera가 에러를 직접 읽고 다음 수정으로 넘어갑니다.

hera-agent console --type error

v0.0.23기본 20줄 cap (218KB → 41.7KB, 80.8% 절감). 옛 무제한 동작은 --lines 0으로 명시 복원.

Lite

test — EditMode / PlayMode

테스트를 터미널에서 직접 돌리고 결과를 받습니다. PlayMode는 도메인 리로드 너머까지 폴링.

hera-agent test --mode PlayMode

Lite

profiler — 느린 부분만 뽑기

Profiler 계층을 GUI 클릭 없이 한 줄로. 정렬·깊이·임계값으로 핫스팟만 직접 가져옵니다.

hera-agent profiler hierarchy --depth 3 --sort self

Lite

screenshot · menu · scene · reserialize · doctor · update · uninstall

뷰 캡처, 메뉴 항목 실행(File/Quit 차단), 씬 로드/저장, 에셋 강제 재직렬화, 자가 진단, 셀프 업데이트, 완전 제거까지 한 바이너리에서.

hera-agent doctor && hera-agent update

Pro AI 코딩이 매일인 인디 개발자에게

Pro

exec --check — 실행 전 문법 확인

코드를 돌리지 않고, 문법만 먼저 확인. AI의 "실행 → 실패 → 재시도" 한 바퀴를 건너뜁니다.

hera-agent-pro exec --check "return Camera.main.name;"

Pro

introspection — 살아있는 API 보기

지금 돌고 있는 코드에서 타입·메서드·시그니처를 직접 가져옵니다. Hera가 옛날 학습 데이터가 아니라, 지금 이 프로젝트를 봅니다.

hera-agent-pro describe_type UnityEditor.EditorApplication

Pro

batch — 여러 명령 한 번에

여러 명령을 JSON 한 파일로 묶어 한 번에. CI/CD에서 여러 번 왕복할 걸 한 번으로 줄입니다.

hera-agent-pro batch --file deploy.json

Pro

pitfalls — describe_type 함정 노트

시그니처와 함께 Unity 6 함정 + Manual 링크가 함께 옵니다. Editor API · MonoBehaviour 생명주기 · uGUI(Canvas/RectTransform/EventSystem/LayoutGroup/ScrollRect/Selectable/Mask/CanvasGroup) 커버.

hera-agent-pro describe_type AssetDatabase --members methods

Pro

list_assemblies / find_method

지금 이 프로젝트에 실제로 로드된 어셈블리·메서드를 리플렉션으로 직접 검색. LLM 학습 cutoff 짐작이 아니라 라이브 상태.

hera-agent-pro find_method Refresh --namespace UnityEditor

Pro

asset-config set-csc/set-dotnet

Pro 전용 — csc/dotnet 경로를 영속화. exec에서 매번 --csc/--dotnet 안 적어도 됨. on/off·JSON·TUI는 Lite도 같음.

hera-agent-pro asset-config set-csc /usr/local/share/dotnet/.../csc.dll

Pro

자동 다중 인스턴스 발견

Unity를 여러 개 열어도 CWD → 프로젝트 경로 → 포트 → 최근 heartbeat 순으로 자동 선택. --port, --project, HERA_AGENT_* 환경변수로 명시 오버라이드.

HERA_AGENT_PROJECT=~/Projects/MyGame hera-agent-pro exec ...

How It Works

복잡한 건 숨기고, 간단한 것만 보여줍니다

Terminal

hera-agent (Go binary)

→

HTTP POST

localhost:8090+ (자동 폴백)

→

Unity Editor

Connector (C#)

Stateless · Auto-discovery · Domain-reload safe

Examples

왼쪽은 명령, 오른쪽은 Hera가 다음에 쓸 정보

// Hera가 시작 전에 프로젝트 정보를 가져옵니다
hera-agent status
Connected: true | Project: MyGame | Unity: 6000.0.25f1

// Hera가 Play를 켜고 에러를 직접 읽습니다
hera-agent editor play --wait && hera-agent console --type error

// Hera가 씬의 모든 카메라 위치를 한 줄로 가져옵니다
hera-agent exec "return Camera.allCameras.Select(c => c.transform.position).ToList();"

// 내 도구는 [HeraTool] 표시만 붙이면 자동으로 인식됩니다
hera-agent spawn --x 0 --y 5 --z 0 --prefab Enemy_Boss

// Hera가 느린 부분을 GUI 클릭 없이 한 줄로 뽑습니다
hera-agent profiler hierarchy --depth 3 --sort self

// Pro: Hera가 살아있는 코드에서 타입을 확인. LLM 짐작을 바꿉니다
hera-agent-pro describe_type UnityEditor.EditorApplication

// Pro: 실행 전 문법만 먼저 확인해서, 재시도 한 번 줄이기
hera-agent-pro exec --check "return Player.Instance.Velocity;"

// Pro: 빌드·테스트·확인을 한 번에 (CI/CD)
hera-agent-pro batch --file deploy-commands.json

Under the Hood

코드 크기, 환경 변수, 도메인 리로드 안전 메커니즘

코드 크기

	Go	C#
Lite 엔진	~2,600	~3,900
Pro 엔진	~4,300	~7,600

Lite엔 테스트·TUI·asset-config 레이어 ~2,300줄 더. 그래도 Unity와 직접 통신하는 엔진은 가볍게 유지.

환경 변수

HERA_AGENT_PORT — 자동 발견 무시
HERA_AGENT_PROJECT — 경로로 인스턴스 선택
HERA_AGENT_TIMEOUT_MS — HTTP 타임아웃 (기본 60s)
GITHUB_TOKEN — Pro 셀프 업데이트 인증

CLI 플래그로도 가능: --port, --project, --timeout.

Domain Reload 메커니즘

스크립트 리컴파일 시 HTTP 서버가 잠시 죽습니다. Hera는 ~/.hera-agent*/instances/ heartbeat 파일을 원자적 쓰기로 유지하고 CLI가 매 호출마다 재탐색.

PlayMode 테스트는 status/test-results-{port}.json으로 디스크에 결과를 흘려보내 도메인 리로드 너머까지 폴링. editor refresh --compile은 3초 유예 기간으로 조기 ready 오탐 방지. (Lite·Pro 공통)

Benchmark

AI 에이전트가 exec C# 을 50회 호출했을 때
도구 자체가 토큰을 얼마나 쓸까요?

Lite v0.0.24

Unity Editor 명령 50회 → ~1,600 토큰
응답 중간값 3 bytes
50회 세션당 $0.03 이하 Claude Sonnet 단가

Pro v0.0.36

Unity Editor 명령 50회 → ~1,700 토큰
응답 중간값 3 bytes
50회 세션당 $0.01 미만 Claude Sonnet 단가

응답의 70%가 5바이트 이하 (OK\n) — 도구 비용은 사실상 노이즈.
토큰 대부분은 에이전트가 짠 C# 코드(입력)에 있습니다.

카테고리	시나리오 수	Lite (B)	Pro (B)
Scene inspection	8	563	609
GameObject creation	10	2,095	2,115
Component manipulation	10	1,447	1,742
Asset/path queries	7	536	495
Math/expression	5	207	209
Bulk ops + cleanup	10	1,720	1,753
합계	50	6,568	6,923

Unity 6000.3.5f2 LTS · 2026-05-20 측정. 50개 시나리오는 Scene inspection / GameObject creation / Component manipulation / Asset queries / Math / Bulk ops 6 카테고리에 걸친 실 사용 패턴. 측정 절차·원본 CSV는 docs/benchmarks/ 참고.

Pricing

Lite로 충분히 시작할 수 있습니다.
Pro는 AI를 매일 쓰는 사람을 위한 것입니다.

Lite

혼자 만들 때, 시작할 때

$0/월

평생 무료 · MIT

exec — 런타임 C# 실행
editor — Play Mode 제어
scene — 씬 정보·로드·저장·목록·닫기
test — EditMode/PlayMode
console — 로그 골라보기
menu — 메뉴 아이템 실행
screenshot — 화면 캡처
reserialize — 강제 다시 저장
profiler — 성능 분석
doctor — 자가 진단
update — 셀프 업데이트
uninstall — 완전 제거
asset-config — 에셋 플러그인 on/off, JSON 출력, TUI
내 도구 ([HeraTool])
batch — 여러 명령 한 번에
introspection — 살아있는 API 보기
exec --check — 실행 전 문법 확인
asset-config set-csc/set-dotnet — 컴파일러 경로 영속화

GitHub에서 공짜로 시작

Indie

AI 코딩이 매일인 인디에게

$9/월

비공개 저장소 · 매주 업데이트

Lite의 모든 기능
compact 모드 — 호출 75회에 ~32K 토큰 (Lite와 비슷)
exec --check — 재시도 한 번 줄이기
introspection — LLM 짐작 교체
batch — 여러 번 호출이 한 번으로
asset-config set-csc/set-dotnet — csc/dotnet 경로 영속화
Unity Pitfalls 모음 — Editor API · MonoBehaviour 생명주기 · uGUI
Discord 우선 지원
Patreon에서만 보는 비공개 콘텐츠

Patreon에서 잠금해제

출시 예정

Studio

팀 전원이 같은 도구를 쓸 때

$49/월

팀 라이선스 5인 · 1:1 상담 포함

Indie의 모든 기능
팀 라이선스 (5인)
CI/CD 통합 가이드
기능 요청 우선 반영
1:1 기술 상담 (월 1회)
비공개 저장소 직접 접근

출시 예정

FAQ

Unity 6000.0 이상이면 됩니다.

아닙니다. Go로 만든 실행 파일 하나라서요. Unity 쪽은 UPM 패키지로 설치하면 끝입니다. 런타임이나 서버를 따로 띄울 필요 없습니다.

유지됩니다. 스크립트가 다시 컴파일되면 서버도 재시작되지만, Hera가 알아서 새 포트를 찾습니다. 따로 만질 게 없습니다.

Claude Code CLI를 권장합니다. 터미널에서 Claude Code를 열고 "hera-agent가 설치되어 있는지 확인하고 기능을 탐색해줘"라고 말하면, 에이전트가 hera-agent를 발견하고 Unity를 직접 제어하기 시작합니다.

Codex CLI와 Cursor는 현재 개발 중입니다. 곧 지원될 예정이에요.

Hera는 MCP에 묶여있지 않은 순수 CLI 도구라, 어떤 셸에서든 부를 수 있습니다. 직접 짠 스크립트에서도 자유롭게 사용하세요.

혼자 가끔 자동화하는 정도면 Lite로 충분합니다. 매일 AI(Cursor, Claude Code, Copilot 같은 거)에게 Unity 코드를 시키고 있다면 Pro가 빠르게 본전을 뽑습니다. exec --check가 재시도를 줄여주고, describe_type이 LLM의 짐작을 실제 코드로 바꿔주거든요.

Pro 저장소는 비공개입니다. Patreon 구독자에게만 GitHub 바이너리랑 저장소 접근이 열려요. Unity Connector는 UPM git URL로 설치합니다. 참고로 최근 15일 동안 릴리스가 20개 나갔습니다. 꾸준히 업데이트되고 있어요. 구독하는 동안은 새 기능 다 받으실 수 있습니다.

해지해도 그때까지 받은 마지막 버전은 계속 쓸 수 있습니다. 단, 그 이후 업데이트나 새 Unity Pitfalls, 새 기능, 우선 지원은 더 못 받습니다. 라이선스상 재배포·서브라이선스·경쟁 제품 개발은 금지입니다.

Claude Code CLI에서 hera-agent / hera-agent-pro를 도구로 호출했을 때를 직접 측정한 결과입니다. 컨텐츠 개발 일감 호출 75회 기준으로 Lite가 약 26K 토큰, Pro compact가 약 32K 토큰 정도 나옵니다. Claude Sonnet 4 입력 가격($3 / 1M tokens)으로 따지면 세션당 $0.08~0.10 수준이고, 매일 5세션씩 30일이면 월 $12~14쯤 됩니다. 공통 도구만 따지면 오히려 Pro compact가 Lite보다 토큰을 43% 적게 씁니다. 자세한 환경은 위 Benchmark 섹션 참고하세요.

C# 클래스에 [HeraTool]을 붙이면 자동으로 인식됩니다. Lite, Pro 모두 같은 어트리뷰트를 씁니다. Parameters 클래스로 인자를 잡고, HandleCommand 메서드 안에 로직을 쓰면 됩니다. hera-agent list로 잘 등록됐는지 확인할 수 있습니다.

AI는 Unity를 짐작합니다.
Hera는 직접 봅니다.

Problem

Python 런타임

WebSocket 릴레이

JSON-RPC 설정

Domain Reload 단절

Solution

하나의 바이너리

직접 HTTP

자동 연결

Domain Reload 안전

Features

exec — 런타임 C# 실행

editor — Play Mode 제어

console — 로그 가져오기

test — EditMode / PlayMode

profiler — 느린 부분만 뽑기

screenshot · menu · scene · reserialize · doctor · update · uninstall

exec --check — 실행 전 문법 확인

introspection — 살아있는 API 보기

batch — 여러 명령 한 번에

pitfalls — describe_type 함정 노트

list_assemblies / find_method

asset-config set-csc/set-dotnet

자동 다중 인스턴스 발견

How It Works

Terminal

HTTP POST

Unity Editor

Examples

Under the Hood

Benchmark

Pricing

FAQ

다음 한 줄이 컴파일에서 죽지 않게

AI는 Unity를 짐작합니다.Hera는 직접 봅니다.

Problem

Python 런타임

WebSocket 릴레이

JSON-RPC 설정

Domain Reload 단절

Solution

하나의 바이너리

직접 HTTP

자동 연결

Domain Reload 안전

Features

exec — 런타임 C# 실행

editor — Play Mode 제어

console — 로그 가져오기

test — EditMode / PlayMode

profiler — 느린 부분만 뽑기

screenshot · menu · scene · reserialize · doctor · update · uninstall

exec --check — 실행 전 문법 확인

introspection — 살아있는 API 보기

batch — 여러 명령 한 번에

pitfalls — describe_type 함정 노트

list_assemblies / find_method

asset-config set-csc/set-dotnet

자동 다중 인스턴스 발견

How It Works

Terminal

HTTP POST

Unity Editor

Examples

Under the Hood

Benchmark

Pricing

FAQ

다음 한 줄이 컴파일에서 죽지 않게

AI는 Unity를 짐작합니다.
Hera는 직접 봅니다.