KittyClaw

KittyClaw는 AI 에이전트가 수행하는 소프트웨어 작업을 위한 로컬 제어 플레인입니다. 소프트웨어 티켓을 제출하고, 라이브 보드에서 이동하는 것을 지켜보고, 코드를 변경한 실행(run)을 읽고, 검증 증거를 검사한 후 최종 릴리스 결정을 직접 내리세요.

이 제품은 하나의 여정에서 세 가지를 입증합니다: 라이브 보드, 읽을 수 있는 실행, 외부 릴리스 전 인간 검증. 새 보드는 Backlog, Todo, InProgress, Blocked, Scheduled, Review, Done으로 시작합니다(열은 사용자 지정 가능). 실행은 Claude Code, OpenAI Codex, Grok Build 또는 로컬 Ollama 모델을 사용할 수 있습니다.

5분 가이드 데모를 따라 현실적인 소프트웨어 티켓으로 여정을 반복하세요. 동반 활성화 테스트 프로토콜은 자격을 갖춘 평가판 사용자가 10분 이내에 첫 실행에 도달하는지 측정합니다.

프로젝트는 독립적으로 명명된 파이프라인으로 분할할 수 있으며, 안정적인 정체성은 이름 변경에도 유지됩니다. 열은 지속 메모리, 재사용 가능한 프로젝트 스킬, 정렬된 티켓 선택, 내구성 있는 재시도, 그리고 모든 파이프라인의 열로의 스위치형 라우팅을 갖춘 일반 프로세서를 소유할 수 있습니다. 열을 마우스 오른쪽 버튼으로 클릭하고 열 구성을 선택하여 보드의 시각적 맥락을 잃지 않고 이름, 색상, 역할, 위치, 티켓 지침, 프로세서 및 라우팅을 편집하세요. Waiting 또는 OwnerAction 열의 티켓은 설명과 활동 사이에 항상 눈에 띄는 컨텍스트 블록을 표시하여, 소유자가 댓글을 달거나 티켓을 특정 검증/거부 열로 이동해야 하는지, 아니면 KittyClaw가 자동으로 재개할지 설명합니다. 열은 기존 레인 사이에 삽입하거나 Kanban에서 직접 끝에 추가할 수 있습니다. Workflows 페이지는 전역 파이프라인 및 스킬 개요로 유지됩니다. 실행 상태는 비즈니스 열과 분리되어 있으므로 InProgress 열은 선택 사항입니다. 레거시 AutomationEngine은 트리거 기반 규칙, cron/간격 작업 및 이전 버전과의 호환성을 위해 계속 사용할 수 있습니다. 에이전트는 Claude Code, OpenAI Codex, Grok Build, Mistral Vibe 또는 로컬 Ollama 모델을 통해 실행되며 출력은 앱으로 스트리밍됩니다.

각 프로세서는 .agents/processors/column-<id>/processor.json에서 프로젝트와 함께 버전 관리됩니다. 이 권위 있는 정의에는 미션, 명시적 프롬프트, 모델, 스킬, 티켓 순서, 재시도 정책 및 라우팅이 포함됩니다. SQLite는 동기화된 런타임 프로젝션과 실행 상태만 유지합니다. 지속적인 교훈은 정의 옆의 .agents/processors/column-<id>/memory/MEMORY.md에 저장됩니다.

Tech Stack

• .NET 10 / Blazor Server (대화형 SSR)

• SQLite via Entity Framework Core (프로젝트당 하나의 DB)

• OpenAPI with auto-generated Markdown docs (자동 생성된 Markdown 문서 포함)

• 에이전트 실행: 지원되는 CLI 중 하나 이상 — Claude Code CLI, OpenAI Codex CLI, Grok Build, 또는 Mistral Vibe. Ollama 는 Claude Code CLI를 통한 로컬 모델에도 지원됩니다 (로컬 모델 설정).

• 저장소 초기화, Git 인식 자동화 및 에이전트 커밋을 위한 선택 사항: Git

Getting Started

Prerequisites

• .NET 10 SDK

• PATH에 에이전트 CLI가 하나 이상 있어야 합니다: Claude Code (claude), OpenAI Codex (codex), Grok Build (grok), 또는 Mistral Vibe (vibe). 로컬 모델 실행에는 Claude Code CLI와 연결 가능한 Ollama 서버가 모두 필요합니다.

