kunchenguid/gh-axi

gh‑axi – 자율형 AI 에이전트를 위한 GitHub CLI 래퍼

무엇인가요

• gh‑axi는 공식 GitHub CLI (gh) 위에 구축된 Node 기반 명령줄 도구입니다.
• AI 에이전트가 GitHub과 프로그래밍 방식으로 상호작용해야 할 때 설계되었으며, 토큰 효율적인 출력(TOON 인코딩), 구조화된 오류 메시지, 다음 단계 제안을 제공합니다.
• 이 도구는 AXI (Agent eXperience Interface) 생태계의 일부로, 에이전트가 기능을 탐색하고 사용하는 방식을 표준화합니다.

에이전트에게 중요한 이유

• 에이전트는 대규모 언어 모델을 호출할 때 토큰 예산이 매우 제한적입니다. gh‑axi는 CLI 출력을 압축하고, 에이전트가 다음 동작을 결정하는 데 필요한 정보만 제공함으로써 LLM이 처리해야 하는 데이터 양을 줄입니다.
• 자유형 인간 중심 출력을 제공하는 원시 gh CLI와 달리, 결정론적이고 기계가 읽을 수 있는 응답(JSON, 간결한 상태 코드)을 제공합니다.
• 내장된 오류 처리 및 검증을 통해 에이전트는 모호한 터미널 메시지를 분석할 필요 없이 실패에 대응할 수 있습니다.

주요 기능

영역	gh‑axi로 할 수 있는 일
이슈 및 PR	목록, 보기, 생성, 편집, 댓글, 라벨/담당자/리뷰어 추가, 파일(이미지, 동영상) 첨부 – 반복 가능한 플래그로 다수 값 처리 가능.
스택	github/gh‑stack 확장 기능을 위한 완전한 비대화형 래퍼로, 스택된 PR 워크플로우(초기화, 보기, 제출, 머지, 리베이스 등)를 지원합니다.
워크플로우 및 실행	GitHub Actions 실행 목록, 보기, 트리거, 취소, 로그 다운로드 – 로그는 자르지만, 에이전트가 grep할 수 있도록 임시 파일에 전체 복사본을 저장합니다.
프로젝트(v2)	목록, 보기, 생성, 편집, 닫기, 복사, 항목 및 필드 관리 – OAuth 범위가 부족할 경우 명확한 안내 제공.
시크릿 및 변수	시크릿 설정(보안을 위해 stdin 전용), 목록/삭제, 리포지토리 전체 변수 관리.
기스트	목록, 보기, 생성(공개 또는 비공개), 편집, 이름 변경, 삭제, 클론 – 엄격한 플래그 검증 포함.
원시 API	gh‑axi api를 통해 어떤 GitHub REST 엔드포인트에도 직접 접근 가능. 사용자 정의 HTTP 메서드, 헤더, JSON 본문, 페이징, jq 필터링, 템플릿, 출력 자르기 비활성화하는 "full" 모드 지원.
리포지토리 및 검색	표준 리포지토리 명령(목록, 보기, 클론, 포크) 및 이슈, PR, 코드, 커밋에 대한 강력한 검색.
세션 훅	에이전트(Claude Code, Codex, OpenCode 등)가 세션 시작 시 현재 리포지토리 상태를 자동으로 표시하는 선택적 훅.

에이전트 친화적인 디자인 세부 사항

• 토큰 효율적인 TOON 출력 – LLM의 컨텍스트 창을 작게 유지하는 컴팩트한 표현.
• 구조화된 JSON – 기계가 읽을 수 있는 데이터가 필요한 명령(예: stack view, run view)에 사용.
• 반복 가능한 플래그(예: --add-label)는 모든 값이 하위 gh 명령에 전달되도록 보장하여 조용히 손실되는 것을 방지합니다.
• 검증 오류는 명확합니다. 누락되거나 빈 플래그 값은 무시되지 않고 명확한 오류를 발생시킵니다.
• 결정론적 종료 코드 – 래퍼는 원래 gh의 종료 코드를 그대로 전달하여 에이전트가 의존하는 의미를 유지합니다.
• 자기 업데이트 – 에이전트는 gh‑axi update를 실행하여 외부 패키지 매니저 없이 도구를 최신 상태로 유지할 수 있습니다.

설치 및 사용법

1. 에이전트 스킬 설치(권장):

   npx skills add kunchenguid/gh-axi --skill gh-axi -g
   

   이는 최신 npx -y gh-axi 대시보드를 가리키는 가벼운 "스킬"을 등록합니다.
2. 제로 세팅 – 기능이 있는 에이전트는 npx -y gh-axi만 실행하면 됩니다.
3. 글로벌 설치(수동 사용용):

   npm install -g gh-axi
   gh-axi setup hooks   # 선택적 세션 훅
   

   이후 다른 CLI와 마찬가지로 사용 가능(gh‑axi <command> …).

에이전트의 일반적인 워크플로우

1. 에이전트는 이슈를 트리에지해야 한다고 결정합니다.
2. gh‑axi issue list --label bug --assignee @me를 실행합니다.
3. 도구는 일치하는 이슈의 간결하고 토큰 부담이 적은 목록을 반환합니다.
4. 에이전트는 이슈를 선택하고 gh‑axi issue comment 42 --body-file ./reply.md를 실행합니다.
5. 댓글에 이미지가 포함된 경우, 에이전트는 --attach ./screenshot.png를 추가하고 하위 gh 바이너리 경유로 파일을 업로드합니다.

벤치마크

• AXI 벤치마크(17개의 실제 GitHub 작업, 에이전트로 Claude‑Sonnet‑4‑6 사용)에서 gh‑axi는 100% 성공률, 평균 입력 토큰 수(약 46k), 최저 비용(약 $0.05/작업), 평균 실행 시간(약 15.7초)을 기록하여 원시 gh 및 기타 GitHub‑MCP 기반 인터페이스보다 가장 낮았습니다.

누가 사용해야 할까

• 자율형 DevOps 에이전트, AI 지원 코드 리뷰어, 또는 신뢰성 있고 저오버헤드의 GitHub 상호작용이 필요한 LLM 기반 워크플로우를 구축하는 개발자.
• 이미 AXI 생태계를 사용 중이며 GitHub 작업용 즉시 도입 스킬을 원하는 팀.

라이선스: MIT.