Architecture Overview

System Architecture

Katachi consists of three components that work together to provide secure remote access to your AI coding tools.

flowchart TB
    subgraph machine["Your Machine"]
        subgraph agent["Katachi Agent"]
            ai["AI Service\n(Providers)"]
            fs["File/Git\nOperations"]
            mcp["MCP Server\n(JSON-RPC)"]
        end
        tunnel["Encrypted Tunnel"]
    end

    subgraph cloud["Cloudflare Network"]
        cf[" "]
    end

    subgraph backend["Katachi Backend"]
        auth["Auth\nService"]
        db["Database\n(State)"]
        router["Tunnel Router\n(Request Relay)"]
    end

    subgraph webui["Katachi Web UI"]
        viewer["File Viewer\n(CodeMirror)"]
        chat["Chat\n(AI Chat)"]
        sessions["Session Manager\n(Workspaces)"]
    end

    agent --> tunnel
    tunnel --> cf
    cf --> router
    webui -->|HTTPS| backend

Component Details

Agent

The agent is a TypeScript/Node.js daemon that runs on your workstation. It:

• Hosts AI providers — Runs native SDKs for Claude, Gemini, OpenAI/Codex, and Copilot
• Manages files — Reads and diffs files in your workspaces via a sandboxed filesystem layer
• Handles git — Creates branches, commits, pushes, and manages worktree isolation
• Serves MCP — Exposes a Model Context Protocol server for structured tool calls
• Establishes tunnel — Creates a secure encrypted tunnel to the backend

Backend

The backend is a Go server running in the cloud. It:

• Authenticates — Validates user identity and manages sessions
• Routes requests — Forwards web UI requests to the correct agent via tunnel
• Manages state — Stores session metadata and tunnel registrations
• Streams responses — Proxies SSE streams from the agent to the browser

Web UI

The web UI is a React single-page application. It provides:

• File viewer — CodeMirror-based viewer with syntax highlighting and git diff
• Chat interface — Real-time streaming chat with your AI assistant
• Kanban board — Task card management for Katachi Flow sessions
• Session Commander — AI orchestrator for multi-card workflows
• Settings — Configure API profiles, themes, and agent management

Communication Model

Agent ↔ Backend

The backend communicates with the agent via JSON-RPC over an encrypted tunnel. The agent exposes an HTTP server on localhost; the tunnel provides secure external access. No direct WebSocket connections are used.

Chat Streaming

Katachi uses Server-Sent Events (SSE) to stream AI responses in real-time. The web UI initiates a chat request, the backend relays it to the agent, and tokens stream back to the browser as they’re generated.