• 선택 사항: Git (PATH의 git) - 저장소 초기화, Git 인식 자동화 및 에이전트 커밋용

첫 실행 시 온보딩 팝업은 디스패치와 동일한 해석된 실행 파일 경로를 사용하여 Git 및 지원되는 모든 공급자 CLI를 확인합니다: Claude Code (claude / KITTYCLAW_CLAUDE_BIN), OpenAI Codex (codex / KITTYCLAW_CODEX_BIN), Grok Build (grok, ~/.grok/bin, 또는 KITTYCLAW_GROK_BIN), Mistral Vibe (vibe / KITTYCLAW_MISTRAL_BIN). 또한 선택적 Ollama 사용 가능 여부를 보고합니다. 에이전트 공급자 하나면 충분하며, 실패하거나 시간 초과된 프로브는 비차단으로 유지되고, Git 종속 기능에는 여전히 Git이 필요합니다.

Run

저장소 루트에서:

run.bat        (Windows)
./run.sh       (macOS / Linux)

둘 다 dotnet watch --project KittyClaw.Web --non-interactive를 감싸고 핫 리로드가 활성화된 상태로 http://localhost:5230 에서 앱을 제공합니다.

Creating a project

홈 페이지에서 프로젝트 만들기를 선택하고 이름을 입력한 후 작업 영역을 선택하세요. 내장 폴더 브라우저는 Windows, macOS, Linux에서 브라우저 뒤에 네이티브 시스템 대화 상자를 열지 않고 작동합니다. 홈 디렉터리, 마운트된 드라이브 또는 파일 시스템 루트, 이동 경로, 상위 탐색 및 직접 경로 입력을 제공합니다. 절대 경로를 입력하고 폴더가 없으면 만들 수도 있습니다.

초기화를 클릭하여:

1. 프로젝트 레지스트리 항목 + 프로젝트별 SQLite DB를 생성합니다.

2. ProjectTemplate/에서 프로젝트 템플릿(preamble.md, {agent}/SKILL.md, {agent}/memory/MEMORY.md 인덱스, memory-consolidation.md, automations.json, CLAUDE.md)을 작업 영역으로 복사합니다 — 에이전트 파일은 <workspace>/.agents/ 아래, CLAUDE.md는 작업 영역 루트에.

3. 작업 영역이 이미 git 저장소가 아닌 경우 git init을 실행합니다(git이 설치되지 않은 경우 건너뜀).

4. 템플릿에서 찾은 각 에이전트 슬러그에 대한 멤버를 생성합니다.

5. 프로젝트 설정 마법사를 엽니다.

설정 마법사는 기존 작업 영역을 분석하고 별도의 파이프라인, 열, 인간 핸드오프, 프로세서, 라우팅 및 일정을 제안합니다. 빈 폴더의 경우 먼저 프로젝트의 목적, 산출물, 인간 결정 및 반복 작업에 대한 몇 가지 질문을 합니다. 제안은 그래픽으로 표시됩니다: 파이프라인을 추가하거나 제거하고, 각 파이프라인의 열을 검토하고, 프롬프트로 단계를 개선하고, 승인 전에 뒤로 이동할 수 있습니다. 이 준비 중에는 아무것도 생성되지 않습니다. 워크플로 만들기는 승인된 계획을 적용하고 검증한 다음 보드를 엽니다.

이 새 프로젝트 설정은 의도적으로 레거시 보드 마이그레이션 마법사와 분리되어 있습니다. 마이그레이션 용어와 레거시 자동화 정리는 기존 자동화 기반 보드를 변환해야 할 때만 표시됩니다.

작업 영역 폴더 자체는 프로젝트를 삭제하더라도 KittyClaw에 의해 삭제되지 않습니다.

Data Storage

모든 KittyClaw 데이터는 %APPDATA%/KittyClaw/에 로컬로 저장됩니다:

• registry.db — 프로젝트 레지스트리

• projects/{slug}.db — 프로젝트별 데이터베이스(티켓, 댓글, 라벨, 열, 멤버)

• uploads/ — 업로드된 이미지

