Taskie

여러 프로젝트의 .claude/tasks 디렉토리를 한 곳에서 관리하는 웹 기반 작업 관리 도구입니다.

소개

Taskie는 개발자가 여러 프로젝트에 흩어진 작업 파일들을 효율적으로 관리할 수 있도록 돕는 웹 애플리케이션입니다. 각 프로젝트의 .claude/tasks 디렉토리에 있는 마크다운 파일들을 중앙에서 조회하고 편집할 수 있습니다.

주요 기능

• ✅ 멀티 프로젝트 관리: 여러 프로젝트를 등록하고 빠르게 전환
• 📝 작업 편집: 마크다운 형식의 작업 파일 생성, 수정, 삭제
• 🔍 빠른 조회: 최근 사용한 프로젝트 및 작업 바로 접근
• 💾 파일 기반: 별도 데이터베이스 없이 로컬 파일 시스템 활용
• 🌐 웹 인터페이스: 브라우저에서 편리하게 사용
• 🚀 간편한 설치: npx로 설치 없이 바로 실행 가능

빠른 시작 (권장)

npx로 실행 (설치 불필요)

npx taskie-ai

명령어 하나로 Taskie를 실행할 수 있습니다. 서버가 자동으로 시작되고 브라우저가 열립니다.

첫 실행 시:

• 의존성이 자동으로 설치됩니다 (약 5-10초 소요)
• 서버가 http://localhost:50902에서 시작됩니다
• 브라우저가 자동으로 열립니다

두 번째 실행부터:

• 즉시 실행됩니다 (의존성 설치 불필요)

명령줄 옵션

# 기본 실행 (웹 UI)
npx taskie-ai

# 포트 변경
npx taskie-ai --port 8080

# 브라우저 자동 오픈 비활성화
npx taskie-ai --no-open

# 버전 확인
npx taskie-ai --version

# 도움말
npx taskie-ai --help

CLI 명령어

Taskie는 웹 UI 외에도 터미널에서 사용할 수 있는 CLI 명령어를 제공합니다:

# 프로젝트 목록 조회
taskie list
# 또는
taskie projects

# 특정 프로젝트의 작업 목록 조회
taskie tasks <프로젝트-ID-또는-이름>

# 특정 진행 상태만 필터링
taskie tasks Taskie --progress Doing

# JSON 형식으로 출력
taskie list --json
taskie tasks Taskie --json

# 새 프로젝트 추가
taskie add /path/to/project

# 프로젝트 이름 지정하여 추가
taskie add /path/to/project --name "내 프로젝트"

# 프로젝트 등록 (.claude/tasks 초기화)
taskie register <프로젝트-ID-또는-이름>

# 웹 UI 실행
taskie open

# 특정 프로젝트로 바로 이동하여 웹 UI 실행
taskie open <프로젝트-ID>

설치 방법

방법 1: 전역 설치 (추천)

전역으로 설치하면 taskie 명령어를 어디서나 사용할 수 있습니다:

npm install -g taskie-ai

설치 후 실행:

taskie

방법 2: npx (설치 불필요)

설치 없이 바로 실행:

npx taskie-ai

방법 3: 개발자 모드 (Git Clone)

Taskie 개발에 기여하고 싶으신가요?

# 1. 저장소 클론
git clone https://github.com/your-username/taskie.git
cd taskie

# 2. 의존성 설치
pnpm install

# 3. 백엔드 실행 (터미널 1)
pnpm server:dev
# → http://localhost:3001

# 4. 프론트엔드 실행 (터미널 2)
pnpm dev
# → http://localhost:3000

개발 모드에서는:

• 프론트엔드: http://localhost:3000 (Vite HMR 지원)
• 백엔드: http://localhost:3001 (API 서버)
• 두 개의 프로세스를 별도로 실행 (Hot Reload 지원)

시스템 요구사항

일반 사용자 (npx/npm)

• Node.js: 18.0 이상

개발자 (Git Clone)

