From 1932257f8217ea56652f3a2214208229501fc469 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Tue, 9 Dec 2025 21:47:01 +0900
Subject: [PATCH] docs(readme): add comprehensive Claude Code compatibility
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add new 'Claude Code Compatibility' section to both README.md and README.ko.md
- Document hooks integration (PreToolUse, PostToolUse, UserPromptSubmit, Stop)
- Document configuration loaders (Command, Skill, Agent, MCP loaders)
- Document data storage (Todo management, Transcript logging)
- Simplify 'Other Features' section by moving loaders to new section
- Clean up temporary planning files in local-ignore/

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
---
 README.ko.md                            |  72 +++++++++--
 README.md                               |  84 +++++++++---
 local-ignore/comment-checker-ts-plan.md | 162 ------------------------
 local-ignore/push-and-release.sh        |  12 --
 4 files changed, 128 insertions(+), 202 deletions(-)
 delete mode 100644 local-ignore/comment-checker-ts-plan.md
 delete mode 100755 local-ignore/push-and-release.sh

diff --git a/README.ko.md b/README.ko.md
index 365e6a6..7a594ca 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -15,6 +15,7 @@
       - [내장 AST-Grep Tools](#내장-ast-grep-tools)
       - [Grep](#grep)
       - [내장 MCPs](#내장-mcps)
+    - [Claude Code 호환성](#claude-code-호환성)
     - [기타 편의 기능](#기타-편의-기능)
   - [설정](#설정)
   - [작성자의 노트](#작성자의-노트)
@@ -224,17 +225,72 @@ OpenCode 는 아주 확장가능하고 아주 커스터마이저블합니다. 
 }
 ```
 
+### Claude Code 호환성
+
+Oh My OpenCode는 Claude Code 설정과 완벽하게 호환됩니다. Claude Code를 사용하셨다면, 기존 설정을 그대로 사용할 수 있습니다.
+
+#### Hooks 통합
+
+Claude Code의 `settings.json` 훅 시스템을 통해 커스텀 스크립트를 실행합니다. Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
+
+- `~/.claude/settings.json` (사용자)
+- `./.claude/settings.json` (프로젝트)
+- `./.claude/settings.local.json` (로컬, git-ignored)
+
+지원되는 훅 이벤트:
+- **PreToolUse**: 도구 실행 전에 실행. 차단하거나 도구 입력을 수정할 수 있습니다.
+- **PostToolUse**: 도구 실행 후에 실행. 경고나 컨텍스트를 추가할 수 있습니다.
+- **UserPromptSubmit**: 사용자가 프롬프트를 제출할 때 실행. 차단하거나 메시지를 주입할 수 있습니다.
+- **Stop**: 세션이 유휴 상태가 될 때 실행. 후속 프롬프트를 주입할 수 있습니다.
+
+`settings.json` 예시:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
+      }
+    ]
+  }
+}
+```
+
+#### 설정 로더
+
+**Command Loader**: 4개 디렉토리에서 마크다운 기반 슬래시 명령어를 로드합니다:
+- `~/.claude/commands/` (사용자)
+- `./.claude/commands/` (프로젝트)
+- `~/.config/opencode/command/` (opencode 전역)
+- `./.opencode/command/` (opencode 프로젝트)
+
+**Skill Loader**: `SKILL.md`가 있는 디렉토리 기반 스킬을 로드합니다:
+- `~/.claude/skills/` (사용자)
+- `./.claude/skills/` (프로젝트)
+
+**Agent Loader**: 마크다운 파일에서 커스텀 에이전트 정의를 로드합니다:
+- `~/.claude/agents/*.md` (사용자)
+- `./.claude/agents/*.md` (프로젝트)
+
+**MCP Loader**: `.mcp.json` 파일에서 MCP 서버 설정을 로드합니다:
+- `~/.claude/.mcp.json` (사용자)
+- `./.mcp.json` (프로젝트)
+- `./.claude/.mcp.json` (로컬)
+- 환경변수 확장 지원 (`${VAR}` 문법)
+
+#### 데이터 저장소
+
+**Todo 관리**: 세션 todo가 `~/.claude/todos/`에 Claude Code 호환 형식으로 저장됩니다.
+
+**Transcript**: 세션 활동이 `~/.claude/transcripts/`에 JSONL 형식으로 기록되어 재생 및 분석이 가능합니다.
+
+> **`claude-code-*` 네이밍에 대해**: `src/features/claude-code-*/` 아래의 기능들은 Claude Code의 설정 시스템에서 마이그레이션되었습니다. 이 네이밍 규칙은 어떤 기능이 Claude Code에서 유래했는지 명확히 식별합니다.
+
 ### 기타 편의 기능
 
 - **Terminal Title**: 세션 상태에 따라 터미널 타이틀을 자동 업데이트합니다 (유휴 ○, 처리중 ◐, 도구 ⚡, 에러 ✖). tmux를 지원합니다.
-- **Command Loader**: 다음 디렉토리들에서 마크다운 기반의 커스텀 명령어들을 로드합니다:
-  - User scope: `~/.claude/commands/`
-  - Project scope: `./.claude/commands/`
-  - OpenCode global: `~/.config/opencode/command/`
-  - OpenCode project: `./.opencode/command/`
-- **Skill Loader**: 다음 디렉토리들에서 디렉토리 기반의 스킬들을 실행 가능한 명령어로 로드합니다:
-  - User scope: `~/.claude/skills/`
-  - Project scope: `./.claude/skills/`
+- **Session State**: 이벤트 훅과 터미널 타이틀 업데이트에 사용되는 중앙집중식 세션 추적 모듈입니다.
 
 ## 설정
 
diff --git a/README.md b/README.md
index 8fceceb..bc50597 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ English | [한국어](README.ko.md)
       - [Built-in AST-Grep Tools](#built-in-ast-grep-tools)
       - [Grep](#grep)
       - [Built-in MCPs](#built-in-mcps)
+    - [Claude Code Compatibility](#claude-code-compatibility)
     - [Other Features](#other-features)
   - [Configuration](#configuration)
   - [Author's Note](#authors-note)
@@ -221,29 +222,72 @@ Don't need these? Disable them via `oh-my-opencode.json`:
 }
 ```
 
+### Claude Code Compatibility
+
+Oh My OpenCode provides seamless Claude Code configuration compatibility. If you've been using Claude Code, your existing setup works out of the box.
+
+#### Hooks Integration
+
+Execute custom scripts via Claude Code's `settings.json` hook system. Oh My OpenCode reads and executes hooks defined in:
+
+- `~/.claude/settings.json` (user)
+- `./.claude/settings.json` (project)
+- `./.claude/settings.local.json` (local, git-ignored)
+
+Supported hook events:
+- **PreToolUse**: Runs before tool execution. Can block or modify tool input.
+- **PostToolUse**: Runs after tool execution. Can add warnings or context.
+- **UserPromptSubmit**: Runs when user submits a prompt. Can block or inject messages.
+- **Stop**: Runs when session goes idle. Can inject follow-up prompts.
+
+Example `settings.json`:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
+      }
+    ]
+  }
+}
+```
+
+#### Configuration Loaders
+
+**Command Loader**: Loads markdown-based slash commands from 4 directories:
+- `~/.claude/commands/` (user)
+- `./.claude/commands/` (project)
+- `~/.config/opencode/command/` (opencode global)
+- `./.opencode/command/` (opencode project)
+
+**Skill Loader**: Loads directory-based skills with `SKILL.md`:
+- `~/.claude/skills/` (user)
+- `./.claude/skills/` (project)
+
+**Agent Loader**: Loads custom agent definitions from markdown files:
+- `~/.claude/agents/*.md` (user)
+- `./.claude/agents/*.md` (project)
+
+**MCP Loader**: Loads MCP server configurations from `.mcp.json` files:
+- `~/.claude/.mcp.json` (user)
+- `./.mcp.json` (project)
+- `./.claude/.mcp.json` (local)
+- Supports environment variable expansion (`${VAR}` syntax)
+
+#### Data Storage
+
+**Todo Management**: Session todos are stored in Claude Code compatible format at `~/.claude/todos/`.
+
+**Transcript**: Session activity is logged to `~/.claude/transcripts/` in JSONL format, enabling replay and analysis.
+
+> **Note on `claude-code-*` naming**: Features under `src/features/claude-code-*/` are migrated from Claude Code's configuration system. This naming convention clearly identifies which features originated from Claude Code.
+
 ### Other Features
 
 - **Terminal Title**: Auto-updates terminal title with session status (idle ○, processing ◐, tool ⚡, error ✖). Supports tmux.
-- **Command Loader** (`src/features/claude-code-command-loader/`): Loads markdown-based commands from multiple directories:
-  - User scope: `~/.claude/commands/`
-  - Project scope: `./.claude/commands/`
-  - OpenCode global: `~/.config/opencode/command/`
-  - OpenCode project: `./.opencode/command/`
-- **Skill Loader** (`src/features/claude-code-skill-loader/`): Loads directory-based skills as executable commands:
-  - User scope: `~/.claude/skills/`
-  - Project scope: `./.claude/skills/`
-- **Agent Loader** (`src/features/claude-code-agent-loader/`): Loads agent definitions from markdown files with YAML frontmatter:
-  - User scope: `~/.claude/agents/`
-  - Project scope: `./.claude/agents/`
-  - Format: `*.md` files with frontmatter (name, description, tools)
-- **Session State** (`src/features/claude-code-session-state/`): Centralized session tracking module used by event hooks and terminal title updates.
-- **MCP Loader** (`src/features/claude-code-mcp-loader/`): Loads MCP server configurations from `.mcp.json` files:
-  - User scope: `~/.claude/.mcp.json`
-  - Project scope: `./.mcp.json`
-  - Local scope: `./.claude/.mcp.json`
-  - Supports environment variable expansion (`${VAR}` syntax)
-
-> **Note on `claude-code-*` naming**: Features under `src/features/claude-code-*/` are migrated from Claude Code's configuration system. This naming convention clearly identifies which features originated from Claude Code, such as `claude-code-command-loader`, `claude-code-skill-loader`, `claude-code-agent-loader`, and `claude-code-mcp-loader`.
+- **Session State**: Centralized session tracking module used by event hooks and terminal title updates.
 
 ## Configuration
 
diff --git a/local-ignore/comment-checker-ts-plan.md b/local-ignore/comment-checker-ts-plan.md
deleted file mode 100644
index c0f648f..0000000
--- a/local-ignore/comment-checker-ts-plan.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# Comment-Checker TypeScript Port 구현 계획
-
-## 1. 아키텍처 개요
-
-### 1.1 핵심 도전 과제
-
-**OpenCode Hook의 제약사항:**
-- `tool.execute.before`: `output.args`에서 파일 경로/내용 접근 가능
-- `tool.execute.after`: `tool_input`이 **제공되지 않음** (Claude Code와의 핵심 차이점)
-- **해결책**: Before hook에서 데이터를 캡처하여 callID로 키잉된 Map에 저장, After hook에서 조회
-
-### 1.2 디렉토리 구조
-
-```
-src/hooks/comment-checker/
-├── index.ts              # Hook factory, 메인 엔트리포인트
-├── types.ts              # 모든 타입 정의
-├── constants.ts          # 언어 레지스트리, 쿼리 템플릿, 디렉티브 목록
-├── detector.ts           # CommentDetector - web-tree-sitter 기반 코멘트 감지
-├── filters/
-│   ├── index.ts          # 필터 barrel export
-│   ├── bdd.ts            # BDD 패턴 필터
-│   ├── directive.ts      # 린터/타입체커 디렉티브 필터
-│   ├── docstring.ts      # 독스트링 필터
-│   └── shebang.ts        # Shebang 필터
-├── output/
-│   ├── index.ts          # 출력 barrel export
-│   ├── formatter.ts      # FormatHookMessage
-│   └── xml-builder.ts    # BuildCommentsXML
-└── utils.ts              # 유틸리티 함수
-```
-
-### 1.3 데이터 흐름
-
-```
-[write/edit 도구 실행]
-       │
-       ▼
-┌──────────────────────┐
-│ tool.execute.before  │
-│  - 파일 경로 캡처    │
-│  - pendingCalls Map  │
-│    에 저장           │
-└──────────┬───────────┘
-           │
-           ▼
-    [도구 실제 실행]
-           │
-           ▼
-┌──────────────────────┐
-│ tool.execute.after   │
-│  - pendingCalls에서  │
-│    데이터 조회       │
-│  - 파일 읽기         │
-│  - 코멘트 감지       │
-│  - 필터 적용         │
-│  - 메시지 주입       │
-└──────────────────────┘
-```
-
----
-
-## 2. 구현 순서
-
-### Phase 1: 기반 구조
-1. `src/hooks/comment-checker/` 디렉토리 생성
-2. `types.ts` - 모든 타입 정의
-3. `constants.ts` - 언어 레지스트리, 디렉티브 패턴
-
-### Phase 2: 필터 구현
-4. `filters/bdd.ts` - BDD 패턴 필터
-5. `filters/directive.ts` - 디렉티브 필터
-6. `filters/docstring.ts` - 독스트링 필터
-7. `filters/shebang.ts` - Shebang 필터
-8. `filters/index.ts` - 필터 조합
-
-### Phase 3: 코어 로직
-9. `detector.ts` - web-tree-sitter 기반 코멘트 감지
-10. `output/xml-builder.ts` - XML 출력
-11. `output/formatter.ts` - 메시지 포매팅
-
-### Phase 4: Hook 통합
-12. `index.ts` - Hook factory 및 상태 관리
-13. `src/hooks/index.ts` 업데이트 - export 추가
-
-### Phase 5: 의존성 및 빌드
-14. `package.json` 업데이트 - web-tree-sitter 추가
-15. typecheck 및 build 검증
-
----
-
-## 3. 핵심 구현 사항
-
-### 3.1 언어 레지스트리 (38개 언어)
-
-```typescript
-const LANGUAGE_REGISTRY: Record<string, LanguageConfig> = {
-  python: { extensions: [".py"], commentQuery: "(comment) @comment", docstringQuery: "..." },
-  javascript: { extensions: [".js", ".jsx"], commentQuery: "(comment) @comment" },
-  typescript: { extensions: [".ts"], commentQuery: "(comment) @comment" },
-  tsx: { extensions: [".tsx"], commentQuery: "(comment) @comment" },
-  go: { extensions: [".go"], commentQuery: "(comment) @comment" },
-  rust: { extensions: [".rs"], commentQuery: "(line_comment) @comment (block_comment) @comment" },
-  // ... 38개 전체
-}
-```
-
-### 3.2 필터 로직
-
-**BDD 필터**: `given, when, then, arrange, act, assert`
-**Directive 필터**: `noqa, pyright:, eslint-disable, @ts-ignore` 등 30+
-**Docstring 필터**: `IsDocstring || starts with /**`
-**Shebang 필터**: `starts with #!`
-
-### 3.3 출력 형식 (Go 버전과 100% 동일)
-
-```
-COMMENT/DOCSTRING DETECTED - IMMEDIATE ACTION REQUIRED
-
-Your recent changes contain comments or docstrings, which triggered this hook.
-You need to take immediate action. You must follow the conditions below.
-(Listed in priority order - you must always act according to this priority order)
-
-CRITICAL WARNING: This hook message MUST NEVER be ignored...
-
-<comments file="/path/to/file.py">
-	<comment line-number="10">// comment text</comment>
-</comments>
-```
-
----
-
-## 4. 생성할 파일 목록
-
-1. `src/hooks/comment-checker/types.ts`
-2. `src/hooks/comment-checker/constants.ts`
-3. `src/hooks/comment-checker/filters/bdd.ts`
-4. `src/hooks/comment-checker/filters/directive.ts`
-5. `src/hooks/comment-checker/filters/docstring.ts`
-6. `src/hooks/comment-checker/filters/shebang.ts`
-7. `src/hooks/comment-checker/filters/index.ts`
-8. `src/hooks/comment-checker/output/xml-builder.ts`
-9. `src/hooks/comment-checker/output/formatter.ts`
-10. `src/hooks/comment-checker/output/index.ts`
-11. `src/hooks/comment-checker/detector.ts`
-12. `src/hooks/comment-checker/index.ts`
-
-## 5. 수정할 파일 목록
-
-1. `src/hooks/index.ts` - export 추가
-2. `package.json` - web-tree-sitter 의존성
-
----
-
-## 6. Definition of Done
-
-- [ ] write/edit 도구 실행 시 코멘트 감지 동작
-- [ ] 4개 필터 모두 정상 작동
-- [ ] 최소 5개 언어 지원 (Python, JS, TS, TSX, Go)
-- [ ] Go 버전과 동일한 출력 형식
-- [ ] typecheck 통과
-- [ ] build 성공
diff --git a/local-ignore/push-and-release.sh b/local-ignore/push-and-release.sh
deleted file mode 100755
index 170f3b5..0000000
--- a/local-ignore/push-and-release.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-set -e
-cd /Users/yeongyu/local-workspaces/oh-my-opencode
-
-echo "=== Pushing to origin ==="
-git push -f origin master
-
-echo "=== Triggering workflow ==="
-gh workflow run publish.yml --repo code-yeongyu/oh-my-opencode --ref master -f bump=patch -f version=$1
-
-echo "=== Done! ==="
-echo "Usage: ./local-ignore/push-and-release.sh 0.1.6"