Setup

---
name: setup
description: "Detect and install external tools, guide companion plugins, generate config files. 트리거: /nereus:setup [--check]."
---

# Nereus setup

## 1. 감지

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/detect.mjs"
```

출력된 표를 사용자에게 그대로 보여준다.

MCP 상주 비용도 함께 본다 — 세션마다 서버가 뜨는데 그 비용이 평소 아무 데도 안 보인다.
```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/mcp-doctor.mjs"
```
계열별 RSS·개수, 유령 프로세스(부모가 죽어 init 에 재부모된 것), `~/.npm/_npx` 캐시 크기, 설정 문제(버전 미고정·텔레메트리 on)를 보여준다.

다른 하네스 플러그인과의 충돌도 함께 본다 — 설치는 성공했는데 서로 가리는 경우가 여기서 드러난다.
```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/doctor/scripts/doctor.mjs"
```
`--check` 인자만 있으면 여기까지 하고 끝낸다.

## 2. 설치

- 미설치 **필수** 도구를 하나씩 나열하고 설치 여부를 묻는다. 한 번에 전부 승인받아도 된다.
- 승인된 명령만 실행한다. 표의 명령이 `winget`/`brew`/`npm`/`uv`이면 그대로 실행하고, URL 안내형이면 사용자에게 링크를 보여준다.
- 파이프 설치 스크립트(`curl ... | sh`, `irm ... | iex`)는 실행 전에 원문 URL을 한 번 더 보여주고 승인받는다.
- 선택 도구는 목록만 보여주고 묻지 않는다. 사용자가 원하면 설치한다.
- `ui-ux-pro-max`(디자인 방향 생성기)는 표의 설치 명령 그대로 **데이터 엔진으로만** 넣는다. `npx ui-ux-pro-max-cli init` 은 쓰지 않는다 — 스킬 7개가 전역에 설치되고 그 중 `design` 스킬이 `nereus:design` 과 트리거가 겹친다.
- 설치 후 `detect.mjs`를 다시 실행해 결과를 확인한다. 새 터미널이 필요한 도구(codegraph 등)는 그렇게 안내한다.
- **Windows/Linux 에서 Gemini 웹세션을 쓸 경우** 쿠키 확장을 안내한다(감지 불가 — 브라우저 안에 있다).
  Chrome 127+ App-Bound Encryption 때문에 `chrome_cookies.py` 자동 추출이 macOS 전용이기 때문이다.
  둘 중 하나만 설치하면 된다:
  - [Get cookies.txt LOCALLY](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc) — 원클릭으로 `cookies.txt` 다운로드
  - [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) — Export 를 클립보드에 JSON 으로 복사

  설치 후 `gemini.google.com` 로그인 탭에서 Export 하고
  `node "${CLAUDE_PLUGIN_ROOT}/skills/image/scripts/cookies-import.mjs" <파일|->` 로 넘긴다.
  재추출이 번거로우면 `GEMINI_API_KEY`(api 백엔드)를 권한다 — 쿠키 회전 문제가 원리적으로 없다.

## 3. 동반 플러그인 안내

아래는 Nereus가 포함하지 않고 각자 마켓플레이스에서 설치하는 것들이다. 명령만 보여주고 실행은 사용자가 한다.

- claude-mem: `/plugin marketplace add thedotmack/claude-mem` → `/plugin install claude-mem`
- ouroboros: `/plugin marketplace add Q00/ouroboros` → `/plugin install ouroboros@ouroboros`
- codex: `/plugin install codex@openai-codex`
- impeccable: `npx impeccable install` 후 `/impeccable init`
- Emil Kowalski 스킬(모션·디자인 엔지니어링): `npx skills@latest add emilkowalski/skills` — `review-animations` 등은 에이전트가 스스로 못 부르게 설정돼 있어 사람이 `/review-animations` 로 부른다. 자동 검사는 nereus `motion-check.mjs` 가 한다
- 공식 마켓플레이스: skill-creator, plugin-dev, hookify, mcp-server-dev, claude-security, security-guidance, code-simplifier, 그리고 스택 LSP(typescript-lsp, jdtls-lsp, kotlin-lsp)
- security-audit(저장소 전체 보안 감사, Cloudflare·MIT): `npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit` — 여러 시간짜리 6단계 감사용. 대상 코드를 실행하는 검증은 OS 샌드박스가 있어야 해서 Windows 에서는 대부분 needs_validation 으로 남는다. 변경분 리뷰는 nereus security 에이전트가 같은 판정 규칙으로 한다
- credstore: `/plugin install credstore@nereus` (CredStore npm 게시 후 동작)

### 확장이 선언한 동반 플러그인

위 목록은 코어가 아는 것이고, **설치된 확장이 자기 것을 따로 선언한다.**
코어는 게임·모바일 같은 도메인을 모르므로 여기서 데이터로만 받는다.

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/companions.mjs"
```