• runs/{runId}.json — 에이전트 실행 스냅샷(이벤트, 상태, 종료 코드)

• settings.json — 언어 + 온보딩 플래그

프로젝트별 에이전트 상태는 작업 영역에 있습니다: <workspace>/.agents/{agent}/memory/ (점수가 매겨진 MEMORY.md 인덱스 + 주제별 교훈 파일), <workspace>/.agents/channel/ (세션 상태) 등.

Project Structure

Architecture

기능별 아키텍처 문서는 doc/ 아래에 있습니다. 다중 파이프라인 모델은 파이프라인 및 열 처리에서 시작하거나, 전체 아키텍처 맵은 doc/index.md를 참조하세요.

API

모든 엔드포인트는 /api 아래에 있습니다. 문서는 라이브 OpenAPI 사양에서 자동 생성됩니다:

• 사람이 읽을 수 있는 Markdown: GET http://localhost:5230/api/docs

• 기계가 읽을 수 있는 JSON: GET http://localhost:5230/openapi/v1.json

MCP server

KittyClaw는 http://localhost:5230/mcp(Streamable HTTP)에 임베디드 MCP 엔드포인트를 노출할 수 있으므로, 모든 MCP 클라이언트가 REST API를 건드리지 않고 보드를 구동할 수 있습니다 — 프로젝트 나열, 티켓 생성 및 이동, 댓글, 보드 레이아웃 읽기. KittyClaw를 시작하기 전에 KITTYCLAW_MCP_ENABLED=1을 설정한 다음, 다음으로 Claude Code에 연결하세요:

claude mcp add --transport http kittyclaw http://localhost:5230/mcp

v1에는 7개의 도구가 포함됩니다: list_projects, list_tickets, get_ticket, create_ticket, comment_ticket, move_ticket, board_overview. 엔드포인트는 기본적으로 비활성화되어 있으며 REST API와 동일한 localhost 신뢰 경계를 사용합니다. 자세한 내용은 doc/mcp.md를 참조하세요.

For AI Agents

이 앱은 REST API를 통해 AI 에이전트가 운영하도록 설계되었습니다. 시작하는 방법은 다음과 같습니다:

1. 라이브 API 문서 읽기 — http://localhost:5230/api/docs에서 모든 엔드포인트, 요청/응답 예제 및 스키마를 확인하세요. 실행 중인 서버와 항상 최신 상태입니다.

2. 자신을 식별하세요 — author는 모든 변경 엔드포인트에서 필수입니다. 생략하면 HTTP 400이 반환됩니다. 일반 에이전트 이름(예: "programmer", "groomer")을 사용하세요. 인간 사용자는 "owner"입니다.

3. 보드 탐색 — 먼저 GET /api/projects를 호출한 다음 GET /api/projects/{slug}/columns로 워크플로 단계를, GET /api/projects/{slug}/members로 할당 가능한 멤버를 확인하세요.

4. 올바른 상태 사용 — 티켓 상태는 기존 열 이름과 일치해야 합니다. 티켓을 이동하기 전에 열을 가져오세요.

5. 작업 추적 — 티켓에 댓글을 추가하여 수행한 작업이나 필요한 사항을 설명하세요. @멘션으로 멤버에게 알리고, #id로 같은 프로젝트의 티켓을, #{slug}:{id}로 다른 프로젝트의 티켓을 참조하세요.

6. 라벨 및 우선순위 — GET /api/projects/{slug}/labels로 사용 가능한 라벨을 확인하고, 우선순위를 Idea, NiceToHave, Required 또는 Critical로 설정하세요.

7. 멘션 확인 — GET /api/projects/{slug}/mentions/{your-handle}을 호출하여 자신을 언급한 티켓을 찾으세요.

8. 하위 티켓 — 티켓 생성 시 parentId를 설정하여 하위 티켓으로 만드세요. PUT /api/projects/{slug}/tickets/{id}/parent로 부모를 변경하거나 DELETE로 분리하세요. ?parentId={id}로 하위 티켓을 나열하세요.

9. 프로젝트 간 전송 — 대상 프로젝트에 호환되는 열, 담당자 및 라벨이 있는지 확인한 후에만 POST /api/projects/{slug}/tickets/{id}/transfer를 사용하세요. 이 작업은 티켓 트리와 기록을 보존하거나 어느 프로젝트도 변경하지 않고 전송을 거부합니다. 무손실 티켓 전송을 참조하세요.

