one-click-ai-tools

README

🚀 one-click-ai-tools (oct)

English

🎯 AI 코딩 CLI를 하나의 바이너리로 정리합니다 — 전부 업데이트, 전부 쿼터 감시, 유지보수 예약.

oct는 흩어져 있는 AI 코딩 도구 관리를 하나로 모으는 단일 Go 바이너리 CLI입니다.

• 🔄 전부 업데이트 — Claude Code, Codex, Copilot, Cursor 등 10개 CLI를 설치 매니저 자동 감지(brew/npm/공식 인스톨러)로 한 번에 업데이트
• 📊 전부 쿼터 감시 — 14개 프로바이더의 구독 쿼터를 하나의 테이블 / JSON / macOS 메뉴바로 표시
• ⏰ 유지보수 예약 — 업데이트와 세션 점검을 launchd / cron / SchTasks에 예약하고, 임계값 도달 시 OS 알림

💡 왜 oct인가

사용량 조회 도구는 업데이트를 못 하고, 업데이터는 사용량을 못 봅니다. oct는 이 둘을 한 바이너리로 묶은 것이 핵심입니다.

• 📦 단일 Go 바이너리 — Node/Python 런타임 불필요, macOS / Linux / Windows
• 🔀 하이브리드 수집 — usage API가 있는 프로바이더는 API를 직접 조회해 남은 비율과 상태를 확인하고, API가 없는 도구(Qwen 등)는 로컬 사용 기록으로 보완
• 🔑 자격증명 재사용 — 각 CLI가 이미 저장한 OAuth 토큰·API 키를 그대로 사용, 별도 로그인 없음
• 🔍 매니저 자동 감지 — 도구마다 설치된 매니저를 찾아 맞는 업데이트 명령을 실행 (회귀 테스트로 고정)

⚡ 빠른 시작

🌐 설치 (GitHub Releases)

curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | sh

스크립트는 현재 OS/CPU에 맞는 바이너리를 내려받고, 릴리스 checksum 항목이 있으면 검증한 뒤 기본적으로 ~/.local/bin/oct에 설치합니다. 터미널에서 실행하면 설치 직후 oct config가 자동으로 열리고, config가 끝나면 macOS 메뉴바 헬퍼를 자동으로 띄운 뒤 oct -h 명령 요약을 출력합니다. ~/.local/bin이 PATH에 없으면 로그인 셸 설정 파일(zsh는 ~/.zshrc, bash는 ~/.bash_profile) 끝에 # added by one-click-ai-tools installer 마커와 함께 PATH를 자동 추가하며, 다시 실행해도 중복되지 않습니다.

🔧 설치 옵션 — 특정 버전 · 경로 변경 · config/PATH/메뉴바 건너뛰기

# 특정 버전 설치
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_VERSION=v0.1.6 sh

# 베타/prerelease 설치 — 안정판 oct를 덮지 않고 oct-beta 명령으로 함께 설치되며,
# 메뉴바 헬퍼도 별도 이름(OctMenubarApp-beta)으로 분리 실행됩니다
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_VERSION=v0.1.6-beta.1 sh

# 설치 경로 변경
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_INSTALL_DIR=/usr/local/bin sh

# 설치 후 config 단계 건너뛰기
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_INSTALL_RUN_CONFIG=0 sh

# PATH 자동 등록 건너뛰기 (셸 설정 파일을 수정하지 않음)
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_INSTALL_SKIP_PATH=1 sh

# 메뉴바 자동 실행 건너뛰기
curl -fsSL https://raw.githubusercontent.com/suho-han/one-click-ai-tools/main/scripts/install.sh | OCT_INSTALL_RUN_MENUBAR=0 sh

# 이미 설치된 바이너리 제거 (재설치 전)
rm -f ~/.local/bin/oct ~/.local/bin/OctMenubarApp

🍺 설치 (Homebrew)

brew install suho-han/tap/oct

Formula는 최신 stable GitHub Release를 추적합니다. prerelease는 install.sh 채널을 이용하세요.

⏱️ 처음 5분

# 1. 사용할 도구/프로바이더 선택 (인터랙티브)
oct config

# 2. 설치된 AI CLI 전부 업데이트 — 실행 전 계획 확인 가능
oct agent-update --dry-run --explain
oct agent-update

# 3. 전체 쿼터 현황 확인
oct usage            # 사람용 테이블
oct usage --json     # 스크립트/파이프용

사용 분석 및 수집 거부

배포판은 기본적으로 사용 분석을 켭니다. 명령 이름, 실행 방식(CLI·메뉴바·비대화형), 버전·OS·기기 제품군, 성공 여부·실행 시간, 명시적으로 선택한 프로바이더와 무작위 설치 ID를 전송합니다. 설치별 재방문도 집계하므로 완전 익명이 아닌 가명 기반 분석입니다. 프롬프트, 자격증명, 계정, 명령 인자·옵션 값, 오류 내용, 사용량·비용 및 파일 경로는 전송하지 않습니다. 주기적인 메뉴바 조회와 백그라운드 점검은 제외합니다.

