KittyClaw

KittyClaw

kittyclaw.dev · Get early access

KittyClaw is a local control plane for software work performed by AI agents. Submit a software ticket, watch it move across the live board, read the run that changed the code, inspect its verification evidence, and make the final release decision yourself.

The product proves three things in one journey: a live board, a readable run, and human validation before external release. New boards start with Backlog, Todo, InProgress, Blocked, Scheduled, Review, and Done (columns remain customizable). Runs can use Claude Code, OpenAI Codex, Grok Build, or a local Ollama model.

Follow the guided five-minute demo to repeat the journey with a realistic software ticket. The companion activation test protocol measures whether qualified trial users reach their first run within ten minutes.

A project can be split into independently named pipelines whose stable identities survive renames. Columns can own generic processors with persistent memory, reusable project skills, ordered ticket selection, durable retries, and switch-like routing to columns in any pipeline. Right-click a column and choose Configure column to edit its name, color, role, position, ticket guidance, processor, and routing without losing the visual context of the board. Tickets in Waiting or OwnerAction columns always show a prominent contextual block between their description and activity, explaining whether the owner must comment or move the ticket to a specific validation/refusal column, or whether KittyClaw will resume it automatically. Columns can also be inserted between existing lanes or added at the end directly from the Kanban; the Workflows page remains the global pipeline-and-skills overview. Execution state is separate from business columns, so an InProgress column is optional. Recurring work uses column scheduled tasks. Agents run through Claude Code, OpenAI Codex, Grok Build, Mistral Vibe, or a local Ollama model while their output streams into the app.

Each processor is versioned with its project in .agents/processors/column- /processor.json. This authoritative definition contains its mission, explicit prompt, model, skills, ticket ordering, retry policy, and routing. SQLite keeps only a synchronized runtime projection and execution state. Persistent lessons live beside the definition under .agents/processors/column- /memory/MEMORY.md.

Tech Stack