규칙

• 작성자 형식: 사람 사용자는 "owner", AI 에이전트는 일반 에이전트 이름(예: "programmer")

• 우선순위 수준: Idea, NiceToHave, Required, Critical

• 기본 열: Backlog

UI 기능

• 첫 실행 시 Git, Claude Code, OpenAI Codex, Grok Build, Mistral Vibe, Ollama를 확인하는 온보딩 팝업

• 루트, 이동 경로, 직접 경로 입력, 폴더 생성을 지원하는 크로스 플랫폼 앱 내 작업 공간 브라우저

• 작업 공간을 분석하고 워크플로우를 생성하기 전에 편집 가능한 파이프라인과 열을 제안하는 안내형 새 프로젝트 설정

• 완료된 티켓을 보존하고 교체된 자동화를 검증 후에만 폐기하는 안내형 레거시 보드 마이그레이션

• 프로젝트 카드와 칸반 스윔레인이 있는 통합 멀티 프로젝트 홈

• 프로세서 라우팅에 따라 허용/금지 드롭 대상이 시각적으로 구분되는 멀티 파이프라인 칸반

• 구조, 역할, 담당자 가이드, 프로세서, 정렬된 작업, 예약 작업, 라우팅을 위한 컨텍스트 열 편집기

• 자유 드래그 타일(Markdown, KPI, 차트, Heatmap, Timeline 등), AI 채팅 기반 타일 생성, LLM 프롬프트를 통한 자동 새로고침을 지원하는 사용자 지정 대시보드 보기

• 댓글과 활동 타임라인이 있는 티켓 상세 패널

• 실시간 에이전트 실행 서랍(공급자 출력의 SSE 스트림, 조종 + 중지 컨트롤)

• 에이전트에게 임시 프롬프트를 보내는 새 지시사항 채팅 서랍

• @mention, #id, #{slug}:{id} 크로스 프로젝트 티켓 참조를 지원하는 Markdown 렌더링

• 고급 검색 구문: #42, @owner, >date, priority:critical, label:bug, by:owner

• 부모/자식 관계와 진행 상황 추적이 있는 하위 티켓

• REST API를 통한 프로젝트 간 무손실, 원자적 티켓 트리 전송

• 보드에서 직접 열 관리(삽입, 복제, 재정렬, 구성, 읽음 표시)

• 라벨 및 멤버 관리

• 설명과 댓글의 이미지 업로드

• 로컬 모델 지원(Ollama): 모델 자동 검색이 포함된 프로젝트별 기본 URL, 멤버별 기본 모델, .agents/automations.json의 작업별 구성

• Claude Code, OpenAI Codex, Grok Build, Mistral Vibe 또는 Ollama를 통한 공급자 인식 디스패치(대화 핸드오프 및 사용 불가 모델 폴백 포함)

대시보드

각 프로젝트에는 칸반 보드와 함께 사용자 지정 가능한 대시보드 보기가 있습니다. 타일은 자유롭게 드래그할 수 있고, 일정에 따라 자동 새로고침되며, 앱 내 AI 채팅 패널에서 생성하거나 편집할 수 있습니다. 에이전트가 타일의 폴더를 대신 작성해 줍니다.

타일 유형

폴더 구조

각 타일은 프로젝트 작업 공간의 .dashboard/ 아래에 자체 폴더에 있습니다:

.dashboard/
  <tile-slug>/
    tile.yaml        # template, title, refresh schedule, prompt
    script.ps1       # optional refresh script (or script.sh, script.py, …)
    output.json      # last refresh output consumed by the template

tile.yaml 주요 필드

• template — 위 표의 ID 중 하나.

• title — 타일 헤더에 표시되는 이름.

• refresh — 주기적 새로고침 간격(예: 5m, 1h).

• refreshAt — cron 스타일의 시간대별 새로고침(refresh의 대안).

• prompt — output.json을 (재)생성할 때 에이전트로 전송되는 지시사항.

타일은 대시보드의 AI 채팅 패널에서 원하는 내용을 설명하여 만들 수 있습니다. 에이전트가 템플릿을 선택하고, tile.yaml을 작성하고, 새로고침 스크립트를 생성하고, 초기 output.json을 생성합니다.