- 현재 프로젝트의 스택과 **관련 있는 것만** 나온다. 관련 없으면 권하지 않는다 —
  안 쓸 플러그인의 스킬이 상시 로딩되면 토큰 예산만 깎인다.
- 상태에 따라 다음 명령이 달라진다: 미설치면 마켓 추가 + 설치, **설치돼 있으면 업데이트**,
  꺼져 있으면 enable. 설치만 안내하고 업데이트를 안 하면 낡은 채로 남는다.
- 명령은 선언에서 유도된다. 확장이 명령 문자열을 직접 적지 않는다.
- 실행은 여기서도 **사용자 승인 뒤**다. 업데이트는 재시작해야 적용된다.

### 하네스 밖 스킬 위임

마케팅 소재(광고 영상·프로모·모션그래픽)처럼 **전용 스킬이 이미 있는 일**은 만들지 않고 위임한다.
설치돼 있으면 라우터가 자동으로 지목하고, 없으면 지목하지 않는다 —
없는 스킬을 부르라고 하면 죽은 지시가 되고, 라우터를 한 번 헛돌게 하면 그 뒤로 통째로 무시된다.

```bash
node "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/lib/delegates.mjs"
```

이것들은 마켓플레이스 플러그인이 아니라 **스킬 디렉터리**(`~/.claude/skills/<이름>`)에 놓는 종류다.
그래서 설치 명령을 만들어낼 수 없다. **있는 척하지 않고 놓일 위치만 알린다.**

## 4. 설정 파일

사용자 전역 설정이 없으면 만든다. 위치는 macOS `~/.config/nereus/config.json`, Windows `%APPDATA%\nereus\config.json`.

```json
{
  "secondOpinion": "egm",
  "tdd": { "enforce": "block", "allowRefactor": true, "exclude": ["**/migrations/**", "**/*.config.*", "**/*.d.ts", "**/generated/**", "**/*.g.dart", "**/*.freezed.dart"] },
  "pdf": { "engine": "typst", "font": "Noto Sans KR" },
  "image": { "backend": "auto" },
  "commitQuality": { "block": ["secret", "env_file"], "warn": ["debug_log"], "exclude": [] }
}
```

각 키의 의미를 한 줄씩 설명하고 바꿀 것이 있는지 묻는다. `secondOpinion` 은 `"egm"`(기본 — OCR + 대화 맥락 없는 서브에이전트 리뷰) / `"codex"`(EGM 에 Codex 추가) / `"none"`(OCR 만) 중 하나이거나 `["ocr","egm"]` 같은 배열이다. 이전 값 `"both"`·`"gemini"` 와 배열의 `gemini`·`agy` 는 `egm` 으로 읽힌다. Gemini 는 무료 이미지 생성에만 쓴다.

도구 호출 차단 규칙은 별도 파일이다. 기본 규칙(`--no-verify`, 루트 재귀 삭제, force push, 작업 폐기 git 명령, 시크릿 파일 편집)은 플러그인에 내장되어 있고, 사용자 규칙은 같은 디렉터리의 `rules.json`, 프로젝트 규칙은 `.nereus/rules.json`에 둔다. 형식은 `[{ "id", "tools": ["Bash"], "pattern": "<regex>", "message": "<되돌릴 문구>", "enabled": true }]`. 커밋 검사를 통째로 끄려면 `{"id": "commit-quality", "enabled": false}` 를 넣는다. 같은 id를 다시 쓰면 기본 규칙을 덮어쓰거나 `"enabled": false`로 끌 수 있다. 잘못된 regex는 무시된다(fail-open). 프로젝트별로 다르게 하려면 `.nereus/config.json`에 같은 형식으로 둔다.

