Kawa Code User Manual

Welcome to Kawa Code, a real-time AI-enabled collaboration platform.

Table of Contents

1. Overview
2. Core Concepts
3. System Requirements
4. Installation
5. AI Provider Configuration
6. Kawa Code Extensions
7. Getting Started
8. Setting Up CLAUDE.md
9. Troubleshooting

Overview

Kawa Code ecosystem consists of several interconnected components:

Architecture

Editor (VSCode/Emacs/Vim)
    ↓ Unix sockets / Named pipes
Kawa Code (Desktop App)
    ↓ HTTP/SSE
Kawa API (Cloud)

Data Storage & Sync

Kawa Code stores data locally first, then syncs to the cloud for team collaboration:

Key features:

• Local-first: All operations work offline; data syncs when connected
• Zero-knowledge encryption: All code diffs and intent block content are encrypted client-side before upload
• Automatic team sync: Team members' data is downloaded and decrypted locally
• Conflict detection: Overlapping work is detected before you commit

Core Concepts

These four ideas underpin everything Kawa Code does. Understanding them makes the rest of the manual — and the product itself — much easier to reason about.

Diff-Aware Collaboration

Kawa Code continuously tracks the live state of every file open in your editor and computes intersections — locations where your working version diverges from a teammate's. These are not git diffs: they reflect uncommitted, in-progress work that git cannot see. When you and a colleague are both editing the same function, Kawa Code highlights the overlap in your editor before either of you has saved or committed, giving you a chance to coordinate before a conflict is born.

Swarm Authentication

Kawa Code authenticates team members against private repositories without ever asking for a GitHub or GitLab token. Instead, it uses commit SHAs that only people with actual repository access can produce — if you can name the latest commit on a branch, you demonstrably have read access to that repo. This creates a self-refreshing "access pool" that updates naturally as the team pushes new commits. You'll be asked to provide a commit SHA when you first connect a repository; after that, authentication is handled automatically.

Zero-Knowledge Encryption

Every code diff and intent code block that Kawa Code uploads to the cloud is encrypted on your machine before it leaves, using a key derived from your repository's first commit SHA and origin URL — neither of which the server ever sees. The Kawa API stores ciphertext it cannot read; only team members with access to the same repository can decrypt each other's diffs. Intent and decision metadata travels as structured plaintext (to support search and translation features), but actual code content never does.

Temporal Memory Layer

Kawa Code maintains a persistent, queryable record of what your team is building and why. Intents capture the current task and associate it with the specific lines of code being changed. Decisions record the reasoning behind architectural choices as they happen — why one approach was chosen over another, what constraints ruled out alternatives. Together they form a team memory that survives session boundaries: future contributors can understand not just what the code does, but why it was built that way. When used with the MCP server, Claude Code reads this memory automatically at the start of each session.

System Requirements

All Platforms

• Git 2.25 or higher
• Internet connection for cloud sync

Kawa Code Desktop App

• macOS: 10.15 (Catalina) or higher
• Windows: Windows 10 or higher
• Linux: Ubuntu 20.04+ or equivalent

Editor Extensions

• VSCode: Version 1.105.0 or higher
• Emacs: Version 26.1 or higher (27.1+ for tab-bar features)
• Vim: 8.2+ with Python3 support, or Neovim 0.5.0+

MCP Server (for Claude Code)

• Node.js 18.0.0 or higher
• Claude Code CLI installed

Installation

1. Kawa Code Desktop App (Kawa Code)

The Kawa Code main application, code named Kawa Code, is the core desktop application that must be running for all other components to work.

Download the latest release from kawacode.ai:

• macOS: KawaCode-x.x.x.dmg
• Windows: Install from Microsoft Store
• Linux: KawaCode-x.x.x.AppImage or .deb

2. Editor Extensions

Open your IDE (Visual Studio Code, emacs) and install the Kawa Code extension. All extensions require Kawa Code to be running.

3. MCP Server for Claude Code

The MCP (Model Context Protocol) server enables Claude Code to track development intents and integrate with Kawa Code's collaboration features.

Prerequisites:

• Node.js 18.0.0 or higher
• Claude Code CLI installed
• Kawa Code running

Installation:

cd kawa.mcp

# Install dependencies
npm install

# Build
npm run build

Configure Claude Code:

There are three ways to make the MCP server available to Claude Code. Choose the one that fits your setup:

Option A: Project-level config (recommended for teams)

Create a .mcp.json file in your project's root directory:

{
  "mcpServers": {
    "kawa-intents": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/kawa.mcp/build/index.js"]
    }
  }
}

Commit this file to git. All team members who clone the repo will have the MCP server available automatically (Claude Code will prompt them to approve it on first use).

