Kim is a local AI agent platform that connects any cloud LLM (Claude, Gemini, GPT-4o, Ollama) to full OS control — screen vision, mouse/keyboard, file system, browser automation, and shell execution. It is the personal equivalent of Claude Code + Computer Use, running locally, controlled by you.
Status: Active development — macOS first-class, Windows/Linux beta. See Architecture for the full design.
- Multi-provider: Claude, Gemini (OAuth), OpenAI, DeepSeek, Ollama local, or drive any LLM via an open browser tab (no API key needed)
- OS control: Take screenshots, click, type, scroll, run shell commands, read/write files, manage windows
- Browser automation: Fill forms, navigate pages, extract structured data from the DOM
- Code workspace: Integrated code agent (Code tab) powered by Claw/Codex with browser-provider backend, running on
kimcli— Kim's rebranded, pinned build of codex-cli 0.144.3 (docs/kimcli.md) - MCP server: 50+ OS-control tools exposed via the Model Context Protocol — usable from Claude Code or any MCP client
- Session history: Every run is saved as a JSONL trace in
kim_sessions/
- macOS 13+ (arm64 or x64) — primary platform
- Python 3.11+
- Node.js 20+ (LTS)
- Rust stable (
rustup install stable)
Quick path — the install script does all of this step for you (creates venv/, installs Python deps + Playwright Chromium, seeds .env from the template, and records the project root in ~/.kim_root for the packaged app):
git clone https://github.com/AdamMagued/kim.git
cd kim/kim-pro
./install.sh # macOS / Linux
# install.bat # WindowsManual path — the same, by hand:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromiumcp config.yaml.example config.yaml
# Edit config.yaml: set provider, paste API keys, adjust pathsOr set environment variables in .env:
---
## Quickstart: Codex CLI / Desktop Proxy Setup (For Any Machine)
Drive **Codex Desktop GUI** or **Codex CLI** through Kim Engine Proxy with real-time reasoning deltas, live Chrome extension streaming, and automatic workspace `AGENTS.md` auto-injection:
### 1. Clone Repo & Run Install
```bash
git clone https://github.com/AdamMagued/kim.git
cd kim/kim-pro
./install.sh
(Creates venv/, installs Python requirements, sets up Playwright & Chromium)
./scripts/start_codex_proxy.shWhen started, the terminal prints a ready message with your active proxy token:
╔══════════════════════════════════════════════════════════╗
║ Kim Engine → Codex CLI Proxy Launcher ║
╚══════════════════════════════════════════════════════════╝
{"event": "ready", "port": 10532, "token": "YOUR_BEARER_TOKEN"}
- Proxy OpenAI Base URL:
http://127.0.0.1:10532/v1 - Extension WebSocket Bridge:
ws://127.0.0.1:10533
- Open Codex Desktop App.
- Go to Settings → Advanced → Custom Provider / Base URL.
- Set OpenAI Base URL:
http://127.0.0.1:10532/v1 - Set API Key / Authorization Token: Paste
YOUR_BEARER_TOKEN(from step 2). - Select or type Model:
gpt-5.6-sol(orgpt-4o,gemini,deepseek).
Add the environment variables to your ~/.zshrc or ~/.bashrc:
export OPENAI_BASE_URL="http://127.0.0.1:10532/v1"
export OPENAI_API_KEY="YOUR_BEARER_TOKEN"Run codex in any workspace directory:
codex --model gpt-5.6-solIn any project workspace directory, add an AGENTS.md file containing your local ports, dev commands, and REST endpoints. Kim Proxy automatically reads and auto-injects your workspace AGENTS.md into Codex's prompt on Turn 1 — no manual prompt copy-pasting required!
cd desktop
npm install
npm run tauri devThe Tauri window opens. Select a provider in Settings → AI, type a task, and press Enter.
All four test suites (the cli/ crate is separate — easy to forget):
# Python
python -m pytest tests/ -q
# Frontend (Vitest + type check)
cd desktop && npm run test && npx tsc --noEmit
# Rust (desktop)
cd desktop/src-tauri && cargo test
# Rust (kim CLI)
cd cli && cargo testOr with just (if installed: brew install just):
just check # parallel tsc + cargo check + pytest, <30s
just test # full suiteSee ARCHITECTURE.md for the full layer diagram, IPC protocol spec, and design decisions.
Quick summary:
React UI (Tauri webview)
↕ Tauri commands / events
Rust backend (lib.rs)
↕ stdin/stdout IPC
Python orchestrator (agent.py)
↕ MCP stdio
MCP server (50+ OS tools)
See HOW_TO.md for minimal file sets to:
- Add an MCP tool (3 files)
- Add a provider (3 files)
- Add a settings pane (3 files)
- Run a targeted test pass
Quality campaign: docs/OPERATION_GOOGLE_LEVEL.md (plan) · docs/ops/ (findings, triage, baseline).
| Provider | Setup |
|---|---|
| Claude | Set ANTHROPIC_API_KEY in .env; select "claude" in Settings → AI |
| Gemini | Click "Sign in with Google" in Settings → AI (PKCE OAuth, no key needed) |
| Ollama | Run ollama serve; select "ollama" and pick a model |
| Browser | Open Chrome with --remote-debugging-port=9222; select "browser:claude" etc. |
| OpenAI | Set OPENAI_API_KEY; select "openai" |
Kim runs entirely locally. Nothing leaves your machine except:
- LLM API calls (task text + screenshots sent to your chosen provider)
- Screenshots in
kim_sessions/(screenshot payloads are stripped from sessions older than 2 days; whole sessions are deleted after 30 days; export or back up your data from Settings → Data)
No telemetry, no accounts, no cloud storage.
Tasks fail instantly with ModuleNotFoundError (e.g. No module named 'anthropic') — missing or broken venv.
The desktop app resolves a Python interpreter in this order: bundled sidecar → ~/.kim/venv → project venv//.venv/ → bare system python3. If the project venv is missing or broken, Kim silently falls back to your system Python, which does not have Kim's packages. Current builds run a dependency preflight on that fallback and show "Kim's Python dependencies are not installed…" instead of spawning; if you see either that message or a raw ModuleNotFoundError in the task stream, the fix is the same — create the venv:
./install.sh
# or manually:
python3 -m venv venv && ./venv/bin/pip install -r requirements.txtWhere are the logs? Settings → Feedback → "Reveal logs", or logs/kim_YYYY-MM-DD.jsonl (structured JSONL, 7-day retention).
Licensed under the MIT License — see the LICENSE file at the repo root for the full text.
Contributions are welcome under the MIT License. A CONTRIBUTING.md with the
full workflow is still TODO; until then, follow the test-and-CI gate described
above (all four suites green + remote CI green before merge).