# Agents

> 모든 AI Agent, MCP server, LSP server를 설치하거나 업그레이드. OS를 감지해 pnpm, uv, brew, nix를 플랫폼별 방식으로 실행. 'install'로 신규 머신 설정, 'upgrade'로 기존 agent 업데이트. 시스템 패키지(prerequisites 포함)는 /infra:packages 사용.

- Skill: `deuxksy/agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add deuxksy/agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deuxksy/agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: deuxksy (https://skillmd.com/u/deuxksy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deuxksy/agents

---


# Agents

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

> **범위 구분**: 이 스킬은 코딩 도구(AI 에이전트·MCP·LSP)만 담당.
> pnpm/uv/mise 등 prerequisites와 OS 시스템 패키지는 `/infra:packages` 사용.

## OS 감지

```bash
# 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) |
| NixOS | nix 패키지로 관리 (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` |
| `llm` | `llm` |

#### 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 |

---

## Install (새 머신 셋업)

### 1. Prerequisites 확인

pnpm, uv가 있어야 함. 없으면 `/infra:packages`의 Prerequisites 섹션으로 먼저 설치.

### 2. 에이전트 설치

#### pnpm (전 OS)

```bash
# @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)

```bash
# 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
uv tool install llm@latest

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

#### LSP Servers

```bash
# 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
```

#### Brew Cask AI Agents (macOS 분기)

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

```bash
# 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
```

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

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

```bash
# 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 - llm
llm --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`는 `--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가 있어야 함. 없으면 `/infra:packages`의 Prerequisites 섹션으로 먼저 설치.

### 2. 사전 버전 수집

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

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

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

### 3. 사용자 확인

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

### 4. 업그레이드 실행

#### pnpm (전 OS)

```bash
# 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)

```bash
# 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 llm

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

#### LSP Servers

```bash
# 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.*'
```

#### Brew Cask AI Agents (macOS 분기)

```bash
# 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)과 비교하여 리포트 출력.

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

```text
| 패키지 | 관리 | 이전 | 이후 | 상태 |
| :--- | :--- | :--- | :--- | :--- |
| @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/uv/mise 설치·시스템 패키지는 `/infra:packages` 담당. 이 스킬은 실행 전 존재 여부만 확인
- **멱등성** (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)와 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로 관리. antigravity는 installer 스크립트
- **한국어 리포트**: 결과는 항상 한국어로 출력