# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Nexus Agent** — a full-stack AI agent platform with a chat interface and dynamic tool registration system. Packaged as a single CLI tool (`nexus-agent`).

- **Frontend**: Next.js 16 (App Router) + React 19 + TypeScript, using pnpm
- **Backend**: Python 3.13 + FastAPI, using uv
- **LLM**: Google Gemini 2.0 Flash via LiteLLM abstraction layer
- **Package**: `nexus-agent` (CLI via click, installable via `pipx` or `uv tool`)

## Development Commands

### Quick Start
```bash
uv run nexus-agent init             # ~/.nexus-agent/ 초기 설정 생성
uv run nexus-agent start --dev      # 개발 모드 (CORS 허용, 리로드)
```

### Frontend (`frontend/`)
```bash
cd frontend && pnpm dev          # Dev server on :3000
cd frontend && pnpm build        # Production build (static export → out/)
cd frontend && pnpm lint         # ESLint
```

### Backend (직접 실행)
```bash
uv run uvicorn nexus_agent.server:app --reload --host 0.0.0.0 --port 8000
```

### Frontend Build & 정적 파일 반영
`nexus-agent start`는 `nexus_agent/static/`의 빌드된 정적 파일을 서빙하므로, 프론트엔드 소스 수정 후 반드시 빌드해야 반영됨:
```bash
cd frontend && NEXT_TURBOPACK_EXPERIMENTAL_USE_SYSTEM_TLS_CERTS=1 pnpm build
# out/ → nexus_agent/static/ 복사
rm -rf nexus_agent/static && cp -r frontend/out nexus_agent/static
```
- `nexus_agent/static/`은 `.gitignore`에 포함 — 커밋 대상 아님
- Google Fonts TLS 오류 발생 시 `NEXT_TURBOPACK_EXPERIMENTAL_USE_SYSTEM_TLS_CERTS=1` 환경변수 필수

### Full Build (프론트엔드 포함 wheel 빌드)
```bash
./scripts/build.sh    # frontend build → nexus_agent/static/ → uv build
```

### Environment
설정 파일은 `~/.nexus-agent/`에 저장됨:
- `.env` — `GOOGLE_API_KEY` 등
- `settings.json` — LLM 설정
- `mcp.json` — MCP 서버 설정
- `skills.json`, `pages.json` — 런타임 데이터
- `workspaces.json` — 워크스페이스 등록 정보
- `memories.json` — 장기 기억 데이터

## Architecture

### Request Flow
```
User → ChatInterface (React) → POST /api/chat/stream (SSE) → AgentOrchestrator.run_stream()
  → LLMClient (LiteLLM acompletion) → Gemini API
  → SSE events: thinking → tool_call → tool_result → content → done
  → If tool_calls in response:
      → MCP tool call, Skill tool call, or Workspace tool call
      → Tool result appended to messages
      → Next LLM call with tool results
  → Final response → ChatInterface (+ memory auto-extraction)
```

### Package Structure
- `nexus_agent/` — Python 패키지 (최상위)
  - `cli.py` — click CLI 엔트리포인트 (`nexus-agent` 명령)
  - `server.py` — FastAPI 앱, 정적 파일 서빙, CORS 설정
  - `config.py` — `~/.nexus-agent/` 데이터 디렉토리 관리
  - `core/` — agent, llm, mcp_manager, skill_manager, page_manager, settings_manager, workspace_manager, workspace_tools, memory_manager
  - `api/endpoints/` — chat, mcp, skills, pages, settings, workspace, memory, sessions
  - `models/` — mcp, skill, page, settings, workspace, memory
  - `static/` — 빌드된 프론트엔드 (wheel에 포함, git에서 제외)

### Frontend Structure
- `frontend/src/app/page.tsx` — Home page rendering ChatInterface
- `frontend/src/app/pages/page.tsx` — Pages Dashboard
- `frontend/src/app/pages/viewer/page.tsx` — Page viewer (`?id=xxx` query param)
- `frontend/src/app/tools/page.tsx` — MCP Server management
- `frontend/src/app/skills/page.tsx` — Skills management
- `frontend/src/app/workspace/page.tsx` — Workspace Dashboard (등록/활성화/삭제)
- `frontend/src/app/workspace/viewer/page.tsx` — Workspace Viewer (파일 트리 + 파일 뷰어)
- `frontend/src/app/settings/page.tsx` — LLM Settings, Profile & Branding, Memory
- `frontend/src/lib/config.ts` — API_BASE_URL (빈 문자열 = same origin)