## 5. statusline 연동 (HUD 컨텍스트 %)

Claude Code가 statusline에 넘기는 공식 `context_window.used_percentage`를 세션 파일로 남겨 HUD(`hud.mjs`)가 statusline 과 같은 숫자를 보여주게 한다. 사용자가 원할 때만. 사용자의 statusline 스크립트(`~/.claude/settings.json`의 `statusLine.command`)에 아래 한 줄을 추가한다. 없으면 이 줄만 실행하는 스크립트를 만들어 등록한다.

```bash
printf '%s' "$input" | node "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/ctx-sink.mjs" >/dev/null 2>&1 &
```
(`$input`은 statusline이 stdin으로 받은 JSON을 담은 변수명에 맞춘다. Windows PowerShell은 `$input | node ... ctx-sink.mjs`.) 연동이 없으면 HUD는 컨텍스트 %를 비워 둔다.

같은 statusline에 Nereus 상태 한 줄(`⚓ 3/7 · 미검증 · 54%`)을 붙이려면 아래도 추가한다. 사용자가 원할 때만.

```bash
sid=$(printf '%s' "$input" | jq -r '.session_id // empty')
node "${CLAUDE_PLUGIN_ROOT}/skills/hud/scripts/hud.mjs" --session "$sid"
```

## 6. 자동 압축 임계값

