codernetes 0.1.0
Automated GitHub issue resolution system with distributed job execution platform powered by LLM agents
License: MIT
Requires Python: <4,>=3.10
Keywords: ai, automation, ci-cd, cli, code-generation, devops, distributed-system, github, llm, pull-request

<p align="center">
  <img src="frontend/public/codernetes-icon.svg" alt="Codernetes Icon" width="120" height="120"/>
</p>

# Codernetes

**자동화된 GitHub 이슈 해결 시스템**

Codernetes는 GitHub 이슈를 자동으로 해결하고 Pull Request를 생성하는 분산 작업 실행 플랫폼입니다. LLM Agent(Claude Code, Codex, Aider)를 활용하여 코드 변경을 자동화하고, Master/Node 아키텍처로 확장 가능한 워크플로우를 제공합니다.

<p align="center">
  <img src="frontend/public/codernetes-hero.svg" alt="Codernetes Architecture" width="800"/>
</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Node.js 18+](https://img.shields.io/badge/node.js-18+-green.svg)](https://nodejs.org/)

## 🎨 Codernetes

<div align="center">
  <img src="docs/assets/codernetes-logo.svg" alt="Codernetes Logo" width="200"/>
  <p><em>자동화된 GitHub 이슈 해결, 코드로 완성하다</em></p>
</div>

## 🎯 주요 기능

- **🤖 자동 코드 작업**: GitHub/Linear 이슈를 선택하면 LLM Agent가 자동으로 코드를 수정
- **🔄 PR 자동 생성**: 변경사항을 커밋하고 Pull Request 자동 생성
- **📐 Linear 통합**: Linear 이슈 관리 시스템 완벽 지원 (팀 선택, 이슈 필터링, 우선순위)
- **📊 실시간 모니터링**: 웹 대시보드에서 작업 진행 상황 실시간 추적
- **⚡ 분산 처리**: Master/Node 아키텍처로 여러 작업 병렬 실행
- **🚀 동시 작업 실행**: 단일 노드에서 최대 5개 작업 동시 처리 (설정 가능)
- **💬 응답 전용 모드**: 코드 변경 없이 Agent 응답만 제공하는 작업 지원
- **🛡️ 에러 핸들링**: 자동 에러 분류 및 재시도 로직
- **🔍 작업 로그**: 실시간 로그 스트리밍 및 검색

## 🏗️ 아키텍처

```
┌─────────────┐
│  Frontend   │  React + Vite (Port 5173)
│  Dashboard  │
└──────┬──────┘
       │ HTTP/WebSocket
┌──────▼──────────────────┐
│   Master Server         │
│  - HTTP API (8080)      │
│  - WebSocket Hub (8765) │
│  - SQLite DB            │
│  - Job Scheduler        │
└──────┬──────────────────┘
       │ WebSocket
┌──────▼───────┐  ┌─────────────┐  ┌─────────────┐
│   Node 1     │  │   Node 2    │  │   Node 3    │
│   Worker     │  │   Worker    │  │   Worker    │
└──────┬───────┘  └─────────────┘  └─────────────┘
       │
       └─► GitHub Clone → LLM Agent → Commit → Push → PR
```

## 🚀 빠른 시작

### 필수 요구사항

- Python 3.12+
- Node.js 18+
- [uv](https://github.com/astral-sh/uv) (Python 패키지 관리)
- GitHub Personal Access Token
- LLM Agent CLI (하나 선택):
  - **Claude Code**: `npm i -g @anthropic-ai/claude-code` + ANTHROPIC_API_KEY
  - **Codex**: `npm i -g @openai/codex` + ChatGPT Plus/Pro 계정 또는 OPENAI_API_KEY

### 설치

```bash
# 1. 저장소 클론
git clone https://github.com/your-org/codernetes.git
cd codernetes

# 2. Python 의존성 설치
uv sync

# 3. Frontend 설치
cd frontend
npm install
cd ..

# 4. 환경 변수 설정
cp .env.sample .env
# .env 파일 편집하여 필수 값 입력:
# GITHUB_TOKEN, ANTHROPIC_API_KEY, JOBS_WORK_DIR
```

### 실행

**Terminal 1 - Master 서버**:
```bash
uv run python -m master.server --host 0.0.0.0 --port 8765 --http-port 8080
```

**Terminal 2 - Node 클라이언트**:
```bash
# 기본값 사용 (localhost:8765에 연결)
uv run python -m node.client

# 또는 명시적으로 지정
uv run python -m node.client --host localhost --port 8765
```

**Terminal 3 - Frontend**:
```bash
cd frontend
npm run dev
```

브라우저에서 http://localhost:5173 접속

### 첫 번째 작업 실행

1. **Settings** 탭에서 GitHub Token 등록
2. **Jobs** 탭으로 이동
3. GitHub 저장소 선택 → 이슈 선택
4. Agent 타입 선택 (claude-code 권장)
5. **작업 생성** 클릭
6. 실시간으로 작업 진행 상황 모니터링
7. PR 생성 완료 후 GitHub에서 확인

## 📚 문서

- **[사용자 가이드](docs/user_guide.md)** - 기본 사용법 및 고급 설정
- **[Linear 통합 가이드](docs/linear_integration.md)** - Linear 이슈 관리 시스템 연동
- **[운영 가이드](docs/operations.md)** - 프로덕션 배포 및 운영
- **[구현 계획](docs/implementation_plan.md)** - Phase별 구현 상세
- **[구현 상태](docs/phase1_implementation_status.md)** - Phase 1 완료 현황

## 🎮 주요 컴포넌트

### Master Server

중앙 조율 서버로 다음 기능을 제공합니다:

- **HTTP API** (Port 8080): Job 생성, 조회, 상태 업데이트
- **WebSocket Hub** (Port 8765): Node 서버들과 실시간 통신
- **SQLite Database**: Job, Node, 로그 저장
- **Job Scheduler**: Node에 Job 할당

**주요 API 엔드포인트**:
- `GET /api/status` - 시스템 상태
- `GET /api/github/repos` - GitHub 저장소 목록
- `GET /api/github/issues` - 이슈 목록
- `POST /api/jobs` - Job 생성
- `GET /api/jobs` - Job 목록
- `GET /api/jobs/{id}` - Job 상세
- `GET /api/jobs/{id}/logs` - Job 로그

### Node Server

작업 실행 워커로 다음을 수행합니다:

1. **동시 작업 처리**: 최대 5개 작업 병렬 실행 (node-config.yaml에서 설정 가능)
2. **격리된 작업 환경**: 각 작업은 독립된 디렉터리에서 실행
3. **Git 저장소 클론**
4. **LLM Agent 실행** (Claude Code, Codex, Aider)
5. **변경사항 커밋** (변경사항이 있는 경우)
6. **GitHub에 Push** (변경사항이 있는 경우)
7. **Pull Request 생성** (변경사항이 있는 경우)
8. **Agent 응답 전달** (코드 변경이 없어도 Agent의 분석/설명 제공)
9. **실시간 로그 전송**

**동시 작업 실행 설정 (node-config.yaml)**:
```yaml
# Performance
max_concurrent_jobs: 5  # 동시 실행 가능한 최대 작업 개수 (기본값: 5)
```

### Frontend Dashboard

React + Vite 기반 웹 대시보드:

- **Jobs**: 작업 생성 및 모니터링
- **Settings**: GitHub 연동 및 시스템 설정
- **Nodes**: 연결된 Node 서버 관리

## 🔧 고급 설정

### Agent CLI 설정

Codernetes는 2가지 LLM Agent를 지원합니다:

#### 1. Claude Code
```bash
# 설치
npm i -g @anthropic-ai/claude-code

# 환경 변수
export ANTHROPIC_API_KEY=sk-ant-your-key

# 특징
# - --print 플래그: 비대화형 출력 모드
# - --dangerously-skip-permissions: 자동화를 위한 권한 우회
# - Codernetes는 신뢰된 환경에서 이 플래그들을 사용합니다

# 수동 테스트
claude --print "Say hello"
claude --print --dangerously-skip-permissions "Create a test file"
```

#### 2. Codex
```bash
# 설치 (npm)
npm install -g @openai/codex

# 또는 Homebrew (macOS)
brew install --cask codex

# 인증 방법 (둘 중 하나)
# 1. ChatGPT 계정 (Plus/Pro/Team/Enterprise)
codex  # 브라우저에서 로그인

# 2. OpenAI API Key
export OPENAI_API_KEY=sk-your-openai-key

# 특징
# - 'codex exec' 명령으로 비대화형 실행
# - ChatGPT 계정 또는 API Key 인증
# - GitHub Action, TypeScript SDK 지원
# - MCP (Model Context Protocol) 서버 연결 지원
# - 구성 파일: ~/.codex/config.toml

# 더 많은 정보: https://github.com/openai/codex
```

### .codernetes/agent.md

저장소에 `.codernetes/agent.md` 파일을 추가하여 Agent 동작을 커스터마이징할 수 있습니다:

```markdown
# Codernetes Agent Configuration

## Agent Settings
**Agent Type**: claude-code
**Auto Commit**: true

## Code Style
**Linter**: eslint
**Formatter**: prettier

## Testing Policy
**Required**: true
**Command**: npm test
**Coverage Threshold**: 80%

## Protected Paths
- /config/
- /secrets/

## System Prompt
You are a senior software engineer.
Follow existing code style and patterns.
Write comprehensive tests for new features.
```

### 환경 변수

`.env` 파일에서 설정할 수 있는 주요 환경 변수:

```bash
# GitHub
GITHUB_TOKEN=ghp_your_token_here

# Linear (선택)
LINEAR_USER_ID=user:12345
LINEAR_API_KEY=lin_api_your_key_here

# Anthropic (Claude Code)
ANTHROPIC_API_KEY=sk-ant-your_key_here

# 작업 디렉토리
JOBS_WORK_DIR=/tmp/codernetes-jobs

# 서버 설정
MASTER_HOST=0.0.0.0
MASTER_PORT=8765
MASTER_HTTP_PORT=8080

# 로그 레벨
LOG_LEVEL=INFO
```

## 🛡️ 에러 핸들링

Codernetes는 포괄적인 에러 핸들링 시스템을 갖추고 있습니다:

**에러 분류**:
- Network errors
- Authentication errors
- Resource errors
- Timeout errors
- Git errors
- Agent execution errors

**자동 재시도**:
- Network: 3회, 5초 간격
- Timeout: 2회, 10초 간격
- Agent: 2회, 15초 간격
- Git: 2회, 5초 간격

**재시도 불가**:
- Authentication errors
- Validation errors

## 📊 작업 워크플로우

### 코드 변경 작업
```
1. pending      → Job 생성
2. queued       → 큐 대기
3. running      → 실행 시작
4. accepted     → Node가 수락
5. cloning      → Git 클론
6. agent_working → Agent 실행
7. committing   → 변경사항 커밋
8. pushing      → GitHub Push
9. pr_creating  → PR 생성 중
10. pr_created  → PR 생성 완료 ✅
```

### 응답 전용 작업 (코드 변경 없음)
```
1. pending      → Job 생성
2. queued       → 큐 대기
3. running      → 실행 시작
4. accepted     → Node가 수락
5. cloning      → Git 클론
6. agent_working → Agent 실행 (분석/설명)
7. succeeded    → Agent 응답 제공 완료 ✅
   (committing, pushing, pr_creating 단계 스킵)
```

**응답 전용 모드 사용 예시**:
- 코드 리뷰 및 분석
- 아키텍처 설명
- 버그 원인 분석
- 개선 제안
- 문서 질문 답변

## 🔐 보안

### GitHub Token 권한

필요한 최소 권한:
- `repo` (저장소 접근)
- `workflow` (GitHub Actions)

### API Key 관리

- 환경 변수로 관리
- 절대 코드에 하드코딩 금지
- 정기적으로 키 순환 (90일 권장)

### 네트워크

- Master/Node 간 WebSocket은 내부 네트워크만 허용
- Frontend는 Nginx 리버스 프록시 사용
- HTTPS/TLS 설정 권장

## 🧪 테스트

### Unit/Integration 테스트
```bash
# Python 테스트
uv run pytest

# Frontend 테스트
cd frontend
npm test
```

### E2E 테스트 (Playwright)

E2E 테스트로 전체 시스템 워크플로우를 검증할 수 있습니다.

```bash
# 1. E2E 테스트 환경 설정 (최초 1회)
cd tests/e2e
./setup.sh

# 2. Master와 Node 서버 시작 (별도 터미널)
uv run python -m master.server
uv run python -m node.client

# 3. E2E 테스트 실행
cd tests/e2e
./run-tests.sh

# 또는 직접 실행
npm test                 # 모든 테스트
npm run test:critical    # 크리티컬 테스트만
npm run test:headed      # 브라우저 표시 모드
npm run test:ui          # 인터랙티브 UI 모드

# 테스트 리포트 보기
npm run report
```

**E2E 테스트 커버리지**: 37개 테스트 케이스 (기본 워크플로우, 노드 연결, 작업 취소, GitHub 통합, 에러 처리)

자세한 내용은 [E2E 테스트 README](tests/e2e/README.md) 참조

## 📈 모니터링

### 로그 확인

```bash
# Master 로그
tail -f /var/log/codernetes/master.log

# Node 로그
tail -f /var/log/codernetes/node.log

# 특정 Job 로그 (웹 대시보드에서 실시간 확인 가능)
```

### Job 통계

```bash
sqlite3 /var/lib/codernetes/codernetes.db <<EOF
SELECT status, COUNT(*) FROM jobs GROUP BY status;
EOF
```

## 🤝 기여하기

기여는 언제나 환영합니다!

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.

## 🎯 로드맵

### Phase 1 (완료) ✅
- GitHub 통합 및 이슈 선택
- Linear 통합 (팀 선택, 이슈 필터링, 브랜치 자동 생성)
- LLM Agent 실행 (Claude Code, Codex, Aider)
- PR 자동 생성
- 웹 대시보드
- 에러 핸들링
- 실시간 로그
- 동시 작업 실행 (노드당 최대 5개, 설정 가능)
- 응답 전용 모드 (코드 변경 없는 작업)

### Phase 2 (계획)
- PR 자동 리뷰
- 자동 병합 (조건부)
- Slack/Telegram 통합
- 다중 저장소 지원
- 작업 템플릿

### Phase 3 (계획)
- 성능 최적화
- 고급 스케줄링
- 작업 우선순위
- 리소스 관리
- 통계 및 분석

## 📞 지원

- **Issues**: [GitHub Issues](https://github.com/your-org/codernetes/issues)
- **문서**: `/docs` 디렉토리
- **Email**: [jiunbae.dev@gmail.com](mailto:jiunbae.dev@gmail.com)

## 🙏 감사의 말

이 프로젝트는 다음 오픈소스 프로젝트들의 도움을 받아 개발되었습니다:

- [Claude](https://www.anthropic.com/claude) by Anthropic
- [FastAPI](https://fastapi.tiangolo.com/)
- [React](https://react.dev/)
- [PyGithub](https://github.com/PyGithub/PyGithub)
- [websockets](https://github.com/python-websockets/websockets)

---

**Made with ❤️ by the Codernetes Team**

**버전**: 1.1 (Phase 1 Complete + Concurrent Execution)
**최종 업데이트**: 2025-11-01