이후 수집을 끄려면 oct config set telemetry-enabled false를 실행하거나 메뉴바 Settings → General에서 Share usage analytics를 끄고 Save를 누르세요. DO_NOT_TRACK=1 또는 OCT_TELEMETRY_ENABLED=false로 일시적으로 끌 수도 있습니다. 수집 거부는 이미 보관된 기록이나 로컬 설치 ID를 삭제하지 않습니다. ID는 ~/.oct/telemetry/installation-id에 있으며, 파일을 삭제하면 다음 활성 실행에서 새 ID가 만들어집니다. 분석 기록은 90일간 보관합니다. IP 주소는 분석 기록에 저장하거나 위치 추정에 사용하지 않지만, 네트워크 사업자는 전송 중 발신 IP를 볼 수 있습니다.

메뉴바 Settings → About → Project → Feedback에서 Send feedback을 눌렀을 때만 작성한 텍스트와 수신 시각이 전송·저장됩니다. 설치 ID나 계정과 연결하지 않으며, 90일간 보관합니다. 사용 분석 수집 거부와 별개이고 전송 실패 시 자동 재전송하지 않습니다. 비밀번호·API 키·개인정보는 입력하지 마세요.

🗺️ 명령어 지도

단계	명령어	하는 일
⚙️ 설정	oct config	도구·프로바이더 선택, 사용량 표시 모드 등 일반 설정 (인터랙티브; 알림 설정은 다루지 않음)
🔄 업데이트	oct agent-update	설치된 AI CLI 전부 업데이트 (--dry-run --explain 사전 점검)
📊 감시	oct usage	전 프로바이더 쿼터 1회 조회 (--json, --compact, --format waybar/polybar/swiftbar, --notify)
📊 감시	oct monitor	상시 갱신 화면 (--interval, --once, 정렬·필터)
📊 감시	oct menubar	macOS 메뉴바에 상시 표시
🔔 알림	oct alert	서브커맨드 없이 실행하면 방향키/키 입력 기반 인터랙티브 알림 설정; config·프로바이더 임계값·test·snooze 지원
⏰ 예약	oct schedule	agent-update / session-refresh를 OS 스케줄러에 등록
⏰ 예약	oct session-refresh	프롬프트 없이 세션·인증 상태만 probe (--dry-run)
🩺 진단	oct doctor	shell PATH / bootstrap 진단, credentials로 프로바이더별 자격증명 소스 진단
🩺 진단	oct update	oct 자체 업데이트
🧪 개발	oct release-doctor	릴리스 전 점검 한 번에 보기

oct --help는 사용 빈도 기준으로 그룹핑해 보여줍니다 (Core / Configuration & Scheduling / Update & Maintenance).

🔄 전부 업데이트 — oct agent-update

oct agent-update                      # 전체 업데이트 실행
oct agent-update --dry-run --explain  # 실행 없이 도구별 감지 매니저와 계획만 출력

도구마다 설치 경로와 매니저를 감지합니다. 지원 매니저: brew, npm, pnpm, yarn, cargo, go-install, pip, Cursor/Antigravity 공식 인스톨러 — 상세 매트릭스는 아래 Manager Support Matrix.

📊 전부 쿼터 감시 — oct usage / oct monitor / oct menubar / oct alert

oct usage                        # 1회 조회
oct usage --compact              # C-45% X-25% 형태 요약
oct usage --json                 # JSON 출력
oct usage --notify               # 임계값 규칙에 따라 알림 발송

스크립트 작성자용: --json 출력 구조는 안정적인 계약으로 문서화돼 있습니다 — docs/usage-json-schema.md 참고.

🖥️ 상태바 연동 — waybar / polybar / swiftbar (스크립트 작성자용)

리눅스/macOS 상태바 연동용 --format 모드 (심각도에 따라 warn 85% / crit 95% 색상):

oct usage --format waybar        # waybar custom/script 모듈용 JSON (text/tooltip/class)
oct usage --format polybar       # polybar custom script용 한 줄 (%{F#...} 색상, % 이스케이프)
oct usage --format swiftbar      # SwiftBar 플러그인 프로토콜 (타이틀 + 드롭다운 메뉴)
oct usage --format waybar --from-snapshot   # 라이브 fetch 대신 마지막 oct monitor 스냅샷 사용

--from-snapshot은 ~/.oct/state/usage-latest.json(oct monitor가 매 사이클 기록)을 읽으므로, 상태바가 짧은 폴링 간격으로 재실행해도 프로바이더 전체 fan-out이 발생하지 않습니다. waybar/polybar/swiftbar와 --compact는 모두 remaining 기준으로 표시합니다.