자동 압축 50% 를 기본으로 설정한다. Baton(handoff 경고·하드 스톱)은 2026-10-23 에 없어졌으므로 Claude Code 자동 압축이 유일한 컨텍스트 관리다. 압축 직전 PreCompact 훅이 요약에 다섯 섹션(원문 요청·최종 목표·완료한 작업·남은 작업·MUST NOT)을 넣으라고 지시해 손실을 줄인다.

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/autocompact.mjs"            # 현재 값
node "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/autocompact.mjs" --set 50   # 권장값
```

현재 값이 50이 아니면 50으로 설정한다(사용자가 다른 값을 원하면 그 값). `~/.claude/settings.json`의 `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`에 쓰고 변경 전 파일을 백업한다. Claude Code 내부 상한이 약 83%라 그 위 값은 자동으로 조정된다. 새 세션부터 적용된다.

## 7. MCP 서버 개별로 끄기

nereus 는 MCP 서버 하나를 제공한다 — `context7`. 브라우저는 MCP 가 아니라 `agent-browser` CLI 다(쓸 때만 데몬이 뜨고 1시간 유휴면 닫힌다). 예전 browser 서버(chrome-devtools-mcp)는 세션마다 npx 3단 프로세스로 상주해 세션당 RAM 1~2GB 를 썼다(2026-09-21 실측) — 2026-11-12 에 뺐다.

**끄는 방법은 사용자 설정이다.** `~/.claude/settings.json` 에 넣는다 — 플러그인 업데이트가 `.mcp.json` 을 덮어써도 살아남는다.
```json
{ "deniedMcpServers": ["plugin:nereus:context7"] }
```
- 서버 이름 형식은 `plugin:<플러그인>:<서버>` 이고 **정확히 일치**해야 한다. 커맨드·URL 은 정규식으로도 쓸 수 있다(`"https://mcp\\.context7\\.com/.*"`).
- `enabledPlugins` 로 끄면 nereus 하네스 전체를 잃는다. `disabledMcpjsonServers` 는 프로젝트 `.mcp.json` 전용이라 플러그인 서버에는 듣지 않는다.

**끄면 잃는 것**

| 서버 | 잃는 것 |
|---|---|
| `plugin:nereus:browser` | 스크린샷·Lighthouse·콘솔 로그 → **nereus:design 의 렌더 라운드**, qa 의 브라우저 검증, seo 감사가 막힌다 |
| `plugin:nereus:context7` | 라이브러리 버전별 문서 조회. common 규칙 5번(기억으로 API 쓰지 않기)의 근거가 사라진다 |

`.mcp.json` 쪽에서 이미 해둔 것: 버전 고정(`@latest` 금지 — 세션마다 레지스트리 조회 + `~/.npm/_npx` 무한 증식), `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1`(텔레메트리 watchdog 자식 프로세스 제거, 실측 51MB/서버).

### 선택 MCP — OpenSEO (키워드 실측)

nereus:seo 키워드 단계에 검색량·KD·SERP 실측을 붙인다. 없어도 seo 는 돈다(키워드 맵이 `실측 없음`으로 나온다). 기본으로 묶지 않는 이유: DataForSEO 유료 키가 있어야 데이터가 오고, 앱 위주 작업에는 필요 없을 때가 많다. 목록만 보여주고 사용자가 원할 때 연결한다.

- 정체: `every-app/open-seo` (MIT). Semrush·Ahrefs 대체, 데이터는 DataForSEO 종량제.
- 호스팅판: `claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp` → 첫 호출 때 OpenSEO 로그인. 요청당 DataForSEO 원가에 28% 가 붙는다.
- 자체 호스팅: Docker 나 Cloudflare 로 띄우고 같은 명령에 자기 주소의 `/mcp` 를 넣는다. DataForSEO 키는 그 서버에 넣는다.
- **서버 이름은 반드시 `openseo`.** seo 에이전트의 tools 가 `mcp__openseo__*` 이름으로 고정돼 있어서 다른 이름이나 claude.ai 디렉터리 연결로 붙이면 에이전트가 도구를 못 본다.

## 8. 마무리

무엇을 설치했고 무엇이 남았는지 표로 요약한다. 남은 필수 도구가 있으면 어떤 워크플로 단계가 영향을 받는지 알려준다 (예: `ooo` 없음 → intake 인터뷰 불가, `ocr` 없음 → review는 2차 의견만).

## 9. Codex에서 쓰기 (하네스 공용 어댑터)

저장소 루트의 `.codex/hooks.json`이 같은 Node 스크립트를 Codex 이벤트에 연결한다 (입력 차이는 `hooks/scripts/lib/harness.mjs`가 흡수). Codex 세션에서 쓰는 순서:

1. `codex` 실행 후 `/hooks`에서 Nereus 훅을 검토·신뢰한다. 프로젝트 훅은 trust 전에는 건너뛰어진다.
2. 버전 주의: Codex 빌드에 따라 PreToolUse deny가 `apply_patch`에 안 먹을 수 있다(상류 이슈). 그 경우 TDD 강제(block)는 PostToolUse 경고 + finish 게이트가 대신 막는다 — `tdd.enforce`를 `"warn"`으로 두고 gate 통과를 완료 조건으로 삼는다.
3. 스킬·MCP는 Codex 설정을 따로 잡는다 (`~/.codex/config.toml`의 skills·mcp_servers). 훅 매핑만으로 스킬이 따라오지 않는다.

## 10. OpenCode에서 쓰기 (oh-my-opencode 기준)

저장소 루트의 `.opencode/`가 전부다. 재시작 후 적용된다(실행 중 세션은 옛 설정을 쓴다).

1. **훅**: `.opencode/hooks.json`(Claude 스키마)이 oh-my-opencode 내장 브릿지나 opencode-hooks류 플러그인을 통해 실행된다. **자사 브릿지 플러그인은 두지 않는다** — 중복 실행되면 pre-tool-guard 차단 메시지가 겹치고 tdd 히스토리가 두 번 기록된다.
2. **스킬**: `.opencode/opencode.json`의 `skills.paths`가 `plugins/nereus/skills`를 가리킨다. `opencode debug skill`로 목록을 확인한다. 스킬 이름이 전역(`intake`, `build`…)이라 기존 스킬과 충돌하면 프로젝트 설정이 이긴다.
3. **명령**: `.opencode/commands/`의 명령 (`/intake`, `/spec`, `/build`, `/e2e`, `/review`, `/finish`, `/setup` 과 opsx 명령들). 본문은 SKILL.md를 읽으라는 지시라 스킬 수정이 그대로 반영된다.
4. **MCP**: 같은 파일의 `mcp`에 browser·context7이 `.mcp.json`과 같은 핀으로 들어 있다.
5. 한계: OpenCode에 PreCompact 개념이 없어 압축 요약 지시(다섯 섹션)가 적용되지 않는다. `permission.ask`는 건드리지 않는다(사용자 승인 흐름 유지). oh-my-opencode 자체 자동화와 Nereus 게이트가 겹치면 Nereus 게이트(review·finish·TDD 강제)를 주인으로 둔다.