### Key Patterns
- **Path alias**: `@/*` maps to `./src/*` in tsconfig
- **shadcn/ui config**: `frontend/components.json` — new-york style, Lucide icons, CSS variables
- **Static export**: `next.config.ts`에 `output: "export"` — 빌드 시 정적 HTML 생성
- **Data directory**: 모든 런타임 데이터는 `~/.nexus-agent/`에 저장
- **Styling**: oklch color space, dark theme with glassmorphism (backdrop-blur, low-opacity borders), amber/orange primary color

## Workspace 보안 및 안전장치

### 경로 순회 방지
모든 워크스페이스 파일 작업은 `_resolve_safe_path()`로 루트 내부만 접근 가능. `../../etc/passwd` 등 차단.

### 위험 셸 명령 차단 (10종)
`workspace_bash` 도구에서 아래 패턴 매칭 시 실행 전 즉시 차단:
- `rm -rf /` / `rm -fr /` — 루트 재귀 삭제
- Fork bomb `:(){ :|:& };` — 무한 프로세스 생성
- `dd if=/dev/zero of=/dev/sda` — 디스크 덮어쓰기
- `mkfs.*` — 파일시스템 포맷
- `> /dev/sda` — 블록 디바이스 직접 쓰기
- `curl ... | sh` / `wget ... | sh` — 원격 스크립트 pipe-to-shell
- `chmod -R 777 /` — 루트 전체 권한 변경
- `chown -R ... /` — 루트 전체 소유자 변경

### 셸 실행 제한
- 타임아웃: 기본 30초, 최대 120초
- 출력 절삭: stdout 30,000자, stderr 5,000자
- 작업 디렉토리: 워크스페이스 루트 내부만 허용

### 파일 편집 안전장치
- 빈 old_string 거부
- old_string 다중 매치 시 replace_all=false면 거부 (매치 수 안내)

### 파일 트리 자동 제외
`.git`, `node_modules`, `__pycache__`, `.venv`, `.next`, `dist`, `build`, `.cache`, `target`, `.idea`, `.vscode` 등

## Git Convention

### 커밋 규칙
- **커밋 시 반드시 `/commit` (git-commit-formatter 스킬)을 사용할 것**
- Follow **Conventional Commits**: `<type>(scope): <description>`
- Types: feat, fix, docs, style, refactor, perf, test, chore
- Commit messages must be written in **Korean (한글)**
- Do NOT include `Co-Authored-By` in commit messages

### 작업 완료 흐름
1. 코드 수정
2. 프론트엔드 변경이 있으면 **빌드 후 `nexus-agent start`로 확인**
3. `/commit` 스킬로 커밋
4. `git push origin main`으로 푸시
5. **배포는 사용자가 명시적으로 요청할 때만 실행** (자동 배포 금지)

### 태그 & 배포 규칙
- 사용자가 배포를 요청하면 **새 패치 버전 태그**를 생성하여 배포 (GitHub Actions → PyPI)
- 버전 형식: `v0.MINOR.PATCH` (예: v0.3.5, v0.3.6, ...)
- **이미 푸시된 태그는 절대 `--force`로 덮어쓰지 않는다** — 항상 다음 번호로 올릴 것
- 배포 절차:
  1. `pyproject.toml`과 `nexus_agent/__init__.py`의 버전을 새 버전으로 업데이트
  2. `chore: vX.Y.Z 버전 업데이트` 커밋 (git-commit-formatter 스킬 사용)
  3. `git tag vX.Y.Z` 태그 생성
  4. `git push origin main && git push origin vX.Y.Z` 푸시

## Ports

| Service | URL |
|---------|-----|
| Frontend (dev) | http://localhost:3000 |
| Backend API / UI (production) | http://localhost:8000 |
| Swagger Docs | http://localhost:8000/docs |