statusline 포맷은 값 없는 프로바이더(미구성·데이터 없음 — ? 토큰)는 숨기고 실패(401 등)는 유지합니다. 숨겨진 개수는 툴팁 마지막 줄에 표시됩니다.

oct monitor --interval 10s       # 10초 갱신 상시 화면
oct monitor --once --sort-by used --desc --top 5 --compact

🔔 고급 알림 설정 — oct alert config / snooze

서브커맨드 없이 oct alert를 실행하면 방향키/키 입력 기반 인터랙티브 알림 설정이 열립니다.

oct alert

# CLI로 세부 조정
oct alert config show
oct alert config set enabled true
oct alert config set threshold_percent 85
oct alert config set quiet 2h
oct alert config set-provider-threshold 5h 90 --provider codex
oct alert test --provider codex --window 5h --value 91
oct alert snooze set --duration 2h

⏰ 유지보수 예약 — oct schedule / oct session-refresh

oct schedule enable --task agent-update --interval daily --hour 9   # 매일 9시 전체 업데이트
oct schedule enable --task session-refresh --interval 6h            # 6시간마다 세션 점검
oct schedule --task agent-update                                    # 등록 상태 확인
oct session-refresh --dry-run                                       # 토큰 소모 없이 수동 점검

🤖 지원 AI 에이전트 (업데이트 대상)

• Claude Code (@anthropic-ai/claude-code)
• Command Code (command-code, binary: commandcode / cmd)
• OpenAI Codex (@openai/codex)
• Antigravity CLI (공식 인스톨러, binary: agy)
• GitHub Copilot (@github/copilot)
• Cursor CLI (공식 agent 설치 흐름, cursor.com/install)
• OpenCode (opencode-ai)
• Kimi Code (@moonshot-ai/kimi-code, binary: kimi) — (experimental)
• Qwen Code (@qwen-code/qwen-code, binary: qwen) — (experimental)
• MiniMax (mmx-cli, binary: mmx) — (experimental)

👀 사용량 전용 프로바이더 (설치 대상 아님, opt-in)

설치/업데이트 대상 CLI는 아니지만 사용량 조회만 지원합니다. agent_order 또는 enabled_tools에 이름을 넣으면 표에 나타납니다 (예: oct config set tools zai).

• Z.ai (GLM Coding Plan) — ZAI_API_KEY / ZHIPU_API_KEY, 또는 opencode zai-coding-plan 로그인 — (experimental)
• DeepSeek — DEEPSEEK_API_KEY — (experimental)
• OpenRouter — OPENROUTER_API_KEY
• Grok (xAI SuperGrok) — grok login 자격증명 또는 GROK_OAUTH_TOKEN — (experimental)

(experimental)는 실구독 API 응답에 대한 라이브 검증이 아직 안 된 통합이라는 뜻입니다 (라이브 검증 완료: Codex, Claude, Command Code, OpenCode, Antigravity, OpenRouter).

👥 멀티 계정 (codex, kimi, qwen, grok)

계정이 여러 개면 각각의 자격증명 디렉터리를 등록해서 사용량을 함께 볼 수 있습니다.

🧭 인터랙티브 화면으로 계정 관리하기

가장 간단한 방법은 대화형 화면입니다. codex 행 아래의 "➕ Add codex account…" 항목을 고르면 브라우저 로그인이 바로 열리고, 로그인이 끝나면 계정 이메일에서 이름을 자동 만들어 등록합니다(예: hansuho36@... → codex:han***o36, 홈은 ~/.codex-hansuho36) — 입력 없이 로그인만 하면 됩니다.

계정이 등록되면 codex 행 아래에 "Manage existing accounts (N)" 행이 나타납니다. Enter로 펼치면 마스킹된 계정 이름(codex:han***o36)이 표시되고, 계정 행에서 다시 Enter를 누르면 🔄 Reconnect(토큰 재로그인)와 ❌ Disconnect(oct 설정에서만 제거; 저장된 자격증명 파일은 유지) 액션이 나타납니다.

oct config                                              # ➕ Add codex account… → 이름 입력 → 로그인
oct config account add codex work                       # CLI: 이름만 쓰면 ~/.codex-work로 자동 파생
oct config account add kimi personal ~/.kimi-code-alt   # 경로를 직접 지정할 수도 있음
oct config account list                                 # 등록 목록 확인
oct config account remove codex work                    # 등록 해제

등록하면 oct usage 표에서 해당 프로바이더 행 바로 아래에 codex:work, kimi:personal 같은 행이 생기고, 컴팩트/스테이터스라인 표기는 XW, KP처럼 별칭 첫 글자가 붙습니다. 계정 행은 기본 행이 표시될 때 함께 표시되며, oct alert config set-provider-threshold ... --provider codex:work처럼 알림 대상으로도 쓸 수 있습니다.

