agents

Agents

모든 AI Agent를 설치하거나 업그레이드.

OS 감지

# NixOS 감지
grep -q ^ID=nixos /etc/os-release 2>/dev/null && echo "NixOS"

# macOS 감지
[ "$(uname -s)" = "Darwin" ] && echo "macOS"

# Linux 배포판 감지
cat /etc/os-release 2>/dev/null | grep ^ID=

감지 결과	분기
macOS	brew
SteamOS	mise (Node.js/corepack/pnpm) + brew (Linuxbrew, k8sgpt)
NixOS	nix 패키지로 관리 (k8sgpt, pnpm, uv 모두)
Debian/Ubuntu	apt/binary
Fedora	dnf/binary

대상

AI Agents

pnpm

패키지	CLI 명령
oh-my-claude-sisyphus	omc, oh-my-claudecode
oh-my-codex	omx

codex는 macOS에서 brew cask(codex) 권장 — pnpm minimumReleaseAge로 최신 설치가 지연됨. 아래 Brew Cask AI Agents 섹션 참조. 타 OS는 @openai/codex pnpm 패키지.

uv

패키지	CLI 명령
holmesgpt	holmes
serena-agent	serena, serena-agent, serena-hooks
shell-gpt	sgpt

OS별

패키지	macOS	SteamOS	Debian/Ubuntu	Fedora	NixOS
k8sgpt	brew	brew (Linuxbrew)	binary download	binary download	nix (스킵)

Brew Cask AI Agents

macOS에서 codex·claude-code·antigravity-cli는 brew cask로 관리. pnpm minimumReleaseAge·native PATH 충돌·agy 자체 업데이터 충돌을 모두 회피.

패키지	CLI	설치 (macOS)	업그레이드 (macOS)
codex	codex	brew install --cask codex	brew upgrade --cask codex
claude-code	claude	brew install --cask claude-code	brew upgrade --cask claude-code
antigravity-cli	agy	brew install --cask antigravity-cli	brew upgrade --cask antigravity-cli (실패 시 agy update)

antigravity-cli: auto_updates cask라 agy 자체 업데이터가 바이너리를 덮어쓰면 brew upgrade --cask가 "already a Binary at .../agy" 에러로 실패. 이때 agy update로 갱신 (brew info가 Not installed로 인식하는 상태 불일치도 동일 원인). claude-code: native installer(~/.local/bin/claude)와 PATH 충돌. brew 우선하려면 native 바이너리 제거 → /opt/homebrew/bin/claude 사용. ~/.claude/(설정·플러그인)는 공유 유지. codex: npm 패키지이나 macOS는 brew cask가 최신을 즉시 제공 (pnpm minimumReleaseAge 우회). 타 OS: SteamOS/Linux antigravity는 curl -fsSL https://antigravity.google/cli/install.sh | bash (자체 agy update). NixOS는 nixpkgs#antigravity-cli. codex는 타 OS에서 @openai/codex pnpm. claude-code는 native installer. Gemini CLI는 2026-06-18 서비스 중단.

MCP Servers

pnpm

패키지	CLI 명령
mcp-hub	mcp-hub
@bytebase/dbhub	dbhub
kubernetes-mcp-server	kubernetes-mcp-server

uv

패키지	CLI 명령
proxmox-mcp-plus	proxmox-mcp, proxmox-mcp-plus
doris-mcp-server	doris-mcp, doris-mcp-server
postgres-mcp	postgres-mcp

LSP Servers

Serena/OMC LSP 도구(lsp_*)가 코드 심볼 분석에 사용. PATH에 있어야 자동 감지. nil은 NixOS는 nix, 타 OS는 cargo(mise rust)로 설치.

pnpm

패키지	LSP	용도
typescript-language-server	TS/JS	TypeScript/TSX
yaml-language-server	YAML	Ansible, CI, config
bash-language-server	Bash/Zsh	shell script
pyright	Python	Python
vscode-langservers-extracted	JSON/HTML/CSS	범용 번들
@ansible/ansible-language-server	Ansible	playbook

OS별

패키지	macOS/SteamOS	Debian/Ubuntu/Fedora	NixOS
lua-language-server	brew	binary download	nix
marksman	brew	binary download	nix
terraform-ls	brew	binary download	nix
nil	cargo	cargo	nix

