https://github.com/clawket/clawket
LLM-native work management plugin for Claude Code — structured task board across sessions
https://github.com/clawket/clawket
claude-code llm project-management sqlite task-management
Last synced: about 2 months ago
JSON representation
LLM-native work management plugin for Claude Code — structured task board across sessions
- Host: GitHub
- URL: https://github.com/clawket/clawket
- Owner: clawket
- Created: 2026-04-11T14:38:14.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T14:21:38.000Z (2 months ago)
- Last Synced: 2026-04-17T15:38:58.996Z (2 months ago)
- Topics: claude-code, llm, project-management, sqlite, task-management
- Language: JavaScript
- Size: 9.65 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.ko.md
Awesome Lists containing this project
README
[English](README.md)
Claude Code를 위한 LLM 네이티브 작업 관리 + 로컬 RAG 플러그인
Clawket은 LLM 기반 개발을 위한 구조화된 상태 레이어로, Jira + Confluence를 대체합니다. 프로젝트 계획, 유닛, 태스크, 산출물, 실행 이력을 로컬 SQLite + 경량 데몬으로 세션 간 영구 보존합니다. 훅 기반 가드레일이 에이전트가 등록된 태스크 없이 작업하지 못하게 보장합니다 — 모든 작업은 추적되고, 모든 세션은 컨텍스트를 가집니다.
상태 레이어 위에 **로컬 RAG 스택**(sqlite-vec + 온디바이스 임베딩)과 **MCP stdio 서버**(CLI 바이너리에 rmcp 1.5 로 내장)를 제공하므로, 외부 벡터 DB로 데이터를 내보내지 않고도 세션 간에 의미 기반 컨텍스트를 pull 할 수 있습니다.
## 왜 Clawket인가
구조화된 상태 레이어 없이 Claude Code 세션은 무상태(stateless)입니다:
- **컨텍스트 소실** — 세션이 바뀌면 처음부터 시작. "어디까지 했더라?"에 답이 없음.
- **작업 미추적** — 에이전트가 뭘 바꿨는지, 언제, 왜 바꿨는지 기록 없음.
- **플랜 노후화** — Plan Mode 파일이 `~/.claude/plans/`에 방치됨.
- **서브에이전트 단절** — 병렬 에이전트가 프로젝트 상태를 공유하지 못함.
- **과거 결정 소실** — 이전 설계 근거를 다음 세션이 떠올리지 못함.
Clawket은 영구 DB, 로컬 벡터 RAG, MCP pull 인터페이스, 런타임 어댑터, 웹 대시보드로 이 문제를 해결합니다 — 전부 로컬 실행.
## 주요 기능
- **구조화된 워크플로우** — Project → Plan (approve) → Unit → Task → Cycle (activate)
- **라이프사이클 훅** — 9개 이벤트 타입에 10개 훅 배치
- **웹 대시보드** — 요약, 계획, 보드(칸반), 백로그, 타임라인, 위키 6개 뷰
- **에이전트 Swimlane 타임라인** — 에이전트별 수평 바 차트로 동시 작업 시각화
- **드래그 앤 드롭** — 칸반 DnD로 상태 변경, 백로그 DnD로 사이클 배정
- **위키 + 로컬 RAG** — 파일 트리 내비게이션, Artifact 버전 관리, `scope=rag` artifact에 대한 FTS5 키워드 + sqlite-vec 의미 검색 하이브리드
- **자동 임베딩** — `scope=rag` artifact와 모든 task가 생성/수정 시 자동 임베딩. 데몬 startup에 누락 분 백필.
- **MCP RAG Pull** — `clawket mcp` (CLI 바이너리에 내장된 stdio 서버)가 5개 read-only tool을 Claude Code tool_use로 노출. `rag` scope만 반환.
- **훅 가드레일** — 활성 태스크 없이 작업 불가, 세션마다 프로젝트 컨텍스트 자동 주입
- **티켓 번호** — 내부 ULID와 함께 사람이 읽을 수 있는 ID (CK-1, CK-2) + 토큰 최적화
- **CLI + Web** — LLM(CLI)과 사람(웹 UI)이 동일한 상태를 관리
### Claude 훅
| 훅 | 트리거 | 용도 |
|----|--------|------|
| **SessionStart** | 세션 시작(startup/clear/compact) | 데몬 시작 보장, 대시보드 컨텍스트 + 규칙 주입 |
| **UserPromptSubmit** | 사용자 메시지마다 | 활성 태스크 컨텍스트 주입, 활성 태스크 없으면 경고 |
| **PreToolUse** | Edit/Write/Bash/Agent/TeamCreate/SendMessage | 활성 태스크 없으면 변경 작업 차단 |
| **PostToolUse** | Edit/Write | 파일 변경을 활성 태스크에 기록 |
| **PostToolUse** | ExitPlanMode | Plan Mode 출력을 Clawket에 등록하도록 안내 |
| **SubagentStart** | 서브에이전트 시작 | 에이전트를 배정된 Clawket 태스크에 바인딩 |
| **SubagentStop** | 서브에이전트 종료 | 결과 요약 추가, 태스크 자동 완료 |
| **TaskCreated** | 팀 에이전트 태스크 생성 | 매칭되는 todo 태스크 자동 시작 (todo → in_progress) |
| **TaskCompleted** | 팀 에이전트 태스크 완료 | 매칭되는 in_progress 태스크 자동 완료 (→ done) |
| **Stop** | 세션 종료 | 해당 세션의 모든 활성 실행(Run) 종료 |
태스크가 `done`/`cancelled`로 전환되면, 데몬이 Unit/Plan/Cycle 완료를 자동 cascade 합니다.
### 기술 스택
| 레이어 | 기술 |
|---|---|
| CLI | Rust 단일 바이너리 (`clawket` / `clawket mcp`) |
| 데몬 | Rust (axum + rusqlite), Unix socket + TCP |
| 저장소 | SQLite + sqlite-vec (vec0 virtual tables) |
| 임베딩 | `candle-core` + `all-MiniLM-L6-v2` (384d, 온디바이스) |
| MCP | `rmcp` 1.5 stdio 서버, CLI 바이너리에 내장 |
| 웹 | React 19 + Vite + Tailwind + dnd-kit |
| 어댑터 | Claude Code plugin + hooks + skills + `.mcp.json` |
## 설치
```bash
# 1. 마켓플레이스 추가
/plugin marketplace add clawket/clawket
# 2. 플러그인 설치
/plugin install clawket@clawket
```
바이너리(`clawket` CLI, `clawketd` 데몬, 웹 번들)는 GitHub Releases 에서 idempotent 한 install gate (`adapters/shared/claude-hooks.cjs::ensureInstalled`) 가 다운로드합니다. 이 게이트는 `SessionStart` 와 MCP first spawn 양쪽에서 호출되며, 먼저 발화한 쪽이 설치를 수행하고 이후에는 버전 마커 일치 시 no-op 입니다. 임베딩 모델은 데몬이 최초 사용 시 가져옵니다. MCP stdio 서버(`clawket mcp`)는 플러그인의 `.mcp.json`을 통해 등록되며, 번들된 `scripts/mcp-launch.cjs` 가 install gate 를 한 번 더 통과시킨 뒤 CLI 를 exec 합니다.
### 사전 요구사항
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
- Node.js 20+ (setup 훅 실행용)
- Rust 툴체인은 **불필요** — 플러그인 setup 이 `clawket`, `clawketd` 바이너리를 자동 다운로드합니다. CLI/daemon 를 직접 개발할 때만 Rust 가 필요합니다.
## 로컬 RAG
Clawket의 RAG는 전적으로 데몬 내부에서 동작합니다. 외부로 아무것도 나가지 않습니다.
### 임베딩 대상
| 엔티티 | 트리거 | 임베딩 소스 텍스트 |
|---|---|---|
| Task | 생성/업데이트 시 매번, 누락 분은 데몬 startup에서 백필 | `title\nbody` |
| Artifact | 생성/업데이트 시, **단** `scope=rag` 이고 `content`가 있을 때만 | `title\ncontent` |
`reference`, `archive` artifact는 임베딩되지 않고 LLM에도 노출되지 않습니다.
### 벡터 저장
- `vec_tasks(task_id TEXT PRIMARY KEY, embedding float[384])`
- `vec_artifacts(artifact_id TEXT PRIMARY KEY, embedding float[384])`
둘 다 sqlite-vec `vec0` 가상 테이블입니다. `vec0`는 `INSERT OR REPLACE`를 지원하지 않으므로 업데이트는 `DELETE` + `INSERT` 패턴을 씁니다.
### 하이브리드 검색
데몬이 task와 artifact에 대해 키워드(FTS5), 의미(vec0 KNN), 하이브리드 검색 HTTP 엔드포인트를 제공합니다. 웹 위키, CLI `search` 서브커맨드, MCP 서버가 동일 엔드포인트를 재사용합니다.
## MCP 서버
Clawket은 MCP stdio 서버를 제공해 Claude Code가 필요할 때 컨텍스트를 **pull** 할 수 있게 합니다(SessionStart의 push 주입을 보완). Rust `rmcp` 1.5 로 구현되어 **`clawket` CLI 바이너리에 내장**되어 있으며 `clawket mcp` (stdio)로 호출됩니다. `~/.cache/clawket/clawketd.port`에서 포트를 자동 탐지해 데몬 HTTP API를 호출합니다. 플러그인 `.mcp.json`이 이를 Claude Code 에 연결합니다.
| 도구 | 용도 |
|------|------|
| `clawket_search_artifacts` | `scope=rag` artifact에 대한 의미/키워드/하이브리드 검색 |
| `clawket_search_tasks` | task에 대한 의미/키워드/하이브리드 검색 |
| `clawket_find_similar_tasks` | 시드 task의 KNN 이웃, 코멘트에서 결정사항/이슈 추출 |
| `clawket_get_task_context` | task + 연관 artifact / 관계 / 코멘트 / 활동 이력 |
| `clawket_get_recent_decisions` | `type=decision, scope=rag` artifact를 최근 순으로 반환 |
수동 실행: `clawket mcp` (stdio).
**Scope 경계**: `archive`, `reference` artifact는 절대 반환되지 않습니다 — `rag` scope 지식만 LLM에 노출됩니다.
> 레거시 `@clawket/mcp` npm 패키지(Node stdio 서버)는 더이상 `.mcp.json` 에 등록되지 않으며, 플러그인 v11 U4 에서 archive 예정입니다.
## 아키텍처
```
Claude Code
├─ 플러그인 훅 ────────────────┐
└─ .mcp.json → stdio 자식 ──┐ │
│ │
▼ ▼
clawket mcp (rmcp stdio, CLI 내장)
│ (HTTP, 포트 자동 탐지)
▼
clawketd (Rust: axum + rusqlite)
│ ├─ Unix socket: ~/.cache/clawket/clawketd.sock
│ ├─ TCP: http://127.0.0.1:
│ ├─ SSE 이벤트 버스 (/events)
│ ├─ POST/PATCH 시 auto-embed (scope=rag)
│ └─ Startup 백필 (누락된 vec_tasks)
▼
SQLite + sqlite-vec
~/.local/share/clawket/db.sqlite
웹 대시보드 (React 19) ─────▶ clawketd HTTP API + SSE
```
### 데이터 저장 경로 (XDG)
| 경로 | 용도 | 오버라이드 |
|---|---|---|
| `~/.local/share/clawket/` | SQLite DB | `CLAWKET_DATA_DIR` |
| `~/.cache/clawket/` | Unix socket, pid, port, 런타임 상태 | `CLAWKET_CACHE_DIR` |
| `~/.config/clawket/` | 설정 | `CLAWKET_CONFIG_DIR` |
| `~/.local/state/clawket/` | 로그 | `CLAWKET_STATE_DIR` |
## 디렉토리 구조
**v2.3.0** 부터 이 레포는 얇은 플러그인 쉘입니다. cli/daemon/web 소스는 `clawket`
GitHub 조직의 형제 레포로 이관되었고, setup 이 `clawket`, `clawketd` 바이너리를
GitHub Releases 에서 받아옵니다. **v2.3.2** 부터 플러그인 설치 시 npm install 이
발생하지 않습니다.
```
clawket/
├── .claude-plugin/ # Claude 플러그인 매니페스트 + 마켓플레이스 메타
├── .mcp.json # `clawket mcp` (stdio) 등록 — scripts/mcp-launch.cjs 를 가리킴
├── hooks/hooks.json # Claude 훅 라우팅 매니페스트
├── components.json # setup 이 사용하는 cli / daemon / web 바이너리 핀 버전
├── skills/clawket/ # /clawket 스킬 (SKILL.md)
├── prompts/ # 공용 + 런타임별 프롬프트 조각
├── adapters/
│ ├── shared/ # claude-hooks.cjs — install gate (`ensureInstalled`) + 데몬 glue
│ └── claude/ # Claude 어댑터 엔트리포인트 (훅 .cjs 핸들러)
├── scripts/
│ ├── setup.cjs # 수동/CI 진입점 — ensureInstalled 위임
│ └── mcp-launch.cjs # MCP first-spawn launcher — ensureInstalled 후 `clawket mcp` exec
├── docs/ # COMPATIBILITY.md + RELEASING.md + HOOK_ENFORCEMENT.md
├── assets/ # 로고, 마스코트, 브랜딩
├── screenshots/ # 대시보드 스크린샷
├── bin/ # (setup 이 생성) 다운로드한 clawket CLI 바이너리
├── daemon/bin/ # (setup 이 생성) 다운로드한 clawketd 바이너리
└── web/dist/ # (setup 이 생성) 압축 해제된 웹 대시보드 번들
```
### 분리 레포
| 레포 | 내용 | 소비 방식 |
|---|---|---|
| [`clawket/cli`](https://github.com/clawket/cli) | Rust CLI + 내장 `clawket mcp` (rmcp 1.5) | GitHub Releases 바이너리 |
| [`clawket/daemon`](https://github.com/clawket/daemon) | Rust 데몬 (axum + rusqlite + sqlite-vec + candle-core) | GitHub Releases 바이너리 |
| [`clawket/web`](https://github.com/clawket/web) | React 대시보드 | GitHub Releases tarball |
| [`clawket/landing`](https://github.com/clawket/landing) | 공개 랜딩 페이지 | Cloudflare Pages |
| [`clawket/tap`](https://github.com/clawket/tap) | Homebrew formula | Homebrew 배포 채널 |
| [`clawket/mcp`](https://github.com/clawket/mcp) | 레거시 Node MCP 서버 | **deprecated** — 플러그인 v11 U4 에서 archive 예정 |
버전 호환 범위는 `docs/COMPATIBILITY.md` 참조.
## 웹 대시보드
데몬 실행 중 `http://localhost:19400`에서 접근할 수 있습니다. 6개 뷰, SSE 실시간 반영.
| 뷰 | 설명 |
|----|------|
| **요약** | 프로젝트 진행률, 활성 에이전트, 유닛 상태 |
| **계획** | 트리 뷰 — 인라인 편집, 일괄 액션, 체크박스 선택 |
| **보드** | 칸반 보드 — 드래그 앤 드롭 상태 변경 |
| **백로그** | 사이클별 그룹화 — 드래그 앤 드롭 배정 |
| **타임라인** | 에이전트 Swimlane (Run 바 차트) + 활동 스트림 탭 |
| **위키** | 파일 트리, Artifact CRUD + 버전 이력, FTS5 + 의미 검색, GFM 테이블 |
### 스크린샷
| 요약 | 계획 |
|------|------|
|  |  |
| 보드 (칸반) | 백로그 |
|-------------|--------|
|  |  |
| 타임라인 | 위키 |
|----------|------|
|  |  |
## 사용법
Clawket은 구조화된 워크플로우를 강제합니다. 프로젝트 + 활성 플랜 + 활성 태스크가 모두 존재해야 에이전트가 변경 작업을 시작할 수 있습니다. PreToolUse 훅이 활성 태스크 없이 Edit/Write/Bash/Agent/TeamCreate/SendMessage 호출을 차단합니다.
### 처음 시작하기
새 디렉토리에서 먼저 프로젝트를 등록해야 합니다:
```
사용자: "이 디렉토리를 새 프로젝트로 등록해줘"
→ 에이전트 실행: clawket project create "my-project" --cwd "."
→ 웹 대시보드 사이드바에 프로젝트 표시
```
### 작업 계획
Clawket이 플랜의 source of truth입니다 — Claude의 Plan Mode 파일(`~/.claude/plans/`)이 아닙니다. 로컬 파일로 관리하지 않아 파일 오염·동기화 문제가 없습니다.
**일반 모드:**
```
사용자: "인증 리팩토링 계획 세워줘"
→ 에이전트가 코드베이스 분석 후 대화에서 플랜 제안
→ 사용자 검토/승인
→ 에이전트가 CLI로 등록:
clawket plan create --project PROJ-xxx "인증 리팩토링"
clawket plan approve PLAN-xxx
clawket unit create --plan PLAN-xxx "Unit 1 — OAuth 설정"
clawket task create "OAuth 흐름 구현"
clawket cycle create --project PROJ-xxx "Sprint 1"
clawket cycle activate CYC-xxx
clawket task update TASK-xxx --cycle CYC-xxx
```
**플랜 모드 (`/plan`):**
```
사용자: /plan
사용자: "인증 리팩토링 계획 세워줘"
→ 에이전트가 대화 컨텍스트로 플랜 제안 (Write는 훅에 의해 차단됨)
→ 사용자가 ExitPlanMode로 승인
→ 에이전트가 승인된 내용을 CLI로 등록
```
### 새 작업 시작
```
사용자: "설정 페이지 로그인 버그 수정해줘"
→ 에이전트가 기존 plan/unit/cycle 하위에 태스크 등록
→ in_progress → done 처리
(PreToolUse 훅이 태스크 없이 작업하는 것을 차단)
```
### 과거 컨텍스트 pull (MCP)
```
사용자: "과거에 인증 재시도 정책에 대한 결정 있었어?"
→ 에이전트가 clawket_search_artifacts / clawket_get_recent_decisions 호출
→ scope=rag artifact만 의미 유사도로 반환
```
### 웹 대시보드에서 리뷰
`http://localhost:19400` 에서 보드(현재 스프린트), 백로그, 타임라인(에이전트 swimlane), 위키(문서 + artifact)를 확인할 수 있습니다.
### 핵심 개념
| 개념 | 설명 |
|------|------|
| **Project** | Clawket에 등록된 작업 디렉토리 |
| **Plan** | 상위 의도 (로드맵). approve 후에만 task를 시작할 수 있음 |
| **Unit** | 플랜 내 순수 그룹핑 엔티티 (상태 없음) |
| **Task** | 원자적 작업 단위. 사이클 없이 생성 가능 (백로그로 이동) |
| **Cycle** | 스프린트 — 시간 제한 이터레이션. 활성 사이클에 배정돼야 시작 가능 |
| **Artifact** | 버전 관리되는 첨부 문서. `scope` ∈ {`rag`, `reference`, `archive`}. `rag`만 임베딩되고 LLM에 노출됨 |
| **Backlog** | 사이클 미배정 태스크. 드래그로 사이클에 배정 |
### 상태 관리
- **Plan**: `draft` → `active`(approve로 의도적 활성화) → `completed`(의도적 종료)
- **Unit**: 상태 없음 — 순수 그룹
- **Cycle**: `planning` → `active`(의도적 시작) → `completed`(의도적 종료). 재시작 불가.
- **Task**: `todo` → `in_progress` → `done`/`cancelled`. 시작하려면 활성 플랜 + 활성 사이클 필요. `blocked`도 유효.
### 프로젝트 비활성화
웹 대시보드에서 **Project Settings → Clawket Management** 토글을 끄면, 훅이 해당 디렉토리를 미등록 상태로 인식합니다. 기존 데이터는 보존되며, 언제든 다시 켜서 구조화된 워크플로우를 재개할 수 있습니다.
### 프롬프트 팁
| 하고 싶은 것 | 이렇게 말하세요 |
|-------------|---------------|
| 프로젝트 등록 | "이 디렉토리를 새 프로젝트로 등록해줘" |
| 작업 계획 | "X 기능 플랜 세우고 클라켓에 등록해줘" |
| 작업 생성 | "X에 대한 태스크 등록하고 작업 시작해" |
| 상태 확인 | "현재 사이클 진행 상황 보여줘" |
| 작업 리뷰 | "지난 스프린트에서 뭘 했어?" |
| 과거 결정 검색 | "위키에서 인증 설계 결정 찾아줘" |
| 작업 완료 | "현재 태스크 완료 처리해" |
## 개발
각 컴포넌트는 `clawket` 조직의 독립 레포에 존재합니다.
```bash
# CLI (+ 내장 MCP)
cd cli && cargo build --release
./target/release/clawket mcp # 로컬에서 내장 MCP stdio 실행
# 데몬
cd daemon && cargo build --release
./target/release/clawketd
# 웹 대시보드
cd web && pnpm install && pnpm dev
```
## 라이선스
MIT