🍎 메뉴바 헬퍼 (macOS)

macOS 릴리즈 tarball(oct 설치 스크립트, oct update)에는 Swift menubar helper가 함께 들어 있어 oct와 같은 디렉터리(기본 ~/.local/bin)에 자동 설치됩니다. 소스에서 직접 빌드할 수도 있습니다.

oct menubar                # 메뉴바 앱 실행
oct menubar doctor         # helper 탐색/launch 상태 점검
oct menubar build-helper   # Swift helper build
oct menubar install-helper # ~/.local/bin/OctMenubarApp 로 설치

⚙️ Settings 화면 범위와 페치 타임아웃

메뉴바 앱의 Settings는 Providers(도구 선택·업데이트), Display(외형·사용량 표시), Alerts(전역 알림), Automation(세션 갱신·로그인 시 실행), About(앱 정보·버전·업데이트 확인·프로젝트 링크) 탭으로 나뉩니다. 변경한 설정은 탭을 이동해도 유지되며, 창 하단의 Save changes로 저장합니다. Terminal 명령 실행용 Tools 탭은 없으며 명령은 oct CLI에서 직접 실행할 수 있습니다. Alerts 탭은 안전한 전역 설정만 노출하고, 프로바이더별 임계값이나 snooze 제어는 노출하지 않습니다. 그런 고급 설정은 oct alert config ...와 oct alert snooze ...를 사용하세요.

설정을 처음 불러오는 동안 진행 표시가 Settings 창 가운데에 나타납니다. 불러오기가 끝나면 성공 안내가 5초 뒤 페이드아웃되며, 오류 안내는 자동으로 사라지지 않습니다.

Alerts 탭의 임계값 슬라이더는 5% 간격(5~95%)과 마지막 99%를 선택합니다. "Use the same threshold for 5h, 7d, and 1m"을 선택하면 세 기간에 동일한 Alert threshold가 적용되고, 해제하면 각 기간의 슬라이더만 표시됩니다. 체크 상태는 다음 실행에도 유지되지만, 외부 설정에서 세 값이 달라지면 자동으로 해제됩니다.

About 탭에는 실행 중인 메뉴바 앱 버전, GitHub 저장소와 후원 링크가 표시됩니다. "Automatically check for updates"는 즉시 적용되는 앱 설정으로, 켜면 5분마다 새 GitHub Release를 확인해 다운로드 페이지 링크를 보여주고 끄면 확인과 알림을 중지합니다. 업데이트를 자동 설치하지는 않습니다.

oct usage --json의 전체 페치 deadline(기본 15초)은 OCT_USAGE_FETCH_TIMEOUT 환경변수로 조정할 수 있습니다 (예: OCT_USAGE_FETCH_TIMEOUT=8s oct usage). 5~18초 범위로 클램프되어 menubar helper의 20초 프로세스 타임아웃 안에 항상 부분 결과가 도착합니다.

🧰 Manager Support Matrix

펼쳐서 보기 — 감지 기준 · 설치 명령 · built-in 사용처

Manager	감지 기준	설치 경로	built-in 사용처
brew	brew --prefix 하위 binary 또는 brew list	brew upgrade <formula>	Homebrew로 설치된 Claude/Cursor/OpenCode/Codex
npm	npm prefix -g 또는 npm list -g	npm install -g <package>	Claude/Command Code/OpenCode/Codex/Copilot 기본 fallback
pnpm	pnpm bin -g 또는 pnpm list -g	pnpm add -g <package>	provenance 기반 감지만 지원
yarn	yarn global bin 또는 yarn global list	yarn global add <package>	provenance 기반 감지만 지원
cargo	cargo: package prefix 또는 cargo bin path	cargo install <crate> --locked	explicit package override
go-install	go: package prefix 또는 go env GOPATH bin path	go install <package>@latest	explicit package override
pip	pip: package prefix 또는 python3 -m site --user-base bin path	python3 -m pip install --upgrade <package>	explicit package override
cursor-agent	tool identity (cursor-agent / cursor / agent)	curl https://cursor.com/install -fsS | bash	Cursor CLI
antigravity-installer	tool identity (agy / antigravity, legacy gemini*)	curl -fsSL https://antigravity.google/cli/install.sh | bash	Antigravity CLI

이 built-in support matrix는 internal/update/manager_test.go에서 회귀 테스트로 고정합니다.

✅ Requirements

• 사용자: macOS agent-update 지원에는 Homebrew (Linux/Windows는 CLI 기능만)
• 개발자 (소스 빌드/테스트): Go >= 1.25

🚢 Release

• 기본 배포 채널: GitHub Releases + scripts/install.sh
• 로컬 릴리스 래퍼: bash scripts/release-package.sh vX.Y.Z

📄 License

MIT © Suho Han