Cloud Plugins (Claude Code Marketplace)

플러그인	용도	설치 방식
Notion	문서 관리 (회사 문서 DB)	Claude Code 플러그인
Figma	디자인 (디자인 팀 협업)	Claude Code 플러그인
oh-my-claudecode	Claude Code 멀티 에이전트 오케스트레이션	Marketplace

# oh-my-claudecode 설치
claude plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
claude plugin install oh-my-claudecode

---

Prerequisites (pnpm, uv 설치)

Node.js(lts-latest)가 설치되어 있다고 가정. pnpm, uv가 없으면 OS별로 설치.

도구	macOS	SteamOS	Linux (Debian/Ubuntu/Fedora)	NixOS
Node.js	brew / 기존 설치	mise (mise use node@lts)	기존 설치	nix 패키지
pnpm	corepack enable pnpm && pnpm setup	corepack enable pnpm && corepack prepare pnpm@latest --activate	corepack enable pnpm && pnpm setup	nix 패키지 (configuration.nix)
uv	brew install uv	mise (mise use uv@latest) 또는 기존 설치	curl -LsSf https://astral.sh/uv/install.sh | sh	nix 패키지 (configuration.nix)

# --- OS 감지 ---
OS=$(cat /etc/os-release 2>/dev/null | grep ^ID= | cut -d= -f2)
KERNEL=$(uname -s)

# --- pnpm ---

# macOS / Linux (Debian/Ubuntu/Fedora)
if [ "$KERNEL" = "Darwin" ] || [ "$OS" != "steamos" -a "$OS" != "nixos" ]; then
  if ! command -v pnpm &>/dev/null; then
    # Node.js 25+에서는 corepack이 미포함될 수 있음
    npm install -g corepack@latest 2>/dev/null
    corepack enable pnpm
    pnpm setup
  fi
fi

# SteamOS - mise로 관리되는 Node.js의 corepack 사용
# npm install -g corepack 불필요 (mise node에 이미 포함)
if [ "$OS" = "steamos" ]; then
  if ! command -v pnpm &>/dev/null; then
    corepack enable pnpm
    corepack prepare pnpm@latest --activate
  fi
fi

# NixOS - configuration.nix에 pnpm 추가 후 nixos-rebuild

# --- uv ---

# macOS
if [ "$KERNEL" = "Darwin" ]; then
  if ! command -v uv &>/dev/null; then brew install uv; fi
fi

# SteamOS - mise 또는 이미 설치된 상태
if [ "$OS" = "steamos" ]; then
  if ! command -v uv &>/dev/null; then
    # mise로 설치 권장
    mise use -g uv@latest 2>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
  fi
fi

# Linux (Debian/Ubuntu/Fedora)
# 설치 후 PATH 리프레시 필요: source ~/.local/bin/env 또는 새 쉘
if [ "$OS" != "steamos" -a "$OS" != "nixos" -a "$KERNEL" != "Darwin" ]; then
  if ! command -v uv &>/dev/null; then
    curl -LsSf https://astral.sh/uv/install.sh | sh
    export PATH="$HOME/.local/bin:$PATH"
  fi
fi

# NixOS - configuration.nix에 uv 추가 후 nixos-rebuild

---

Install (새 머신 셋업)

1. Prerequisites 설치

pnpm, uv가 없으면 위 Prerequisites 섹션에 따라 설치.

2. 에이전트 설치

pnpm (전 OS)

# @latest 지정 필수: 미지정 시 설치 시점 버전이 lockfile에 고정되어 최신으로 갱신 안 됨
# AI Agents — macOS는 codex를 brew cask로 설치 (아래 Brew Cask AI Agents). pnpm은 타 OS만.
pnpm add -g oh-my-claude-sisyphus@latest oh-my-codex@latest
# codex (macOS 제외 — macOS는 brew cask)
[ "$(uname -s)" != "Darwin" ] && pnpm add -g @openai/codex@latest

# MCP Servers
pnpm add -g mcp-hub@latest @bytebase/dbhub@latest kubernetes-mcp-server@latest

uv (전 OS)

# AI Agents
# @latest 지정 필수: 미지정 시 설치 시점 버전이 pin되어 upgrade 불가
# holmesgpt는 azure-mgmt-sql pre-release 의존성으로 --prerelease=allow 필요
uv tool install holmesgpt@latest --prerelease=allow
uv tool install serena-agent@latest
# shell-gpt 1.5.x는 click을 의존성으로 명시하지 않아 ModuleNotFoundError 발생 → --with click 필수
uv tool install shell-gpt@latest --with click