Option B: User-level config (available across all your projects)

Run from any directory:

claude mcp add --transport stdio kawa-intents --scope user -- node /absolute/path/to/kawa.mcp/build/index.js

This makes the kawa-intents server available in every project you open with Claude Code.

Option C: Single-project config (private, one project only)

Run from inside the project directory:

claude mcp add --transport stdio kawa-intents -- node /absolute/path/to/kawa.mcp/build/index.js

This stores the config in ~/.claude.json under the project's path. It only works when Claude Code is launched from that specific directory.

Replace /absolute/path/to/kawa.mcp with the actual path to your kawa.mcp directory in all examples above.

Verify Installation:

Start a new Claude Code session in your project directory, then run /mcp. You should see kawa-intents listed with tools available.

Available MCP Tools:

AI Provider Configuration

Kawa Code uses a large language model for features like commit-history inference. You bring your own API key — the key never leaves your machine, and you pay the provider directly. There is no Kawa Code-side LLM billing.

Choosing a provider

Open Settings in Kawa Code. Under AI Provider — global default, choose:

• Anthropic — calls go directly to api.anthropic.com using your ANTHROPIC_API_KEY. Get one at console.anthropic.com.
• OpenRouter — calls go to openrouter.ai, which forwards them to Anthropic (or any other supported model). Pay-as-you-go billing across many providers; useful when you want to control costs by routing high-volume tasks to cheaper models. Get a key at openrouter.ai/keys.

Both keys can be saved at the same time — the AI Provider radio decides which one is used by default. The keys are stored encrypted in ~/.kawa-code/.storage.caw and never sent to the Kawa Code servers.

Saving keys

Paste each key into its field and click Save. The Save button only appears once you've typed something into the field, and disappears again once the key is stored — a configured key shows the placeholder "Key already configured. Replace if needed...".

Where the LLM is used today

Today, the LLM is called by commit history inference — a two-pass pipeline that groups your git commits into stories, then extracts the decisions and lessons recorded along the way. Whichever provider is selected globally handles the whole pipeline.

More LLM-using features (decision distillation, conflict detection, etc.) are on the way; when they ship, the Settings page will gain an Advanced section letting you route individual features to different providers — useful if you want to keep Anthropic Sonnet for long-form analysis but send high-volume classification work to a cheaper OpenRouter model.

Switching providers later

Switching the global provider requires the corresponding key to be saved first — Settings will show an inline error if you select a provider whose key is missing. This prevents you from ending up in a state where every LLM call returns 401.

Kawa Code Extensions

Kawa Code supports standalone extensions — separate processes that add functionality beyond what the built-in Kawa Code provides. Extensions communicate with Kawa Code over stdin/stdout using the Kawa IPC protocol, and can optionally provide UI components that appear inside Kawa Code's UI.

The kawa.i18n (code translation) extension ships as the first standalone extension. More extensions may be available over time, or you can build your own.

Before you start — two things to know:

