jrswab/axe

A lightweight cli for running single-purpose AI agents. Define focused agents in TOML, trigger them from anywhere; pipes, git hooks, cron, or the terminal.

Axe – LLM 에이전트를 위한 Unix 스타일 CLI

개요 – Axe는 (Go로 작성된) 명령줄 프로그램으로, 선언적 TOML 파일에서 에이전트(소규모 단일 목적 LLM 워크플로우)를 정의하고 터미널이나 스크립트에서 실행할 수 있게 해줍니다. 각 에이전트는 LLM과 대화하고, 내장 도구(파일 읽기/쓰기, 셸 명령 실행, URL 가져오기, 웹 검색)를 호출하며, 심지어 다른 에이전트에 작업을 위임할 수 있는 작은 Unix 유틸리티와 같습니다.

중요성 – 기존의 대부분 LLM 래퍼는 거대한 컨텍스트 창을 가진 장기 실행 챗봇을 가정합니다. Axe는 이 모델을 뒤집습니다. 에이전트는 영구 메모리를 명시적으로 활성화하지 않는 한 *집중적이고 구성 가능하며 상태 비저장(stateless)*입니다. 다른 CLI와 동일하게 작동하므로 데이터를 에이전트에 파이프하거나 (git diff | axe run pr‑reviewer), cron으로 예약하거나, CI에서 트리거하거나, 표준 Unix 파이프라인으로 여러 에이전트를 연결할 수 있습니다.

핵심 개념

개념	기능
에이전트 정의	모델, 시스템 프롬프트, 스킬(마크다운 지침 파일), 선택적 도구, 하위 에이전트, 메모리 설정, 토큰 예산, 재시도 정책 등을 지정하는 TOML 파일 (`$XDG_CONFIG_HOME/axe/agents/*.toml`).
스킬	LLM에게 작업을 수행하는 방법을 알려주는 재사용 가능한 `SKILL.md` 지침 세트. 스킬은 Axe 구성 디렉토리로부터의 상대 경로 또는 절대 경로를 통해 검색됩니다.
영구 메모리	실행 시마다 LLM 컨텍스트에 자동으로 로드되는 선택적 마크다운 로그. Axe는 LLM 지원 가비지 컬렉션을 실행하여 오래된 항목을 정리할 수도 있습니다.
도구 사용	내장 샌드박스 도구 (`read_file`, `write_file`, `run_command`, `url_fetch`, `web_search` 등) 및 선택적 외부 MCP 도구. LLM이 도구 호출을 요청하면 Axe가 이를 실행하고 결과를 반환하며 대화가 계속됩니다.
하위 에이전트 위임	에이전트는 깊이 및 병렬성 제한을 두고 다른 에이전트(`call_agent`)를 호출할 수 있어 계층적 워크플로우를 가능하게 합니다.

주요 기능 (README에 설명된 대로)

멀티 공급자 지원 – Anthropic, OpenAI, Ollama (로컬), OpenCode, AWS Bedrock.
TOML 기반, 버전 제어 가능한 구성 – Git에 저장하기 용이함.
표준 입력 파이핑 – 에이전트를 다른 필터와 동일하게 취급.
드라이런 모드 – LLM을 호출하지 않고 해결된 컨텍스트를 미리 보기.
JSON 봉투 – 하위 자동화를 위한 구조화된 출력.
토큰 예산 강제 – 누적 토큰 제한에 도달하면 실행 중지 (종료 코드 4).
메모리 가비지 컬렉션 – LLM 지원을 통한 오래된 로그 정리.
재시도 로직 – 일시적인 공급자 오류에 대한 구성 가능한 지수/선형/고정 백오프.
보안 – 샌드박스 파일 도구, 웹 가져오기를 위한 호스트 허용 목록, SSRF 보호 및 강화된 Docker 이미지 (비루트 사용자, 읽기 전용 루트 FS, 기능 삭제).

설치

방법	명령
미리 빌드된 바이너리 (Linux/macOS/Windows)	GitHub Releases 페이지에서 다운로드.
Go install (Go 1.25+ 필요)	`go install github.com/jrswab/axe@latest`
소스에서 빌드	```bash
git clone https://github.com/jrswab/axe.git
cd axe
go build .

---
### 퀵스타트 워크플로우
```bash
# 구성 디렉토리 초기화 (~/.config/axe)
axe config init

# "my‑agent"라는 새 에이전트 스캐폴딩
axe agents init my-agent

# 생성된 TOML을 편집하여 모델, 스킬 등 설정
axe agents edit my-agent

# 실행 – 데이터를 파이프하거나 -p로 프롬프트 제공
git diff --cached | axe run my-agent
# 또는
axe run my-agent -p "Summarise the latest changelog"

README에는 코드 리뷰어, 커밋 메시지 생성기, 텍스트 요약기와 같이 바로 복사해서 사용할 수 있는 에이전트가 포함된 `examples/` 폴더도 함께 제공됩니다.

Docker 지원

최소한의 Dockerfile이 강화된 이미지(UID 10001, 읽기 전용 루트, 모든 기능 삭제)를 빌드합니다.
Axe 구성 디렉토리를 마운트하고 환경 변수를 통해 API 키를 전달하여 에이전트를 실행합니다.
docker buildx를 통해 다중 아키텍처 빌드(linux/amd64, linux/arm64)가 지원됩니다.
로컬 Ollama 인스턴스와 함께 Axe를 실행하기 위한 docker‑compose.yml이 제공됩니다. Ollama 서비스를 생략하여 클라우드 전용 공급자와 함께 이미지를 사용할 수도 있습니다.

일반적인 사용 사례

자동 코드 리뷰 – git diff를 code‑reviewer 에이전트로 파이프하여 파일을 읽고, 린터를 실행하고, 변경 사항을 제안합니다.
커밋 메시지 생성 – 커밋 로그를 에이전트에 제공하여 간결한 메시지를 출력합니다.
로그 분석 – 오류 로그를 log‑analyzer 에이전트로 스트리밍하여 웹에서 알려진 문제를 검색합니다.
CI/CD 게이트 – GitHub Actions 워크플로우의 단계로 에이전트를 실행하여 스타일이나 보안 검사를 강제합니다.
임시 데이터 추출 – read_file/run_command 도구를 사용하여 리포지토리에서 데이터를 가져온 다음 LLM에게 변환을 요청합니다.

다음 단계

examples/README.md – 번들된 에이전트에 대한 자세한 설명.
CLI 참조 – axe --help 또는 README의 표에서 모든 명령과 플래그 확인.
에이전트 TOML 스키마 – README의 "Agent Configuration" 섹션에 모든 선택적 필드(메모리, 예산, 재시도, MCP 서버 등)가 나열되어 있습니다.
MCP 통합 – Model Context Protocol을 지원하는 외부 도구 서버가 있는 경우 [[mcp_servers]] 아래에 선언하여 도구 세트를 확장하십시오.

결론

Axe는 LLM을 프로그래밍 가능한 명령줄 도구로 취급하기 위한 가볍고 Unix 철학에 부합하는 방법을 제공합니다. 각 에이전트를 작고 버전 제어 가능하며 구성 가능하게 유지함으로써 기존 셸 파이프라인, CI 시스템 및 Docker 워크플로우에 자연스럽게 통합되면서도 하위 에이전트 위임, 영구 메모리, 멀티 공급자 지원과 같은 고급 기능을 제공합니다.