# MCP Servers
uv tool install proxmox-mcp-plus@latest
uv tool install doris-mcp-server@latest
uv tool install postgres-mcp@latest

LSP Servers

# pnpm (전 OS) - @latest 지정 필수
pnpm add -g typescript-language-server@latest yaml-language-server@latest bash-language-server@latest pyright@latest vscode-langservers-extracted@latest @ansible/ansible-language-server@latest

# macOS / SteamOS (Linuxbrew)
brew install lua-language-server marksman terraform-ls

# Debian/Ubuntu/Fedora - 각 프로젝트 GitHub release binary

# nil (macOS/SteamOS/Linux) - cargo (mise rust, 소스 빌드)
cargo install --git https://github.com/oxalica/nil nil

# NixOS - configuration.nix (environment.system.packages) 또는 nix profile
nix profile install nixpkgs#lua-language-server nixpkgs#marksman nixpkgs#terraform-ls nixpkgs#nil

k8sgpt (OS별)

# macOS - homebrew/core
brew install k8sgpt

# SteamOS - Linuxbrew
brew install k8sgpt

# Debian/Ubuntu/Fedora - GitHub binary
ARCH=$(uname -m | sed 's/x86_64/x86_64/' | sed 's/aarch64/arm64/')
TMPDIR=$(mktemp -d)
curl -fsSL "https://github.com/k8sgpt-ai/k8sgpt/releases/latest/download/k8sgpt_Linux_${ARCH}.tar.gz" -o "${TMPDIR}/k8sgpt.tar.gz" \
  && tar xzf "${TMPDIR}/k8sgpt.tar.gz" -C "${TMPDIR}" k8sgpt \
  && sudo install -m 0755 "${TMPDIR}/k8sgpt" /usr/local/bin/k8sgpt \
  && rm -rf "${TMPDIR}"

# NixOS - 스킵 (nixpkgs로 관리)

Brew Cask AI Agents (macOS 분기)

macOS 감지(uname -s = Darwin) 시 codex·claude-code·antigravity-cli를 brew cask로 설치. macOS는 brew 기반.

# macOS - brew cask로 codex / claude-code / antigravity-cli 동시 설치
if [ "$(uname -s)" = "Darwin" ]; then
  brew install --cask codex claude-code antigravity-cli
  # claude-code: native installer(~/.local/bin/claude) 잔류 시 PATH 충돌 → 제거 후 brew 우선
  # rm ~/.local/bin/claude  # 사용자 승인 후 제거
fi

# SteamOS/Linux - antigravity installer (자체 agy update)
if [ "$(uname -s)" != "Darwin" ] && ! command -v agy &>/dev/null; then
  curl -fsSL https://antigravity.google/cli/install.sh | bash
fi

# NixOS - nix 패키지 (nixpkgs#antigravity-cli)
nix profile install nixpkgs#antigravity-cli

Claude Code Plugins (Marketplace)

# oh-my-claudecode
claude plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
claude plugin install oh-my-claudecode

3. 설치 검증 (버전 출력)

설치 직후 각 CLI로 직접 버전 확인하여 결과 리포트 출력. 실패한 패키지는 FAIL 표시하고 계속 진행.

# pnpm - AI Agents
codex --version
omc --version
omx --version

# Brew Cask AI Agents (macOS)
agy --version
claude --version
# pnpm - MCP Servers
mcp-hub --version
kubernetes-mcp-server --version

# uv - AI Agents
holmes version
serena --version

# uv - MCP Servers (--version 미지원)
uv tool list | grep -E "proxmox-mcp-plus|doris-mcp-server|postgres-mcp"

# pnpm - MCP Servers (--version 미지원)
pnpm list -g --depth=0 | grep -E "dbhub"

# uv - shell-gpt (click 의존성 정상 로드 확인)
sgpt --version

# OS별
k8sgpt version

# pnpm - LSP Servers
typescript-language-server --version
yaml-language-server --version
bash-language-server --version
pyright --version
ansible-language-server --version

# pnpm - LSP (--version 미지원)
pnpm list -g --depth=0 | grep vscode-langservers-extracted

