# okapi

**Repository Path**: xmecard/okapi

## Basic Information

- **Project Name**: okapi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Okapi

AI Agent desktop application — MFC host with WebView2 GUI, powered by a C++ agent engine DLL.

## Architecture

```
┌──────────────────────────────────────────────┐
│  webview.exe (MFC + WebView2)                │
│  ┌────────────────────────────────────────┐  │
│  │  react/ (Vite SPA, loaded by WebView2) │  │
│  └──────────────┬─────────────────────────┘  │
│                 │ postMessage                 │
│  ┌──────────────▼─────────────────────────┐  │
│  │  JsHandlerManager + domain handlers     │  │
│  └──────────────┬─────────────────────────┘  │
└─────────────────┼────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────┐
│  agent.dll (AI Agent Engine)                 │
│  AgentRuntime → GeneralAgent → ChatModel     │
│  ToolRegistry (Read/Write/Edit/Grep/Shell...)│
│  McpManager, SessionMetadataManager          │
└─────────────────┬────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────┐
│  db.dll (SQLite3 wrapper)                    │
│  ActiveRecord, QueryBuilder, migrations      │
└──────────────────────────────────────────────┘
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Desktop shell | MFC (C++), custom title bar |
| Web UI | React 19, Vite 6, Zustand |
| Agent engine | C++, OpenAI-compatible SSE streaming |
| Database | SQLite3 via custom C++ wrapper |
| Browser engine | Microsoft Edge WebView2 |
| JSON | Bundled jsoncpp |

## Prerequisites

- Visual Studio 2022 (17.x) with C++ desktop workload
- Node.js 18+
- Edge WebView2 Runtime (bundled with Windows 11, manual install for Windows 10)

## Quick Start

### 1. Frontend

```bash
cd react
npm install
npm run dev          # Dev server on port 5173 with HMR
npm run build        # Production build → react/dist/
```

### 2. Backend (C++)

Open `okapi.slnx` in Visual Studio, or compile via command line:

```bash
# Build order: db.dll → agent.dll → webview.exe
msbuild db\db.vcxproj /p:Configuration=Debug /p:Platform=x64
msbuild agent\agent.vcxproj /p:Configuration=Debug /p:Platform=x64
copy /Y agent\x64\Debug\agent.* x64\Debug\
msbuild webview\webview.vcxproj /p:Configuration=Debug /p:Platform=x64
```

### 3. Run

Launch `x64/Debug/webview.exe`. The app loads the React frontend from `react/dist/` (production) or connects to the Vite dev server.

## Project Structure

```
okapi/
├── agent/          # Agent engine DLL — AI logic, tools, LLM client
├── webview/        # MFC desktop app — WebView2 host, JS handlers
├── db/             # SQLite3 C++ wrapper DLL
├── react/          # React SPA frontend
├── demo/           # Standalone React app for PreviewTool testing
├── scripts/        # Build and test utilities
└── okapi.slnx      # Visual Studio solution
```

## Key Features

- **Multi-session AI chat** — Create/manage independent chat sessions with different agents
- **Tool system** — Read/Write/Edit/Grep files, Shell commands, Browser automation, Web search
- **MCP support** — Model Context Protocol for external tool servers
- **Project-aware** — Auto-detects tech stack, manages .gitignore, infrastructure records
- **Preview pane** — In-app browser with CDP-based inspection (click, type, snapshot, console capture)
- **Streaming UI** — Real-time LLM response streaming with thinking/tool_call/response stages
- **Conversation compaction** — Auto-summarizes long conversations to manage context window