• Node.js: 18.0 이상
• pnpm: 9.0 이상
• 운영체제: macOS, Linux, Windows

사용 방법

프로젝트 추가하기

1. 프로젝트 목록 페이지에서 "프로젝트 추가" 버튼 클릭
2. 프로젝트 이름과 절대 경로 입력
   • 예: /Users/username/projects/my-project
3. 저장하면 해당 프로젝트의 .claude/tasks 디렉토리가 관리 대상에 추가됩니다

작업 조회하기

1. 홈 화면 또는 프로젝트 목록에서 프로젝트 선택
2. 해당 프로젝트의 모든 작업 파일이 표시됩니다
3. 작업을 클릭하면 상세 내용을 볼 수 있습니다

작업 생성하기

1. 프로젝트 상세 페이지에서 "새 작업" 버튼 클릭
2. 파일명과 내용 입력
3. 저장하면 .claude/tasks/ 디렉토리에 파일이 생성됩니다

작업 편집 및 삭제

• 편집: 작업 상세 페이지에서 내용을 수정하고 저장
• 삭제: 삭제 버튼 클릭 후 확인

파일 구조

Taskie는 다음 위치에 데이터를 저장합니다:

~/.taskie/
├── projects.json       # 등록한 프로젝트 목록
└── config.json         # 앱 설정 (최근 프로젝트 등)

각 프로젝트의 작업 파일은 원래 위치에 그대로 유지됩니다:

{your-project}/
└── .claude/
    └── tasks/
        ├── task-001.md
        ├── feature-login.md
        └── bug-fix-auth.txt

환경 변수 설정 (선택사항)

백엔드

server/.env 파일을 생성하여 포트를 변경할 수 있습니다:

PORT=3001
HOST=0.0.0.0

프론트엔드

.env 파일을 생성하여 백엔드 URL을 설정할 수 있습니다:

VITE_API_URL=http://localhost:3001

문제 해결

백엔드가 시작되지 않을 때

# 포트가 이미 사용 중인지 확인
lsof -i :3001

# 프로세스 종료
kill -9 <PID>

프로젝트가 추가되지 않을 때

• 입력한 경로가 올바른지 확인하세요
• 경로는 절대 경로여야 합니다 (예: /Users/username/project)
• 해당 디렉토리에 접근 권한이 있는지 확인하세요

작업 파일이 보이지 않을 때

• .claude/tasks/ 디렉토리가 프로젝트 루트에 존재하는지 확인
• 파일 확장자가 .md 또는 .txt인지 확인

추가 기능

자동 업데이트 알림

Taskie를 실행할 때 새 버전이 출시되면 자동으로 알림을 받습니다:

$ taskie

📢 새로운 버전이 출시되었습니다: v0.2.0 (현재: v0.1.0)
   업데이트: npm install -g taskie-ai@latest

🚀 Taskie가 http://localhost:50902 에서 실행 중입니다

업데이트 체크는 하루에 한 번만 수행됩니다.

다중 인스턴스 실행 방지

Taskie는 한 번에 하나의 인스턴스만 실행할 수 있습니다:

$ taskie
❌ Taskie가 이미 실행 중입니다.
   실행 중인 프로세스 PID: 12345
   종료하려면: kill 12345

포트 충돌 자동 처리

기본 포트(50902)가 사용 중이면 자동으로 다음 사용 가능한 포트를 찾습니다:

$ taskie
⚠️  포트 50902가 사용 중입니다. 50903을 시도합니다...
🚀 Taskie가 http://localhost:50903 에서 실행 중입니다

기술 스택

| 구분 | 기술 | |------|------| | 프론트엔드 | React, TypeScript, Tailwind CSS, Vite | | 백엔드 | Fastify, TypeScript, Node.js | | 스타일링 | Tailwind CSS, SCSS |

라이선스

MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다.

지원 및 문의

• 이슈 제보: GitHub Issues
• 기능 제안: GitHub Discussions

기여하기

Pull Request는 언제나 환영합니다!

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

개발자 가이드는 .claude/PRD.md를 참고하세요.