# brew - LSP Servers
brew list --versions lua-language-server marksman terraform-ls

# nil (cargo/nix)
nil --version

패키지	관리	상태	버전
@openai/codex	pnpm	OK	0.137.0
agy (Antigravity)	standalone	OK	1.0.13

참고:

• holmes, k8sgpt는 --version 미지원으로 하위 명령 방식 사용.
• sgpt는 --version 지원 (ShellGPT x.x.x). click 의존성 누락 시 ImportError 발생하므로 반드시 sgpt --version으로 실행 검증.
• dbhub, proxmox-mcp-plus, doris-mcp-server, postgres-mcp는 --version 미지원으로 pnpm list / uv tool list로 확인.
• vscode-langservers-extracted는 --version 미지원으로 pnpm list로 확인. brew LSP(lua-language-server, marksman, terraform-ls)는 brew list --versions로 확인.
• nil은 NixOS는 nix, 타 OS는 cargo(cargo install --git)로 설치·갱신.

---

Upgrade (기존 머신 업데이트)

1. Prerequisites 확인

pnpm, uv가 없으면 위 Prerequisites 섹션에 따라 설치.

2. 사전 버전 수집

업그레이드 전 각 CLI로 직접 버전 확인하여 테이블로 출력.

# pnpm - AI Agents
codex --version
omc --version
omx --version

# Brew Cask AI Agents (macOS)
agy --version
claude --version
# pnpm - MCP Servers
mcp-hub --version
kubernetes-mcp-server --version

# uv - AI Agents
holmes version
serena --version

# uv - MCP Servers (--version 미지원)
uv tool list | grep -E "proxmox-mcp-plus|doris-mcp-server|postgres-mcp"

# pnpm - MCP Servers (--version 미지원)
pnpm list -g --depth=0 | grep -E "dbhub"

# uv - shell-gpt (click 의존성 정상 로드 확인)
sgpt --version

# OS별
k8sgpt version

# pnpm - LSP Servers
typescript-language-server --version
yaml-language-server --version
bash-language-server --version
pyright --version
ansible-language-server --version

# pnpm - LSP (--version 미지원)
pnpm list -g --depth=0 | grep vscode-langservers-extracted

# brew - LSP Servers
brew list --versions lua-language-server marksman terraform-ls

# nil (cargo/nix)
nil --version

패키지	관리	현재 버전
@openai/codex	pnpm	0.137.0
...	...	...

3. 사용자 확인

수집한 버전 테이블을 보여주고 진행 확인.

4. 업그레이드 실행

pnpm (전 OS)

# AI Agents — macOS는 codex를 brew cask로 업그레이드 (아래 Brew Cask). pnpm은 타 OS만.
pnpm update -g --latest oh-my-claude-sisyphus oh-my-codex
# codex (macOS 제외 — minimumReleaseAge 주의)
[ "$(uname -s)" != "Darwin" ] && pnpm update -g --latest @openai/codex

# MCP Servers
pnpm update -g --latest mcp-hub @bytebase/dbhub kubernetes-mcp-server

uv (전 OS)

# AI Agents
# holmesgpt는 azure-mgmt-sql pre-release 의존성으로 --prerelease=allow 필요
# install 시 @latest로 설치했다면 upgrade 정상 작동 (pin 해제 상태)
uv tool upgrade holmesgpt --prerelease=allow
uv tool upgrade serena-agent
uv tool upgrade shell-gpt

# MCP Servers
uv tool upgrade proxmox-mcp-plus
uv tool upgrade doris-mcp-server
uv tool upgrade postgres-mcp

LSP Servers

# pnpm (전 OS)
pnpm update -g --latest typescript-language-server yaml-language-server bash-language-server pyright vscode-langservers-extracted @ansible/ansible-language-server

# macOS / SteamOS (Linuxbrew)
brew upgrade lua-language-server marksman terraform-ls

# nil (macOS/SteamOS/Linux) - cargo 재설치로 갱신
cargo install --force --git https://github.com/oxalica/nil nil

# NixOS - nix profile upgrade (configuration.nix 관리 시 flake update + nixos-rebuild)
nix profile upgrade '.*lua-language-server.*' '.*marksman.*' '.*terraform-ls.*' '.*nil.*'

k8sgpt (OS별)

