Skip to content

Commit 16a27cd

Browse files
JeremyDev87JeremyDev87
committed
docs(tui): add auto-launch troubleshooting section and Korean guide (#520)
1 parent a312e8f commit 16a27cd

2 files changed

Lines changed: 266 additions & 0 deletions

File tree

‎docs/ko/tui-troubleshooting.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# TUI 에이전트 모니터 문제 해결 가이드
2+
3+
이 가이드는 codingbuddy MCP 서버에서 TUI 에이전트 모니터를 실행할 때 발생하는 일반적인 문제를 해결하는 데 도움을 줍니다.
4+
5+
## 자동 실행 문제
6+
7+
### TUI 창이 열렸다가 즉시 닫힘
8+
9+
**증상:** Claude Code에 codingbuddy MCP가 설정된 상태로 시작하면 터미널 창이 잠깐 나타났다가 사라집니다.
10+
11+
**원인:** `TuiAutoLauncher`가 PATH에서 `codingbuddy` 바이너리를 찾을 수 없습니다.
12+
13+
**진단:**
14+
15+
```bash
16+
# codingbuddy가 PATH에 있는지 확인
17+
which codingbuddy
18+
19+
# 인스턴스 레지스트리 확인
20+
cat ~/.codingbuddy/instances.json
21+
22+
# MCP 서버가 실행 중인지 확인
23+
ps aux | grep codingbuddy
24+
25+
# 디버그 출력으로 TUI 수동 실행
26+
npx codingbuddy tui
27+
```
28+
29+
**해결 방법:**
30+
31+
- **최신 버전으로 업데이트**: 자동 실행기가 바이너리 경로를 자동으로 해결합니다 (v4.2.0에서 수정됨).
32+
- **전역 설치**: `npm install -g codingbuddy`
33+
- **수동 실행**: `npx codingbuddy tui`
34+
- **자동 실행 비활성화**: `~/.claude/settings.json`의 env 섹션에서 `CODINGBUDDY_AUTO_TUI` 제거.
35+
36+
### "No running codingbuddy MCP server found" 오류
37+
38+
**증상:** `codingbuddy tui` 또는 `npx codingbuddy tui` 실행 시 이 오류가 표시됩니다.
39+
40+
**원인:** `~/.codingbuddy/instances.json`에 등록된 MCP 서버 인스턴스가 없습니다.
41+
42+
**진단:**
43+
44+
```bash
45+
cat ~/.codingbuddy/instances.json
46+
ps aux | grep codingbuddy
47+
```
48+
49+
**해결 방법:**
50+
51+
- AI 도구(Claude Code, Cursor 등)가 codingbuddy MCP가 설정된 상태로 실행 중인지 확인합니다.
52+
- `.mcp.json`에 codingbuddy 항목이 있는지 확인합니다.
53+
- AI 도구를 재시작하여 MCP 서버 시작을 트리거합니다.
54+
55+
### "Failed to connect to any MCP server instance" 오류
56+
57+
**증상:** TUI는 인스턴스를 찾지만 연결할 수 없습니다.
58+
59+
**원인:** MCP 서버가 종료되었거나 소켓 파일이 오래된 상태입니다.
60+
61+
**해결 방법:**
62+
63+
- AI 도구를 재시작합니다.
64+
- 오래된 항목 수동 정리: `~/.codingbuddy/instances.json` 삭제 후 재시작.
65+
- 소켓 파일 존재 확인: `ls -la /tmp/codingbuddy-*.sock` (macOS: `$TMPDIR` 확인).
66+
67+
### TUI가 렌더링되지만 에이전트 활동이 없음
68+
69+
**증상:** TUI 대시보드가 표시되지만 모든 에이전트가 유휴/0 상태입니다.
70+
71+
**원인:** TUI는 IPC를 통해 연결되어 있지만 MCP 서버가 아직 도구 호출을 받지 못했습니다.
72+
73+
**해결 방법:** 아직 AI 도구 호출이 없는 경우 정상입니다. AI 도구와 상호작용하여 MCP 도구 호출을 트리거하면 TUI가 실시간으로 업데이트됩니다.
74+
75+
### "Failed to load TUI components" 오류
76+
77+
**증상:** TUI 번들을 찾을 수 없다는 오류 메시지가 표시됩니다.
78+
79+
**원인:** TUI ESM 번들(`tui-bundle.mjs`)이 빌드되지 않았습니다.
80+
81+
**해결 방법:**
82+
83+
- npx 사용자: 최신 배포 버전을 사용하고 있는지 확인합니다.
84+
- 로컬 개발: `apps/mcp-server/`에서 `yarn build && yarn build:tui` 실행.
85+
86+
### 자동 실행 환경 변수 참조
87+
88+
| 변수 | 목적 | 기본값 |
89+
|------|------|--------|
90+
| `CODINGBUDDY_AUTO_TUI` | 새 터미널 창에서 TUI 자동 실행 활성화 | 미설정 (비활성) |
91+
| `CODINGBUDDY_PROJECT_ROOT` | 인스턴스 레지스트리의 프로젝트 루트 | `process.cwd()` |
92+
| `MCP_DEBUG` | stderr로 디버그 로깅 활성화 | 미설정 (비활성) |
93+
94+
**`.mcp.json`에서 디버그 로깅 활성화:**
95+
96+
```json
97+
{
98+
"codingbuddy": {
99+
"command": "npx",
100+
"args": ["codingbuddy", "mcp", "--tui"],
101+
"env": {
102+
"MCP_DEBUG": "1"
103+
}
104+
}
105+
}
106+
```
107+
108+
## 아이콘이 박스 또는 물음표로 표시됨
109+
110+
### 원인
111+
112+
터미널에 Nerd Font가 설정되지 않았지만 TUI가 Nerd Font 아이콘을 렌더링하려고 합니다.
113+
114+
### 해결 방법
115+
116+
**1단계: Nerd Font 설치**
117+
118+
```bash
119+
# macOS (Homebrew)
120+
brew install --cask font-jetbrains-mono-nerd-font
121+
```
122+
123+
**2단계: 터미널에서 Nerd Font 설정**
124+
125+
- **iTerm2**: 환경설정 → 프로필 → 텍스트 → 폰트
126+
- **Terminal.app**: 환경설정 → 프로필 → 폰트
127+
128+
**3단계: TUI에서 Nerd Font 활성화**
129+
130+
```bash
131+
TERM_NERD_FONT=true yarn workspace codingbuddy start:dev -- --tui
132+
```
133+
134+
## 색상이 올바르게 표시되지 않음
135+
136+
**색상 없음:** `NO_COLOR` 환경 변수가 설정된 경우 → `unset NO_COLOR`
137+
138+
**16가지 기본 색상만 표시:** `COLORTERM=truecolor yarn workspace codingbuddy start:dev -- --tui`
139+
140+
## TUI가 렌더링되지 않음
141+
142+
**`--tui` 플래그 누락:**
143+
144+
```bash
145+
# 잘못된 방법 - TUI 비활성
146+
yarn workspace codingbuddy start:dev
147+
148+
# 올바른 방법 - TUI 활성
149+
yarn workspace codingbuddy start:dev -- --tui
150+
```
151+
152+
**stderr가 TTY가 아닌 경우:** stderr가 파이프되거나 리디렉션된 경우 TUI가 비활성화됩니다. stderr를 터미널에 연결된 상태로 유지하세요.
153+
154+
## 디버그 로깅
155+
156+
```bash
157+
MCP_DEBUG=1 yarn workspace codingbuddy start:dev -- --tui 2>&1
158+
```
159+
160+
## 관련 문서
161+
162+
- [TUI 사용자 가이드](../tui-guide.md) - TUI 실행 및 설정 방법
163+
- [TUI 아키텍처](../tui-architecture.md) - 내부 컴포넌트 구조 및 이벤트 흐름

‎docs/tui-troubleshooting.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,109 @@ wait
503503

504504
Expected: Debug log shows `Graceful shutdown: unmounting TUI...`, then clean exit.
505505

506+
## Auto-Launch Issues
507+
508+
### TUI Window Opens and Immediately Closes
509+
510+
**Symptom:** After starting Claude Code with codingbuddy MCP configured, a terminal window briefly appears and disappears.
511+
512+
**Cause:** `TuiAutoLauncher` cannot find the `codingbuddy` binary in PATH.
513+
514+
**Diagnosis:**
515+
516+
```bash
517+
# Check if codingbuddy is in PATH
518+
which codingbuddy
519+
520+
# Check instance registry
521+
cat ~/.codingbuddy/instances.json
522+
523+
# Check if MCP server is running
524+
ps aux | grep codingbuddy
525+
526+
# Run TUI manually with debug output
527+
npx codingbuddy tui
528+
```
529+
530+
**Solutions:**
531+
532+
- **Update to latest version**: The auto-launcher now resolves the binary path automatically (fixed in v4.2.0).
533+
- **Install globally**: `npm install -g codingbuddy`
534+
- **Run manually**: `npx codingbuddy tui`
535+
- **Disable auto-launch**: Remove `CODINGBUDDY_AUTO_TUI` from `~/.claude/settings.json` env section.
536+
537+
### "No running codingbuddy MCP server found"
538+
539+
**Symptom:** Running `codingbuddy tui` or `npx codingbuddy tui` shows this error.
540+
541+
**Cause:** No MCP server instance is registered in `~/.codingbuddy/instances.json`.
542+
543+
**Diagnosis:**
544+
545+
```bash
546+
cat ~/.codingbuddy/instances.json
547+
ps aux | grep codingbuddy
548+
```
549+
550+
**Solutions:**
551+
552+
- Ensure your AI tool (Claude Code, Cursor, etc.) is running with codingbuddy MCP configured.
553+
- Verify `.mcp.json` has the codingbuddy entry.
554+
- Restart the AI tool to trigger MCP server startup.
555+
556+
### "Failed to connect to any MCP server instance"
557+
558+
**Symptom:** TUI finds instances but cannot connect.
559+
560+
**Cause:** The MCP server may have shut down, or the socket file is stale.
561+
562+
**Solutions:**
563+
564+
- Restart the AI tool.
565+
- Manually clean stale entries: remove `~/.codingbuddy/instances.json` and restart.
566+
- Check socket file existence: `ls -la /tmp/codingbuddy-*.sock` (macOS: check `$TMPDIR`).
567+
568+
### TUI Renders but Shows No Agent Activity
569+
570+
**Symptom:** TUI dashboard is visible but all agents show idle/zero.
571+
572+
**Cause:** The TUI connects via IPC but the MCP server hasn't received any tool calls yet.
573+
574+
**Solution:** This is normal when no AI tool calls have been made yet. Interact with your AI tool to trigger MCP tool calls — the TUI will update in real-time.
575+
576+
### "Failed to load TUI components"
577+
578+
**Symptom:** Error message about TUI bundle not being found.
579+
580+
**Cause:** The TUI ESM bundle (`tui-bundle.mjs`) is not built.
581+
582+
**Solutions:**
583+
584+
- For npx users: ensure you're using the latest published version.
585+
- For local development: run `yarn build && yarn build:tui` in `apps/mcp-server/`.
586+
587+
### Auto-Launch Environment Variable Reference
588+
589+
| Variable | Purpose | Default |
590+
|----------|---------|---------|
591+
| `CODINGBUDDY_AUTO_TUI` | Enable auto-launch of TUI in new terminal window | Not set (disabled) |
592+
| `CODINGBUDDY_PROJECT_ROOT` | Project root for instance registry | `process.cwd()` |
593+
| `MCP_DEBUG` | Enable debug logging to stderr | Not set (disabled) |
594+
595+
**Enable debug logging** in `.mcp.json`:
596+
597+
```json
598+
{
599+
"codingbuddy": {
600+
"command": "npx",
601+
"args": ["codingbuddy", "mcp", "--tui"],
602+
"env": {
603+
"MCP_DEBUG": "1"
604+
}
605+
}
606+
}
607+
```
608+
506609
## Related Documentation
507610

508611
- [TUI User Guide](./tui-guide.md) - How to run and configure the TUI

0 commit comments

Comments
 (0)