AI한테 유니티 작업 시키는 CLI 도구 - hera-agent-unity 공유합니다

안녕하세요. 6년차 유니티 프로그래머이고, 모바일 MMORPG 라이브 서비스 팀에서 5년째 일하고 있습니다.

라이브 운영하면서 반복되는 에디터 작업(에셋 정리, 씬 점검, UI 세팅, 컴파일·콘솔 확인 같은 것들)을 AI 에이전트한테 넘기고 싶었는데, 마땅한 도구가 없어서 직접 만들었습니다. 어느 정도 정리돼서 공유합니다.

hera-agent-unity — 커맨드라인에서 유니티 에디터를 제어하는 도구입니다.

구조 (의도적으로 단순하게 잡았습니다)

Go 단일 바이너리 + localhost HTTP 한 방. UPM 패키지(C# 커넥터) 하나 설치하면 끝.

런타임 의존성 0개 — MCP 서버, WebSocket relay, Python 런타임, 영속 서버 다 안 씁니다.

Stateless — 모든 요청이 독립적이라 세션/재연결 로직 없음. 도메인 리로드는 파일시스템 버스로 우회.

MCP 클라이언트에 안 묶여서 Claude Code / Codex / Cursor / 그냥 셸 스크립트 어디서든 호출됩니다.

처음엔 MCP로 갈까 고민했는데, "바이너리 하나 + 패키지 하나"가 설치/디버깅/이식성 면에서 압도적으로 편해서 이 구조로 굳혔습니다.

최근 업데이트에서 추가한 것들

manage_assets — AssetDatabase 기반 find / mkdir / copy / move / delete. 모든 경로가 Assets/ 안으로 강제 containment(traversal 차단).

screenshot --isolated — 계층 경로나 InstanceID로 GameObject 하나만 격리 촬영. 콤마로 각도 여러 개 주면 contact sheet 한 장으로 뽑힘.

uGUI docs fixer — 연결된 에디터 버전(2022.3 / 6000.0 / 6000.5+)에 맞는 공식 uGUI 문서 버킷을 골라 ui_doc apply 시 결정적 교정 + diagnostics 리포트.

Ultra Hera (검증 강도 모드) — Off / Light / Ultra. AI 에이전트가 작업 루프에서 어디까지 검증할지(compile → console error → state 재조회 → test → PlayMode → screenshot) 강도를 정합니다. 라이브 운영하면서 "조용히 틀린 채로 끝나는 것"이 제일 무서워서 제일 신경 쓴 기능입니다.

UI/TMP 타입은 전부 TypeCache + 리플렉션으로 해석해서 com.unity.ugui / TMP에 컴파일타임 의존이 0입니다. 2022.3 LTS부터 Unity 6까지 동작 확인했습니다.

링크 (MIT, 무료)

Unity: https://github.com/NotNull92/hera-agent-unity

Godot: https://github.com/NotNull92/hera-agent-godot

고닷(Godot) 쓰시는 분들을 위해 같은 철학으로 hera-agent-godot도 같이 만들고 있습니다.

피드백·이슈·PR 다 환영합니다. 특히 "이 작업도 AI한테 넘기고 싶다" 싶은 워크플로우 제보가 제일 도움이 됩니다. 봐주셔서 감사합니다. 🙏