Agent Micro
Codex CLI를 키보드와 작은 플로팅 맥로패드로 조작하는 macOS 앱입니다.
이 문서는 처음 설치하는 사람도 앱을 실행하고 기본 기능을 사용할 수 있도록 작성했습니다.
제품 랜딩 페이지 · 최신 릴리스
Windows 버전은 v* 태그가 GitHub에 푸시되면 자동으로 빌드되어 최신 릴리스에 .exe 설치 파일로 첨부됩니다.
랜딩 페이지는 현재 소유자 전용 미리보기입니다. 접속 시 ChatGPT 로그인이 필요하며, 로그인한 계정이 사이트 소유자가 아니면 열리지 않습니다. 앱의 Codex 로그인과는 별개의 배포 접근 설정입니다.
문서 언어: English · 简体中文 · 日本語
기여하고 싶다면 CONTRIBUTING.md를 먼저 확인해 주세요. 현재 작업 방향은 ROADMAP.md에서 볼 수 있습니다.
Agent Micro가 하는 일
Agent Micro는 Codex CLI의 명령을 대신 입력해 주는 리모컨에 가깝습니다.
- 최대 6개의 Codex CLI 세션을 슬롯으로 관리합니다.
- Approve, Decline, Fork, Review 같은 동작을 버튼과 단축키로 실행합니다.
- 선택한 프로젝트의 개발 서버를 시작하고 종료합니다.
- 조이스틱과 Touch 레이어로 Plan, history, sidebar, 새 채팅 등을 실행합니다.
- Codex의 모델·추론 강도·작업 폴더·권한 관련 설정을 앱 안에서 관리합니다.
- 질문의 복잡도에 맞춰 작은 모델과 큰 모델을 자동으로 선택할 수 있습니다.
- 플랜 사용량, 다음 리셋까지 남은 시간, 오늘의 권장 사용량을 함께 표시합니다.
- 로컬 Git의 변경 파일·스테이징·커밋을 처리하고, 선택적으로 GitHub를 연결해 Pull·Push를 사용합니다.
- 개인 Skills/MCP 설정을 지원합니다.
Agent Micro 자체는 AI 모델을 제공하지 않습니다. 실제 작업과 답변은 연결된 Codex CLI가 처리합니다.
빠른 시작
1. 준비물
개발 버전을 실행하려면 다음이 필요합니다.
- macOS
- Node.js
- pnpm
- 터미널 앱(Terminal, iTerm2, Ghostty 등)
- Codex CLI를 사용할 수 있는 ChatGPT 로그인
배포된 .app을 사용하는 경우에는 Node.js와 pnpm이 필요하지 않습니다. 소스 코드로 실행할 때만 필요합니다.
2. 저장소 받기
터미널을 열고 저장소를 내려받습니다.
git clone https://github.com/lumpenop/agent-micro.git
cd agent-micro
이미 저장소를 받은 경우에는 cd로 프로젝트 폴더에 들어갑니다. 현재 폴더에 package.json과 src 폴더가 보여야 합니다.
3. 의존성 설치
pnpm install
pnpm 명령을 찾을 수 없다는 메시지가 나오면 먼저 pnpm을 설치합니다.
corepack enable
corepack prepare [email protected] --activate
4. 앱 실행
pnpm start
앱 창이 열리면 설치가 완료된 것입니다. 개발 중에는 터미널에 앱 로그가 표시될 수 있습니다.
5. 첫 실행: 네 단계
앱을 처음 열면 다음 순서가 표시됩니다.
- Codex 연결: ChatGPT 계정으로 로그인합니다.
- GitHub 연결(선택): 기존 GitHub 로그인을 확인하고, 필요하면 브라우저에서 연결합니다. GitHub 기능이 필요하지 않으면
건너뛰기를 선택해도 됩니다.
- 프로젝트 선택: Codex가 작업할 폴더를 선택합니다.
- Agent 시작:
시작하기를 눌러 첫 번째 Codex 세션을 엽니다.
같은 Mac에서 Codex CLI나 GitHub CLI에 이미 로그인했다면 해당 단계가 자동으로 완료될 수 있습니다. GitHub 연결을 건너뛰어도 로컬 Git과 기본 Codex 기능은 사용할 수 있으며, 나중에 Settings → Account → GitHub에서 연결할 수 있습니다. 작업 폴더와 고급 기능도 Settings에서 바꿀 수 있습니다.
이 프로젝트는 MIT 라이선스로 공개된 오픈소스 소프트웨어입니다. 체험 기간, 구매 절차, 라이선스 키는 없습니다.
도움이 되었다면 GitHub에서 ⭐ Star를 눌러주세요. 프로젝트를 계속 발전시키는 데 큰 도움이 됩니다.
macOS 권한 설정
일부 기능은 macOS 권한이 필요합니다.
손쉬운 사용 권한
CLI 창에 포커스를 맞추거나 터미널을 분할하고 전역 단축키를 사용하려면 허용해야 합니다.
- 시스템 설정을 엽니다.
- 개인정보 보호 및 보안 → 손쉬운 사용으로 이동합니다.
- Agent Micro 또는 Electron을 목록에 추가하고 켭니다.
- 앱을 완전히 종료한 뒤 다시 실행합니다.
기본 사용법
에이전트 슬롯 열기
앱의 1부터 6까지 슬롯은 각각 하나의 CLI 세션을 가리킵니다.
| 슬롯 | 동작 |
|---|
| 1 | 새 터미널 창에서 Codex 시작 |
| 2–6 | 직전 슬롯의 터미널을 분할해 새 세션 시작 |
| 이미 열린 슬롯 | 해당 터미널 패인으로 포커스 |
보통은 1번을 먼저 연 다음 2번, 3번 순서로 여는 것이 가장 안정적입니다. 1번을 열지 않고 2번을 누르면 동작하지 않습니다.
하단 버튼
| 버튼 | 기능 |
|---|
| ⚡ Fast | 현재 에이전트의 추론 강도를 minimal로 변경 |
| ✓ Approve | Codex가 요청한 작업 승인 |
| ✕ Decline | Codex가 요청한 작업 거절 |
| Fork | 현재 세션을 분기해 다음 빈 슬롯에서 실행 |
| Review | 현재 변경 사항의 코드 리뷰 요청 |
| DEV | 선택한 프로젝트의 개발 서버 시작/종료 |
Fork는 빈 슬롯이 있을 때만 사용할 수 있습니다. 6개 슬롯이 모두 사용 중이면 비활성화됩니다.
Dial과 Touch
- Dial: 돌릴 때마다
Codex → Prompts → Tools 레이어를 전환합니다.
- Touch: 탭할 때마다 같은 레이어를 한 칸씩 전환합니다.
- Joystick: 현재 레이어에 지정된 방향 동작을 실행합니다.
| 레이어 | 위 | 오른쪽 | 아래 | 왼쪽 |
|---|
| Codex | Plan | 다음 Agent | 새 채팅 | 이전 Agent |
| Prompts | review PR | debug | docs | refactor |
| Tools | 모델 변경 | Continue | 개발 서버 | 도움말 |
키캡을 우클릭하면 아이콘을 바꿀 수 있습니다. 아이콘 선택기의 + 버튼으로 개인 SVG/PNG도 추가할 수 있습니다.
Agent Manager와 격리 작업
Agent 1은 메인 조정용으로 유지합니다. Agent Manager에 작업을 입력하면 Agent 2–6 중 빈 Worker를 자동 선택하고, 해당 Agent만 사용하는 Git worktree와 브랜치를 만든 뒤 Codex CLI를 실행합니다.
- 필요하면 특정 Worker를 직접 고르거나 다른 작업을 선행 병합 조건으로 지정할 수 있습니다.
- 병합 큐가 의존성과 생성 순서를 표시하고, 선행 작업이 끝나기 전 병합을 차단합니다.
- 실행 중인 Worker 창이 사라지면 감지 후 한 번만 자동 재실행하며, 반복 실패는 사용자 확인 상태로 전환합니다.
- 동시에 만드는 작업도 프로젝트별로 직렬화해 Git 메타데이터 충돌을 막습니다.
- 둘 이상의 Agent가 같은 파일을 수정하면 병합 전에 표시하고 차단합니다.
- dirty worktree와 dirty 메인 작업공간은 병합하지 않습니다.
- 실제 Git 충돌은 메인을 변경하기 전에 검사합니다.
- worktree 폴더가 사라져도 브랜치가 남아 있으면 복구할 수 있습니다.
- 병합이 실패해도 진행 중인 merge 상태를 메인에 남기지 않습니다.
단축키
기본 수정키는 ⌘ Command이며, 앱의 키보드 아이콘 → 키 맵핑에서 변경할 수 있습니다. Mod는 현재 선택한 수정키를 뜻합니다.
| 단축키 | 동작 |
|---|
⌘⇧M | 앱 창 숨기기/보이기 |
⌘⇧Q | 앱 종료 |
Mod + 1–6 | 에이전트 슬롯 선택/실행 |
Mod + Q | Fast |
Mod + W | Approve |
Mod + E | Decline |
Mod + R | Fork |
Mod + D | Review |
Mod + F | DEV |
Mod + Tab | Touch 레이어 전환 |
Mod + ↑ ↓ ← → | 조이스틱 방향 동작 |
패드 창이나 Agent Micro가 연 CLI 터미널이 앞에 있을 때 패드 단축키가 동작합니다.
설정 메뉴
앱의 톱니바퀴 아이콘에서 다음을 설정할 수 있습니다.
- Codex 로그인 및 연결 상태
- 선택형 GitHub 로그인 및 연결 상태
- Provider와 API 설정
- 모델과 추론 강도
- 새 Agent를 답변·분석 전용 읽기 모드로 여는 Ask 모드
- 플랜 사용 퍼센트 기준 일일 목표·차단선과 리셋까지의 권장 사용량
- 질문 복잡도와 최근 실제 토큰 사용 기록에 따른 자동 모델·추론 강도 선택
- 다음 요청의 예상 토큰 범위와 일일/플랜 목표 초과 사전 경고
- 작업 폴더
- sandbox, 승인, 타임아웃 등 Codex 설정
- 에이전트별 이름·역할·모델·작업 폴더
- 자동 Continue
- MCP 서버
- 개인 Skills
- 언어와 수정키
설정은 macOS의 Electron 사용자 데이터 폴더와 ~/.codex에 저장됩니다. 일부 설정은 새로 여는 CLI 창부터 적용됩니다.
Custom provider 호환성
Responses API · Codex Agent는 OpenAI Responses API와 호환되는 provider 또는 proxy용입니다. Codex의 sandbox, 승인, Agent 세션을 그대로 유지하는 대신 /responses 프로토콜이 필요합니다.
DeepSeek 공개 API처럼 /chat/completions만 제공하는 API는 이 모드에 직접 연결할 수 없습니다. 그런 provider를 Codex Agent로 사용하려면 Responses API를 제공하는 호환 proxy가 필요합니다.
랜딩 페이지 개발
랜딩 페이지는 apps/landing에 있습니다.
개발 서버 실행:
pnpm landing:dev
정적 파일 빌드:
pnpm landing:build
다운로드 버튼에 표시할 앱 주소를 지정하려면:
AGENT_MICRO_DOWNLOAD_URL=https://example.com/Agent-Micro.dmg pnpm landing:build
빌드 결과는 apps/landing/dist에 생성되며, 이 결과물을 호스팅 배포에 사용합니다.
현재 소유자 전용 미리보기는 agent-micro.swk5373.chatgpt.site에 배포되어 있습니다. 이 주소의 ChatGPT 로그인 화면은 사이트 접근 권한을 확인하기 위한 것으로, Agent Micro 앱의 Codex 로그인과는 별개입니다.
macOS 앱 빌드
Apple Silicon용 개발 산출물을 만들려면:
pnpm dist:mac
설치용 DMG를 만들려면:
pnpm dist:dmg
로컬에서 만든 앱은 Apple Developer 인증서가 없으면 서명·공증되지 않습니다. macOS에서 처음 열 때 보안 경고가 나타날 수 있습니다.
테스트
안전한 기능 테스트는 다음 명령으로 실행합니다.
pnpm test:safe
pnpm test:controls
pnpm test:providers
pnpm test:providers:codex
pnpm test:coordinator
pnpm test:coordinator:stress
실제 터미널에 입력하거나 창을 여는 테스트는 부작용이 있으므로 별도 환경 변수 없이는 실행되지 않습니다.
문제 해결
앱 창은 열리지만 Codex가 연결되지 않음
- Codex CLI가 설치되어 있는지 확인합니다.
- 앱의
↻ 버튼으로 다시 연결합니다.
- Shift를 누른 채 제목 옆 점을 눌러 강제 로그인을 실행합니다.
- 손쉬운 사용 권한을 확인하고 앱을 다시 시작합니다.
터미널 분할이 동작하지 않음
손쉬운 사용 권한이 필요합니다. 권한을 켠 뒤 Agent Micro와 터미널 앱을 모두 종료하고 다시 실행하세요.
pnpm install 중 Electron 관련 메시지가 나옴
의존성 설치가 끝난 뒤 아래 명령을 한 번 실행해 보세요.
pnpm rebuild electron
로그 확인
앱을 터미널에서 실행하면 오류 로그를 확인할 수 있습니다.
pnpm start
프로젝트 구조
src/
main.js Electron 메인 프로세스와 IPC
preload.js 렌더러에 노출하는 안전한 API
app.mjs 화면 동작과 이벤트 처리
index.html 앱 화면
styles.css 앱 스타일
providers/ Codex/API 연결 브리지
*.mjs, *.js 설정·아이콘·도구 모듈
apps/landing/ 정적 랜딩 페이지
scripts/ 설치·테스트·빌드 보조 스크립트
LICENSE MIT 라이선스
THIRD_PARTY_NOTICES.md 포함된 오픈소스 고지
기여하기
- 저장소를 Fork합니다.
- 기능별 브랜치를 만듭니다.
- 변경 후
pnpm test:safe를 실행합니다.
- 변경 목적과 테스트 결과를 Pull Request에 적습니다.
기존 사용자 설정이나 사용자가 직접 만든 AGENTS.md 파일을 덮어쓰는 변경은 피해주세요.
라이선스
Agent Micro는 MIT License로 배포됩니다. 포함된 외부 프로젝트의 조건은 THIRD_PARTY_NOTICES.md를 확인하세요.