# macOS / SteamOS
brew upgrade k8sgpt

# Debian/Ubuntu/Fedora - GitHub binary 교체
ARCH=$(uname -m | sed 's/x86_64/x86_64/' | sed 's/aarch64/arm64/')
TMPDIR=$(mktemp -d)
curl -fsSL "https://github.com/k8sgpt-ai/k8sgpt/releases/latest/download/k8sgpt_Linux_${ARCH}.tar.gz" -o "${TMPDIR}/k8sgpt.tar.gz" \
  && tar xzf "${TMPDIR}/k8sgpt.tar.gz" -C "${TMPDIR}" k8sgpt \
  && sudo install -m 0755 "${TMPDIR}/k8sgpt" /usr/local/bin/k8sgpt \
  && rm -rf "${TMPDIR}"

# NixOS - 스킵 (nixos-rebuild로 관리)

Brew Cask AI Agents (macOS 분기)

# macOS - brew cask로 codex / claude-code / antigravity-cli 업그레이드
if [ "$(uname -s)" = "Darwin" ]; then
  brew upgrade --cask codex claude-code antigravity-cli
  # antigravity-cli: auto_updates cask라 agy 자체 업데이터 충돌 시 "already a Binary" 에러 → agy update로 폴백
fi

# SteamOS/Linux - 자체 update 서브커맨드
agy update

# NixOS - nix profile upgrade (configuration.nix 관리 시 flake update + nixos-rebuild)
nix profile upgrade '.*antigravity-cli.*'

5. 업그레이드 검증 + 결과 리포트

업그레이드 직후 각 CLI로 직접 버전 확인. 사전 버전(step 2)과 비교하여 리포트 출력.

# Install 섹션 3번과 동일한 CLI 버전 확인 스크립트

| 패키지 | 관리 | 이전 | 이후 | 상태 |
| :--- | :--- | :--- | :--- | :--- |
| @openai/codex | pnpm | 0.137.0 | 0.138.0 | OK |
| agy (Antigravity) | standalone | 1.0.11 | 1.0.13 | OK |
| @bytebase/dbhub | pnpm | 0.21.2 | — | FAIL |

변경 없으면 "모든 패키지가 최신 버전입니다" 출력.

---

Key Rules

• Prerequisites 자동 설치: pnpm(corepack + setup), uv가 없으면 OS에 맞게 설치
• 멱등성 (install): 이미 설치된 패키지는 스킵
• dry-run 먼저 (upgrade): 버전 수집 → 사용자 확인 → 실행
• 에러 중단하지 않음: 실패한 패키지는 리포트에 명시하고 계속 진행
• Brew Cask 우선 (macOS): codex·claude-code·antigravity-cli는 brew cask로 관리. brew formula/cask에 존재하면 pnpm/uv/native보다 우선 (brew search로 확인)
• pnpm minimumReleaseAge 주의: pnpm global은 supply chain 보호로 publish 후 약 24시간 동안 최신 버전 설치 차단 (ERR_PNPM_NO_MATURE_MATCHING_VERSION). (x.xx.x is available)가 떠도 강제 설치 불가 → macOS는 brew cask로 우회
• mise/pnpm PATH 충돌 주의: mise node global bin이 pnpm global bin보다 PATH에서 선행하면 stale 구버전이 실행됨. 업그레이드 후 반드시 which <cli> + --version 교차 검증. mise node global 중복 패키지는 npm uninstall -g로 제거
• Claude Code: macOS는 brew cask claude-code로 관리 (native installer 대체). ~/.claude/ 설정은 공유. 타 OS는 native installer 유지
• NixOS 특례: 모든 패키지 매니저(pnpm, uv, k8sgpt)와 LSP가 nix로 관리됨. nil은 NixOS 외 cargo(mise rust)로 설치
• Antigravity CLI 특례: macOS는 homebrew-cask (auto_updates) — brew upgrade --cask 실패 시 agy update로 폴백. SteamOS/Linux는 installer 스크립트 (자체 agy update), NixOS는 nixpkgs antigravity-cli 패키지
• SteamOS 특례: Node.js/corepack은 mise로 관리 → npm install -g corepack 불필요, corepack prepare pnpm@latest --activate로 활성화. uv도 mise 권장. k8sgpt는 Linuxbrew
• 한국어 리포트: 결과는 항상 한국어로 출력