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`
- 공식 마켓플레이스: skill-creator, plugin-dev, hookify, mcp-server-dev, claude-security, security-guidance, code-simplifier, 그리고 스택 LSP(typescript-lsp, jdtls-lsp, kotlin-lsp)
- 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": "both",
  "baton": { "warn": 0.5, "hard": 0.7 },
  "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` 은 `"both"`(기본) / `"codex"` / `"gemini"` / `"none"`(2차 의견 없음) 중 하나이거나 `["ocr","gemini"]` 같은 배열이다. Codex 를 쓰지 않으려면 `"gemini"` 또는 `["ocr","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 연동 (Baton 기준 일치)

Claude Code가 statusline에 넘기는 공식 `context_window.used_percentage`를 Baton이 그대로 쓰게 한다. 사용자의 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`.) 연동이 없으면 Baton은 transcript 기반 추정치로 동작한다.

같은 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. 자동 압축 임계값

Baton(50% 경고 / 70% 하드 스톱)이 Claude Code 자동 압축보다 먼저 작동해야 한다. 자동 압축은 손실 요약이라 마지막 안전망으로만 둔다.

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

현재 값을 보여주고 80으로 설정할지 묻는다. 승인하면 실행한다. `~/.claude/settings.json`의 `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`에 쓰고 변경 전 파일을 백업한다. Claude Code 내부 상한이 약 83%라 그 위 값은 자동으로 조정된다. 새 세션부터 적용된다.

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

nereus 는 MCP 서버 두 개를 제공한다 — `browser`(chrome-devtools-mcp), `context7`. 세션마다 둘 다 상주하므로 세션이 많으면 비용이 배수로 붙는다.

**끄는 방법은 사용자 설정이다.** `~/.claude/settings.json` 에 넣는다 — 플러그인 업데이트가 `.mcp.json` 을 덮어써도 살아남는다.
```json
{ "deniedMcpServers": ["plugin:nereus:browser"] }
```
- 서버 이름 형식은 `plugin:<플러그인>:<서버>` 이고 **정확히 일치**해야 한다. 커맨드·URL 은 정규식으로도 쓸 수 있다(`"npx.*chrome-devtools-mcp"`).
- `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/서버).

## 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/`의 8개 (`/intake`, `/spec`, `/build`, `/e2e`, `/review`, `/finish`, `/resume`, `/setup`). 본문은 SKILL.md를 읽으라는 지시라 스킬 수정이 그대로 반영된다.
4. **MCP**: 같은 파일의 `mcp`에 browser·context7이 `.mcp.json`과 같은 핀으로 들어 있다.
5. 한계: OpenCode에 PreCompact 개념이 없어 Baton 자동 계승이 없다. handoff는 수동으로 쓰고 `/resume`으로 잇는다. `permission.ask`는 건드리지 않는다(사용자 승인 흐름 유지). oh-my-opencode 자체 자동화와 Nereus 게이트가 겹치면 Nereus 게이트(review·finish·TDD 강제)를 주인으로 둔다.