🧠 my-pi

<div align="center">

[English](./README.en.md) | **한국어**

# 🧠 my-pi

**[pi](https://github.com/mariozechner/pi-coding-agent) 기반 개인 AI 오퍼레이팅 시스템**

*11개의 전문 에이전트 · 25개 이상의 확장 기능 · 한 개발자의 주관적인 셋업*

<br/>

`🤖 11 에이전트` &nbsp; `🧩 25+ 확장 기능` &nbsp; `🎨 7 테마`

<br/>

> AI 코딩 에이전트 설정을 하나의 **엔지니어링 프로젝트**로 다룬다면?
>
> 이 레포가 그 답이다 — 매일 실사용하는 설정으로, pi를 CLI 도구에서 멀티 에이전트 오케스트레이션 플랫폼으로 확장한다. 역할별 전문 에이전트, 안전 장치, 세밀한 커스터마이징까지.

</div>

---

> [!WARNING]
> 이 레포는 계속 바뀌는 개인 실사용 셋업이라 문서와 실제 상태가 언제든 어긋날 수 있다.
> 일부 기능이나 설정은 특정 시점에 불안정하거나 깨져 있을 수 있다.


## 🏗️ 아키텍처

<p align="center">
  <img src="./tmp/architecture.ko.svg" alt="시스템 아키텍처" width="800"/>
</p>

시스템은 **네 개의 레이어**로 구성된다:

| 레이어 | 역할 |
|---|---|
| **사용자 / pi TUI** | 터미널 기반 인터랙티브 인터페이스 |
| **확장 기능** | 25개 이상의 TypeScript 플러그인 — 서브에이전트, 음성 I/O, MCP 브릿지, UI 오버레이, 안전 장치 |
| **에이전트 오케스트라** | 역할과 모델이 다른 11개의 전문 에이전트 정의 |
| **인프라** | [claude-mcp-bridge](./extensions/claude-mcp-bridge/)를 통한 MCP 도구 연동 — 기존 Claude Code MCP 설정을 그대로 재사용 (Jira, Slack, Gmail, Calendar, GA4, Figma, DB 등) |

---

## 🤖 에이전트 오케스트라

<p align="center">
  <img src="./tmp/agents.ko.svg" alt="에이전트 오케스트라" width="800"/>
</p>

현재 기준 11개의 에이전트 정의, 3개의 모델, 하나의 오케스트레이터로 구성된다:

| 에이전트 | 모델 | 역할 | 사용 시점 |
|---|---|---|---|
| 🔍 **finder** | `anthropic/claude-sonnet-4-6` | 빠른 파일·코드 탐색 | 빠른 조회, grep 스타일 탐색 |
| ⚡ **worker** | `openai-codex/gpt-5.4` | 범용 작업 실행기 | 구현, 작성, 수정 (복잡한 다중 파일) |
| 📐 **planner** | `anthropic/claude-opus-4-6` | 구현 설계자 | 복잡한 작업 분할 |
| ✨ **simplifier** | `anthropic/claude-sonnet-4-6` | 코드 단순화 전문가 | 최근 수정 코드 정리, 가독성 개선, 동작 보존 리팩터링 |
| 🧹 **code-cleaner** | `openai-codex/gpt-5.4` | 코드 정리 분석가 | 중복 제거 후보, 품질 문제 탐색 |
| 🔎 **reviewer** | `openai-codex/gpt-5.4` | 코드 리뷰 (P0–P3 심각도) | PR 리뷰, 품질 점검 |
| 🥊 **challenger** | `openai-codex/gpt-5.4` | 스트레스 테스터 | 실행 전 계획 검증 |
| ✅ **verifier** | `anthropic/claude-opus-4-6` | 3단계 근거 검증 | 주장 확인, 정확성 점검 |
| 🔐 **security-auditor** | `openai-codex/gpt-5.4` | 보안 검토자 | 취약점 중심 리뷰 |
| 🌐 **searcher** | `anthropic/claude-sonnet-4-6` | 리서치·웹 검색 | 문서 탐색, 조사 |
| 🖥️ **browser** | `openai-codex/gpt-5.4` | 브라우저 자동화·UI 테스트 | E2E 테스트, 시각 검증 |

<details>
<summary><strong>모델 선택 기준</strong></summary>

- **openai-codex/gpt-5.4** — 범용 실행·리뷰 (구현, 테스트, 리뷰, 보안 검토, 브라우저 자동화)
- **anthropic/claude-sonnet-4-6** — 빠른 탐색·리서치 (파일 검색, 웹 리서치, 코드 단순화)
- **anthropic/claude-opus-4-6** — 깊은 추론 작업 (전략 설계, 검증)

오케스트레이터(메인 에이전트)는 `anthropic/claude-opus-4-6` 기반으로 동작하여 위임 결정을 수행한다.

</details>

---

## 🧩 확장 기능

25개 이상의 커스텀 TypeScript 확장 중 대표 항목들을 도메인별로 정리했다:

### 코어 시스템

| 확장 | 설명 |
|---|---|
| **subagent/** | 멀티 에이전트 위임 엔진 — 서브 `pi` 프로세스 생성, below-editor 상태 위젯으로 실행 관리, 자동 follow-up/정리 |
| **claude-mcp-bridge/** | Claude Code의 MCP 서버 설정을 그대로 재사용 — 중복 설정 제로 |
| **cross-agent.ts** | `.claude/`, `.gemini/`, `.codex/` 디렉터리에서 에이전트 정의 로드 |
| **dynamic-agents-md.ts** | 런타임에 AGENTS.md를 동적 로드하여 편집·쓰기 범위 제한 강제 |
| **escalate-tool.ts** | 서브에이전트가 마스터에게 에스컬레이션 신호를 보내는 도구 |
| **claude-hooks-bridge.ts** | Claude Code의 훅(hook) 이벤트를 Pi 세션에 연결하는 브릿지 |
| **memory-layer/** | 세션 간 영속 메모리 시스템 |

### UI / UX

| 확장 | 설명 |
|---|---|
| **footer.ts** | 모델, git 브랜치, 컨텍스트 사용량을 보여주는 커스텀 푸터 |
| **working-text.ts** | 처리 중 경과 시간과 함께 팁 중심 스피너 텍스트 |
| **idle-screensaver.ts** | 유휴 시 터미널 스크린세이버 |
| **theme-cycler.ts** | `Ctrl+X`로 테마 실시간 순환 |
| **diff-overlay.ts** | `/diff` — 분할 화면 git diff 뷰어 오버레이 |
| **github-overlay.ts** | 터미널에서 바로 GitHub PR 확인 |
| **files.ts** | `/files` — git 트리 파일 브라우저 + 열기/편집/diff 빠른 액션 |
| **fork-panel.ts** | `/fork-panel` — 현재 세션을 새 Ghostty split panel로 포크 |
| **generative-ui/** | `visualize_read_me`, `show_widget` — 네이티브 시각화/위젯 렌더링 |
| **override-builtin-tools.ts** | 도구 출력 접기/펼치기로 세션 깔끔하게 유지 |

### 개발 도구

| 확장 | 설명 |
|---|---|
| **todo-write.ts** | 할 일 관리 — `todo_write` 도구, 영속 저장소, TUI 렌더링 |
| **auto-name.ts** | 첫 사용자 메시지로 세션 이름 자동 감지 |
| **upload-image-url.ts** | GitHub CDN으로 이미지 업로드 후 임베딩 |
| **clipboard.ts** | OSC52 이스케이프 시퀀스로 클립보드에 텍스트 복사 |
| **ask-user-question.ts** | 사전 정의 옵션을 갖춘 인터랙티브 질문 도구 |
| **delayed-action.ts** | 지연 실행 예약 |
| **until.ts** | `/until`, `until_report` — 조건 충족까지 반복 실행 |
| **usage-analytics.ts** | `/analytics` — 서브에이전트·스킬 사용 통계 오버레이 |
| **archive-to-html.ts** | to-html 스킬로 생성된 HTML 파일을 `~/Documents`에 자동 아카이브 |

### 안전 장치

| 확장 | 설명 |
|---|---|
| **command-typo-assist.ts** | 명령어 오타를 감지하고 자동 수정 제안 |

---

---

## 🏷️ 세션 이름

`/name`은 프롬프트 템플릿이 아니라 **내장 명령**이다.

```
/name <세션 이름>   # 이름 설정
/name               # 현재 이름 확인
```

---

## 🎨 테마

현재 7개 테마를 제공하며, `Ctrl+X`로 실시간 전환할 수 있다:

| 테마 | 스타일 |
|---|---|
| **nord** *(기본)* | 북극풍, 깔끔한 블루와 서리 톤 |
| **catppuccin-mocha** | 다크 초콜릿 위의 따뜻한 파스텔 |
| **darcula** | JetBrains 스타일의 진한 다크 톤 |
| **dracula** | 대비가 선명한 퍼플 계열 다크 테마 |
| **gruvbox** | 레트로 따뜻한 톤, 눈이 편한 |
| **midnight-ocean** | 깊은 바다 블루와 틸 |
| **rose-pine** | 차분하고 우아한 로즈 톤 |

---

## ⌨️ 단축키

| 키 | 동작 |
|---|---|
| `Ctrl+T` | 사고(thinking) 표시 토글 |
| `Ctrl+X` | 테마 순환 |
| `Ctrl+Q` | 테마 역순 순환 |
| `Ctrl+Shift+O` | 파일 브라우저 열기 |
| `Ctrl+Shift+F` | 최근 파일 참조를 Finder에서 표시 |
| `Ctrl+Shift+R` | 최근 파일 참조 Quick Look |


... (truncated)