• .NET 10 / Blazor Server (interactive SSR)
• SQLite via Entity Framework Core (one DB per project)
• OpenAPI with auto-generated Markdown docs
• Agent execution: at least one supported CLI — [Claude Code CLI](https://docs.claude.com/en/docs/claude-code/overview), [OpenAI Codex CLI](docs/codex-cli.md), [Grok Build](docs/grok-build.md), or [Mistral Vibe](docs/mistral-vibe.md). [Ollama](https://ollama.com) and [DeepSeek V4](docs/deepseek.md) are supported through Claude Code. See the consolidated [agent-provider installation guide](docs/agent-providers.md).
• Optional for repository initialization, worktree integrations, and agent commits: [Git](https://git-scm.com/downloads)

Getting Started

Windows installer

Download Ekioo.KittyClaw-win-Setup.exe from the latest release when that release includes the Windows installer. Run it, acknowledge the installation confirmation, then launch KittyClaw from its desktop or Start-menu shortcut. The Windows x64 installer includes the .NET, ASP.NET Core, and Windows Desktop runtimes; no SDK or separate .NET installation is required. Agent CLIs still need to be installed and authenticated separately (see the provider guide).

KittyClaw opens in your browser and stays in the notification area. Double-click its icon to open it again, or choose Quit KittyClaw from its menu to stop it. Installation is per user under %LOCALAPPDATA%/Ekioo.KittyClaw; project data stays in %APPDATA%/KittyClaw.

The update banner offers Download update, followed by Update and restart. Downloads do not interrupt work; installation is blocked while agent work or tracked finalization is active. See Windows packaging and updates for build and release details.

Run from source

Prerequisites

• .NET 10 SDK
• At least one agent CLI on your PATH: Claude Code (claude), OpenAI Codex (codex), Grok Build (grok), or Mistral Vibe (vibe). Local-model and DeepSeek execution use Claude Code as their transport; DeepSeek additionally requires DEEPSEEK_API_KEY in the project's secure vault.
• Optional: Git (git on your PATH) for repository initialization, worktree integrations, and agent commits
• Optional: Rust Token Killer (RTK) (rtk on your PATH) for explicit per-project shell-output optimization. KittyClaw never installs or configures it automatically and forces its telemetry off for opted-in runs.

On first launch, the onboarding popup checks Git and every supported provider CLI using the same resolved executable paths as dispatch: Claude Code (claude / KITTYCLAW_CLAUDE_BIN), OpenAI Codex (codex / KITTYCLAW_CODEX_BIN), Grok Build (grok, ~/.grok/bin, or KITTYCLAW_GROK_BIN), and Mistral Vibe (vibe / KITTYCLAW_MISTRAL_BIN). It also reports optional Ollama availability. Any one agent provider is sufficient, failed or timed-out probes remain non-blocking, and Git-dependent features still require Git.

Run

From the repo root:

run.bat        (Windows)

./run.sh (macOS / Linux)

Both wrap dotnet watch --project KittyClaw.Web --non-interactive and serve the app at http://localhost:5230 with hot reload enabled.

Creating a project

From the home page, select Create a project, enter a name, and choose its workspace. The built-in folder browser works on Windows, macOS, and Linux without opening a native system dialog behind the browser. It exposes the home directory, mounted drives or filesystem roots, breadcrumbs, parent navigation, and direct path entry. You can also type an absolute path and create the folder when it does not exist.

Click Initialize to:

1. Create the project registry entry + per-project SQLite DB.
2. Copy the project template from ProjectTemplate/ (preamble.md, {agent}/SKILL.md, {agent}/memory/MEMORY.md index, memory-consolidation.md, agent-budget.json, CLAUDE.md) into the workspace — agent files under /.agents/, CLAUDE.md at the workspace root.
3. Run git init if the workspace is not already a git repo (skipped if git isn't installed).
4. Create a member for each agent slug found in the template.
5. Open the project setup wizard.

The setup wizard analyzes an existing workspace and proposes distinct pipelines, columns, human hand-offs, processors, routing, and schedules. For an empty folder it first asks a few questions about the project's purpose, deliverables, human decisions, and recurring work. Proposals are graphical: you can add or remove pipelines, review each pipeline's columns, refine a step with a prompt, and move backward before approval. Nothing is created during this preparation; Create the workflow applies and verifies the approved plan, then opens the board.

Existing pipelines can be refined through Edit with assistant. The legacy automation engine and its migration wizard are retired.

The workspace folder itself is never deleted by KittyClaw, even when you delete a project.

Data Storage

All KittyClaw data is stored locally in %APPDATA%/KittyClaw/:

• registry.db — project registry
• projects/{slug}.db — per-project database (tickets, comments, labels, columns, members)
• uploads/ — uploaded images
• runs/{runId}.json — agent run snapshots (events, status, exit code)
• settings.json — language + onboarding flag

Per-project agent state lives in the workspace: /.agents/{agent}/memory/ (scored MEMORY.md index + per-topic lesson files), /.agents/channel/ (session state), etc.

Project Structure

Architecture

Per-feature architecture documentation lives under docs/. Start with pipeline and column processing for the multi-pipeline model, or docs/index.md for the complete architecture map.

API

All endpoints are under /api. The documentation is auto-generated from the live OpenAPI spec:

• Human-readable Markdown: GET http://localhost:5230/api/docs
• Machine-readable JSON: GET http://localhost:5230/openapi/v1.json

MCP server

KittyClaw can expose an embedded MCP endpoint at http://localhost:5230/mcp (Streamable HTTP), so MCP clients can manage projects, tickets and acceptance criteria, configure column workflows and scheduled tasks, supervise agent runs, and handle approvals and worktree integrations. Open Settings from the home page and enable the MCP server, then hook it up to Claude Code with:

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

The server exposes 73 tools: nine board and acceptance-criteria tools plus 64 management and observability tools. Reconnect clients after upgrading to refresh their tool catalogue. The endpoint is disabled by default, can be toggled without restarting KittyClaw, and uses the same localhost trust boundary as the REST API. See the complete tool catalogue and operation conventions.

For AI Agents

This app is designed to be operated by AI agents through its REST API. Here's how to get started:

1. Read the live API docs at http://localhost:5230/api/docs — every endpoint, request/response example, and schema, always up to date with the running server.
2. Identify yourself — author is required on every mutating endpoint; omitting it returns HTTP 400. Use your plain agent name (e.g. "programmer", "groomer"). The human user is "owner".
3. Discover the board — call GET /api/projects first, then GET /api/projects/{slug}/columns to learn the workflow stages and GET /api/projects/{slug}/members for assignable members.
4. Use the right status — ticket statuses must match existing column names. Fetch columns before moving tickets.
5. Track your work — add comments on tickets to explain what you did or what you need. Use @mentions to notify members, #id to reference tickets in the same project, and #{slug}:{id} to reference tickets in another project.
6. Labels & priority — use GET /api/projects/{slug}/labels to discover available labels, and set priority to Idea, NiceToHave, Required, or Critical.
7. Check mentions — call `GET /api/projects/{