• Extensions use your Claude Code authentication, not an API key. You do not need to configure an Anthropic API key in Kawa Code Settings for extensions to work. The kawa.i18n extension calls the locally-installed claude CLI, which signs in through your existing Claude Code login. (The Anthropic API key field in Settings is used only by Kawa Code's own LLM features such as inference and decision distillation — not by extensions.)
• Extensions are not available on the Mac App Store version of Kawa Code. Apple's App Store sandbox prevents Kawa Code from spawning the subprocesses that extensions run in. To use extensions on macOS, install Kawa Code from the .dmg at kawacode.ai. On Windows, install Kawa Code from the Microsoft Store — extensions work there as expected.

How Extensions Work

Editor (VSCode/Emacs/Vim)
    ↓ Huginn IPC
Kawa Code
    ├─ Gardener (built-in)          ← handles: auth, repo, sync, branch, context, user
    └─ Extensions (standalone)      ← handles: custom domains (e.g., i18n)
        ↓ stdin/stdout (JSON lines)
Extension Process

When Kawa Code starts, it:

1. Scans ~/.kawa-code/extensions/ for subdirectories containing an extension.json manifest
2. Validates each manifest
3. Sorts extensions by dependency order
4. Spawns each extension as a child process
5. Routes IPC messages to extensions based on their domain subscriptions

Installing an Extension

From a Release Binary

1. Download the extension archive for your platform
2. Extract it into ~/.kawa-code/extensions/ (or link it there):

mkdir -p ~/.kawa-code/extensions
# Extract so the structure is:
# ~/.kawa-code/extensions/<extension-name>/
#   ├── extension.json
#   ├── binaries/
#   │   └── <binary-for-your-platform>
#   └── ui/dist/  (optional)

3. Restart Kawa Code — the extension is auto-discovered on startup

Building from Source

If you want to build an extension from source (e.g., for development or a platform without prebuilt binaries), here's how using kawa.i18n as an example.

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Build Steps

cd kawa.i18n

# Install dependencies
npm install

# Build for your platform (choose one):
npm run build:macos      # macOS Intel/Apple Silicon
npm run build:linux      # Linux x64
npm run build:windows    # Windows x64

This compiles TypeScript, then uses pkg to bundle everything into a standalone binary under binaries/.

Install After Building

Option A: Symlink for development (changes to source are reflected immediately in dev mode):

On macOS / Linux:

# The extension provides a setup script:
./setup-dev-config.sh

# Or manually:
ln -s /path/to/kawa.i18n ~/.kawa-code/extensions/kawa.i18n

On Windows (Git Bash, requires Developer Mode enabled):

ln -s ~/Projects/Odin/kawa.i18n ~/.kawa-code/extensions/kawa.i18n

Or from an elevated Command Prompt / PowerShell:

mklink /D "%USERPROFILE%\.kawa-code\extensions\kawa.i18n" "%USERPROFILE%\Projects\Odin\kawa.i18n"

Note: On Windows 10+, ln -s in Git Bash works without elevation if Developer Mode is enabled. Otherwise, use mklink /D in an elevated terminal.

Option B: Copy for production:

mkdir -p ~/.kawa-code/extensions/i18n
cp extension.json ~/.kawa-code/extensions/i18n/
cp -r binaries/ ~/.kawa-code/extensions/i18n/
cp -r ui/dist/ ~/.kawa-code/extensions/i18n/ui/dist/   # if the extension has UI

Restart Kawa Code after installing.

Creating Your Own Extension

An extension is any executable that reads JSON messages from stdin and writes JSON responses to stdout. You can write extensions in any language (Node.js, Python, Rust, Go, etc.).

Minimum Requirements

1. extension.json manifest in the extension's root directory
2. An executable binary or script referenced by the manifest
3. At least one domain subscription for message routing

Manifest Format (extension.json)

Here is a minimal manifest:

{
  "id": "my-extension",
  "name": "My Extension",
  "version": "1.0.0",
  "description": "What this extension does",
  "binary": {
    "path": "./binaries/my-extension"
  },
  "domains": {
    "subscribe": ["my-domain"]
  }
}

Full manifest reference:

IPC Protocol

Your extension communicates with Kawa Code via JSON lines on stdin/stdout:

Receiving messages (stdin, one JSON object per line):

{"flow":"req","domain":"my-domain","action":"do-something","caw":"client-1","data":{"key":"value"},"_msgId":"abc-123"}

Sending responses (stdout, one JSON object per line):

{"flow":"res","domain":"my-domain","action":"do-something","caw":"client-1","data":{"result":"ok"},"_msgId":"abc-123"}

Message fields:

Important: Use stderr for logging. Anything written to stdout must be valid JSON — stray log output will break the protocol.

Directory Structure

Place your extension in ~/.kawa-code/extensions/<your-extension-id>/:

~/.kawa-code/extensions/my-extension/
├── extension.json          # Manifest (required)
├── binaries/
│   ├── my-extension-macos  # macOS binary
│   ├── my-extension-linux  # Linux binary
│   └── my-extension.exe    # Windows binary
├── dev.sh                  # Dev mode wrapper (optional; Unix/macOS)
├── dev.ps1                 # Dev mode wrapper for Windows (optional; preferred over dev.sh when present)
└── ui/
    └── dist/
        └── my-ui.js        # Web Component bundle (optional)

UI Integration (Optional)

Extensions can provide UI components using Lit Web Components. Kawa Code loads the JS bundle and renders the components in two ways:

• Panels: Appear in Kawa Code's sidebar or bottom area
• Screens: Full-page views accessible from Kawa Code's menu

See the kawa.i18n extension source for a working example of both patterns.

Getting Started

1. Initial Setup

1. Install Kawa Code and create an account
2. Install your editor extension (VSCode, Emacs, or Vim)
3. Install kawa.mcp (optional) if you would like to work with Claude Code
4. Install kawa.i18n (optional) if you would like to read the code in your own language (requires the Claude CLI to be installed and authenticated)
5. Open a Git repository in your editor
6. Verify connection: Look for Kawa Code status indicators in your editor

2. Basic Workflow

1. Work on your code as normal
2. See highlights on lines being modified by teammates
3. View peer diffs in the sidebar/panel
4. Get Claude Code to help you write code
5. Check Intents evolving as you develop your code
6. Click on Code View if you have kawa.i18n installed; navigating in your IDE (VSCode, emacs) will automatically show the translated file in Code View mode
7. Commit and push when ready

3. Using with Claude Code

1. Install the MCP server (see above)
2. Start a coding session in Claude Code
3. Claude will automatically:
   • Check for an active intent before coding
   • Retrieve task-relevant context using semantic search (get_relevant_context)
   • Create intents for new tasks
   • Track code changes
   • Record architectural decisions during implementation
   • Help with commits and include decision summaries

Setting Up CLAUDE.md

CLAUDE.md is a special file that provides instructions to Claude Code when working in your repository. It tells Claude to use Kawa Code's intent tracking and decision recording features.

Minimum Required CLAUDE.md

Create a CLAUDE.md file in your project root with:

# CLAUDE.md

## Project Overview
[1-2 sentence description of your project]

## AI Code Implementation Workflow

**BEFORE exploring code or reading files** for any non-trivial task, follow these steps in order:

1. **Check active intent**: Call `check_active_intent` (kawa-intents MCP) to see if work is already tracked
2. **Get relevant context**: Call `get_relevant_context` with a description of the task to find past decisions and related intents that may inform your approach
3. **Then explore code**: Now read files, search the codebase, and analyze the problem

For trivial one-line fixes (typos, obvious bugs), skip the above and use `log_work` after completing the change.

### Repository Origin and Path
Use these for MCP tools:
- `repoOrigin`: `[email protected]:your-org/your-repo.git`
- `repoPath`: `/absolute/path/to/your-repo` (must contain `.git` directory)

Important: repoPath must point to the directory containing the .git folder. In multi-project setups (monorepos), use each sub-project's path, not the parent directory.

That's it. Claude will discover the available MCP tools automatically. The CLAUDE.md just needs to tell Claude when to call them and provide the repository coordinates.

Multi-Project / Monorepo Setups

If your workspace contains multiple git repositories under a single parent directory, each sub-project needs its own origin and path mapping. Add a table to your CLAUDE.md:

### Repository Origins and Paths

Each sub-project has its own `.git` directory. When calling MCP tools, use the **sub-project path** (not the parent directory) as `repoPath`:

| Sub-project | `repoOrigin`                            | `repoPath`                       |
|-------------|-----------------------------------------|----------------------------------|
| my-api      | `[email protected]:my-org/my-api.git`      | `/path/to/workspace/my-api`      |
| my-frontend | `[email protected]:my-org/my-frontend.git` | `/path/to/workspace/my-frontend` |

Optional: Decision Recording Guidance

If you want Claude to be more thorough about recording architectural decisions, add:

### Recording Decisions

Record decisions using `record_decision` when you:

| Trigger                     | Decision Type |
|-----------------------------|---------------|
| Choose between alternatives | `fork`        |
| Try an approach that fails  | `abandoned`   |
| Find unexpected limitation  | `discovery`   |
| Identify hard requirement   | `constraint`  |
| Make explicit trade-off     | `tradeoff`    |
| Select library/dependency   | `dependency`  |

Troubleshooting

Kawa Code Won't Start

1. Check system requirements
2. Verify no other instance is running
3. Check logs in ~/.kawa-code/logs/
4. Try running from terminal to see error messages

Editor Extension Not Connecting

1. Ensure Kawa Code (Kawa Code) is running
2. Check the socket file exists: ~/.kawa-code/sockets/muninn
3. Restart both Kawa Code and your editor
4. Check editor's output/console for error messages

MCP Server Issues

1. Verify Node.js version: node --version (must be 18+)
2. Run /mcp in Claude Code to check if kawa-intents is listed
3. If missing, check your config:
   • Project scope: .mcp.json in the repo root
   • User/Local scope: ~/.claude.json under the projects → <your-project-path> → mcpServers key
4. Ensure all paths in the config are absolute (not relative)
5. Ensure npm run build completed successfully in kawa.mcp/
6. Check if Kawa Code is running
7. Restart Claude Code after configuration changes

Windows-Specific Issues

• Named pipes are used instead of Unix sockets
• Antivirus may scan ~/.kawa-code/ - consider adding an exclusion
• Run Kawa Code as administrator if permission issues occur

Common Error Messages

Getting Help

• GitHub Issues: Report bugs and request features
• Discord: Join our community for real-time help
• Documentation: Visit kawacode.ai/docs

License

The Kawa Code desktop app and cloud API are proprietary. Every editor extension and the MCP server are open-source — so you can audit exactly what runs alongside your editor, and fork them if your editor needs change.

See individual component repositories for full license details.