비용 보고

비용 페이지는 에이전트 사용량의 캐시된 프로젝트별 보기를 제공하므로 실행 기록이 길어도 보고서를 즉시 열 수 있습니다. 날짜 사전 설정으로 일반적인 기간을 빠르게 선택할 수 있으며, 프로젝트, 파이프라인, 모델 필터를 결합할 수 있습니다. 파이프라인 선택은 선택한 프로젝트를 자동으로 따릅니다. 일별 차트에서 측정 비용과 추정 비용을 구분하는 범례가 표시됩니다.

자동화 모델

• 트리거: interval, ticketInColumn, statusChange, subTicketStatus, ticketCommentAdded, gitCommit, boardIdle, agentInactivity.

• 조건: ticketInColumn, ticketCountInColumn, fieldLength, priority, labels, assignedTo, hasParent, allSubTicketsInStatus, ticketAge.

• 작업: runAgent, moveTicketStatus, setLabels, assignTicket, addComment, consolidateAgentMemory, commitAgentMemory, executePowerShell, createTicket, httpRequest(아웃바운드 웹훅, allowLocalTargets가 아닌 이상 루프백/링크-로컬 대상 차단).

• runAgent.agent / runAgent.concurrencyGroup의 {assignee} 자리 표시자는 실행 중인 티켓의 assignedTo에서 확인됩니다.

• 표준 실행 후 체인: runAgent → consolidateAgentMemory(에이전트의 memory/ 인덱스와 주제 파일을 정리하는 집중 Claude 패스) → commitAgentMemory(결과 커밋).

텔레메트리

KittyClaw는 하루에 익명 하트비트 하나를 자체 호스팅 친화적 분석 서비스(Umami)로 전송하여 실행 중인 인스턴스 수와 실제 사용 중인 버전을 파악합니다. 페이로드에는 정확히 세 개의 필드만 포함되며 그 외에는 아무것도 없습니다:

• 임의의 인스턴스 ID(첫 실행 시 로컬에서 생성된 GUID — 사용자, 머신, 프로젝트 데이터와 연결되지 않음)

• KittyClaw 버전

• OS 계열(Windows / macOS / Linux)

티켓 내용, 프로젝트 이름, 호스트 이름, 사용 세부 정보는 절대 전송되지 않습니다. 실패는 자동으로 무시되며 앱에 영향을 주지 않습니다. 개발 인스턴스는 텔레메트리를 전송하지 않습니다.

라이선스

KittyClaw는 AGPL-3.0-or-later 라이선스로 배포됩니다. 자체 호스팅 및 개인 사용은 제한이 없습니다. 수정 버전을 배포하거나 네트워크 서비스로 제공하는 경우 동일한 라이선스로 소스를 공개해야 합니다.

AGPL §7에 따른 추가 조건(전체 텍스트는 NOTICE.md 참조): 파생 저작물은 KittyClaw 저작자 표시를 유지해야 하며(앱 내 법적 고지 및 README의 "KittyClaw 기반" 문구), 출처를 허위로 표시해서는 안 되며, KittyClaw 이름 또는 로고에 대한 권리를 받지 않습니다.

AGPL이 적용되지 않는 두 가지 사항(NOTICE.md 참조):

• 사용자의 프로젝트: KittyClaw가 작업 공간에 복사하는 템플릿 파일(.agents/, CLAUDE.md 등)은 추가로 MIT 라이선스가 적용되며, 앱이 사용자를 위해 생성하는 모든 것(티켓, 로그, 에이전트 커밋 등)은 라이선스 제한 없이 사용자의 소유입니다. KittyClaw로 프로젝트를 관리한다고 해서 해당 프로젝트가 AGPL에 적용되지는 않습니다.

• 과거 버전: v0.11까지의 버전은 MIT 라이선스로 배포되었으며 해당 조건으로 계속 사용할 수 있습니다.

더 많은 프로젝트 및 연락처

→ 사이트 + 데모: kittyclaw.dev

**ekioo.com**에서 제 다른 프로젝트도 확인해 보세요.

X에서 팔로우하세요: @DamienHOFFSCHIR