Claude Code, Codex가 Unity를 직접 제어하게 만드는 CLI 툴 (hera-agent)

약 12시간·

294

안녕하세요. 유니티 개발자 NotNull92 입니다.

요즘 Claude Code나 Codex 같은 AI 에이전트를 터미널에 물려놓고 코딩하시는 분들 많으실 겁니다. 그런데 AI 에이전트를 유니티 개발에 쓰다 보면 항상 답답한 벽에 부딪힙니다. AI가 코드는 기가 막히게 짜주는데, 정작 유니티 에디터를 "추측"만 할 뿐 직접 만지지는 못한다는 점이죠.

코드가 제대로 컴파일되는지, Play 모드에서 NullReferenceException은 안 터지는지 AI는 알 길이 없습니다. 결국 개발자가 복붙하고, 에디터로 넘어가서 재생 버튼 누르고, 에러 로그 긁어서 다시 AI 터미널에 먹여주는 막노동을 해야 합니다.

'AI 에이전트가 직접 유니티 에디터에 명령을 내리고 결과를 받아볼 순 없을까?' 해서 만든 CLI 툴을 하나 공유합니다.

🛠️ hera-agent: AI를 위한 유니티 제어 도구

hera-agent는 단일 바이너리로 동작하며, HTTP를 통해 Unity Editor를 CLI 환경에서 제어할 수 있게 해주는 도구입니다.

가장 중요한 특징은 개발자가 직접 명령어를 칠 일이 거의 없다는 것입니다. 파이썬 환경 세팅 같은 복잡한 과정 없이, 터미널에서 설치 명령어 한 줄이면 끝납니다.

[개발자가 할 일] 설치하고 상태만 확인해 주면 됩니다.

PowerShell

# 설치 후 상태 확인 및 관리
hera-agent status
hera-agent update

[AI 에이전트가 할 일] 터미널 권한을 가진 Claude Code나 Codex가 아래와 같은 명령어들을 알아서 실행하고, 유니티 에디터의 상태를 확인합니다.

Bash

# AI가 스스로 플레이 모드를 실행하고 테스트
hera play start

# AI가 런타임에 C# 코드를 직접 주입하여 상태 확인
hera exec "GameObject.FindObjectsOfType<GameObject>().Select(g => g.name).ToArray()"

이 외에도 AI가 직접 유닛 테스트(Test Runner)를 돌리거나, 에디터 뷰 스크린샷을 촬영해서 시각적인 결과물을 확인하는 것도 가능합니다.

🏗️ 간단한 아키텍처

Go CLI: 터미널에서 AI의 명령을 받아 HTTP 요청으로 변환해 주는 가벼운 클라이언트 (의존성 0개)
C# Unity Connector: 유니티 에디터 내부에 띄워진 로컬 서버로, CLI의 요청을 받아 유니티 에디터 API를 실행하고 결과를 AI에게 반환