KinetAios

Local-first multi-engine AI agent dashboard (Windows/macOS) with a built-in MCP server: expose agent sessions, long-term memory search, and 40+ tools to any MCP client. Runs Claude Code, Codex and a built-in ReAct engine side by side. https://github.com/phinn/KinetAios

GitHub
13

Documentation

KinetAios

English | ็ฎ€ไฝ“ไธญๆ–‡

License: GPL v3 GitHub stars Release Platforms Discussions Good First Issues Mac App Store

๐ŸŒ Website โ†’ https://phinn.github.io/KinetAios/

KinetAios dashboard

Seven engines running side-by-side

Real session: parallel conversations across projects, engine badge per session, file & Git & rules tabs, token-cost accounting per turn.

A local-first AI agent dashboard for Windows 11 and macOS โ€” both first-class platforms (the "Win" folder name is historical; the repo is phinn/KinetAios). Platform differences (cmd.exe vs /bin/sh, hotkey, tray) are routed at runtime; features are aligned on both sides. Run multiple agent sessions concurrently with streaming answers, shell/file/search/MCP tools, SQLite history with long-term memory, a global hotkey, and a per-session model. No account, no relay server โ€” your own LLM API key is the only credential.

The 30-second version:

  • ๐Ÿ”€ Seven engines, one window โ€” Direct V1โ€“V5 (in-house ReAct line) + Claude Code + Codex; switch per session, hand off context via Pipeline
  • ๐Ÿง  Long-term memory on local SQLite โ€” auto-extracted facts shared across all engines, survives restarts
  • ๐Ÿ”’ Local-first, no account โ€” your API key is the only credential; nothing goes through a relay
  • ๐Ÿ›  30+ built-in tools + MCP client/server + plugins โ€” shell, files, web, screenshots, computer use out of the box
  • โŒจ๏ธ Global-hotkey quick panel โ€” Spotlight for AI agents, summon from anywhere
  • ๐Ÿ“Š Benchmarked on a real 400k-row business task โ€” in-house engine 9.2 vs Claude Code 7.0 (full report)
  • ๐Ÿ–ฅ Windows 11 & macOS โ€” both first-class

โญ If KinetAios saves you time, a Star is the loudest thank-you for a solo open-source project.

Why KinetAios?

Most AI clients lock you into one provider, drop context when you switch engines, and route your conversations through a relay. KinetAios runs seven engines in one window, keeps long-term memory across all of them, and never asks for an account.

KinetAiosClaude DesktopCherry StudioCursorCodex Desktop
Seven engines (Direct V1โ€“V5 + Claude Code + Codex, + plugin engines)โœ…โ€”โ€”โ€”โ€”
Local SQLite + automatic long-term memoryโœ…โ€”โ€”โ€”โ€”
Cross-engine memory (one user profile shared by all engines)โœ…โ€”โ€”โ€”โ€”
Multiple parallel sessionsโœ…โ€”โœ…โ€”โœ…
Global hotkey + quick panelโœ…โ€”โ€”โ€”โ€”
Auto-scan MCP / Skills / Agentsโœ…โœ…โ€”โ€”โ€”
Project rules (AGENTS / CLAUDE / KINET)โœ…โ€”โ€”โœ…โœ…
Built-in MCP Server (remote agent control)โœ…โ€”โ€”โ€”โ€”
Plugin system (tools / panels / slash commands)โœ…โ€”โ€”โ€”โ€”
Multimodal (image input + voice + screenshots)โœ…โœ…โ€”โ€”โ€”
Session branching + cross-engine Pipeline orchestrationโœ…โ€”โ€”โ€”โ€”
Local-first, no accountโœ…โœ…โœ…โ€”โ€”

Install

Grab the latest release:

Unsigned builds โ†’ Windows SmartScreen / macOS Gatekeeper will warn; allow it manually.

First launch: click the โš™ in the top right โ†’ paste your API Key (+ base URL / model, defaults to GLM/Zhipu) โ†’ hit Test Connection, then send your first task.

๐Ÿ‹ One key for every model? Pick the OrcaRouter preset โ€” an OpenAI-compatible gateway with 200+ models, adaptive routing, zero markup. Sign up with this link to support the project (5% referral credit).

Built-in OrcaRouter preset:

provider: orcarouter          # Settings โ†’ Presets โ†’ OrcaRouter (multi-model routing)
protocol: openai              # OpenAI-compatible
base_url: https://api.orcarouter.ai/v1
api_key: sk-orca-...          # create in the OrcaRouter console
model: orcarouter/auto        # adaptive routing, or pin a vendor/model e.g. anthropic/claude-opus-4.8

From source

Requires Node.js 18+ and a network connection (the better-sqlite3 native module needs compiling).

git clone https://github.com/phinn/KinetAios.git
cd KinetAios
npm install      # includes postinstall: rebuild better-sqlite3 for Electron
npm run build
npm start

Highlights

Seven engines, switchable per session

  • Direct V1 (Kaios) โ€” built-in ReAct loop with a dual-protocol provider (OpenAI-compatible & Anthropic, both directions of SSE streaming), tool-level concurrency, sub-agents, context compaction and retries.
  • Direct V2 โ€” next-gen ReAct on a Plan-Execute-Verify-Judge architecture, streaming tool calls, step-by-step task lists rendered live in the chat as checklist cards, plus a unified execution loop shared by plan and replan (retry / verification / checkpointing / compaction behave identically on both paths).
  • Direct V3 โ€” an intent router picks fast / standard / deep per query; the deep path builds tool calls into a dependency DAG and executes it in parallel โ€” real speedups on multi-step tasks.
  • Direct V4 (Legis) โ€” legislation-style pipeline: the engine compiles a plan into explicit bill-like steps (legis-compiler), executes them under rules (legis-executor), and verifies with assertions before settling.
  • Direct V5 (Phylum) โ€” population-based evolution loop: candidates run, get scored (scorer), and winning strategies are settled into the replay signature registry โ€” the engine that improves itself across runs.
  • Claude Code โ€” spawns claude -p --output-format stream-json, parses NDJSON, resumes with --resume.
  • Codex โ€” spawns codex exec --json, parses JSONL, resumes.

30+ built-in tools

shell (confirm before running; focus guard โ€” if a command steals the foreground it's handed back automatically), read_file, write_file, edit_file (exact replace), grep, glob, web_fetch (SSRF guard + Jina Reader fallback), web_search (Bing โ†’ DuckDuckGo fallback), recall_memory, git_diff (read-only, no confirm), remember_fact / recall_fact (session anchors), memory_replace / memory_append (core memory blocks), dispatch_agent (read-only sub-agent with its own context), spawn_team / team_broadcast / team_send / team_close (multi-agent teams), video_gen (MiniMax H3 text-to-video), todo_write (shared task list, rendered live as checklist cards), and more.

Computer Use (native, zero external dependencies)

  • screenshot (with hide_self โ€” the agent's own window turns transparent during the shot, zero focus stealing), screenshot_window (capture any window by title โ€” even occluded/background ones, no desktop switching).
  • mouse_click / mouse_scroll / mouse_drag, keyboard_type / keyboard_key โ€” coordinates are converted from the last screenshot's pixel space to the platform's action space (DPI / window-origin aware, with staleness expiry).
  • Backed by Electron desktopCapturer + PowerShell (Windows) / cliclick (macOS) / xdotool (Linux). On macOS, bare open is mechanically rewritten to open -gj โ€” the agent never steals your foreground.

MCP integration (client + server)

  • Client: the Direct engine auto-connects to MCP servers configured on your system (scans ~/.claude.json, ~/.codex/config.toml, Claude Desktop). stdio transport, auto-reconnect after unexpected drops. The ๐Ÿ”Œ button shows connected servers/tools.
  • Server: a built-in MCP Server (HTTP+SSE) exposes a run_agent tool โ€” remote machines can invoke your local full agent. Token auth (constant-time compare), 5-minute timeout, zombie-connection detection.

Tools

Tools

ToolDescription
run_agentRun the full local agent (any engine) with a task prompt; streams progress and returns the final answer. Authenticated via bearer token, 5-minute timeout.

Configuration

{
  "mcpServers": {
    "kinetaios": {
      "url": "http://127.0.0.1:18109/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Enable it in KinetAios under Settings โ†’ MCP Server (pick a port, optionally set a token โ€” omit the header if empty). Default port: 18109, off by default.

Long-term memory + memory graph

  • Each turn, durable "facts about the user" are extracted in the background โ†’ SQLite โ†’ injected into the next turn. Shared across engines and sessions.
  • Memory graph visualization: force-directed graph of memory provenance, conflict detection, timeline. Standalone fullscreen window.
  • Import/export memories as JSON (backup or migration).

Skills / Commands / Agents / Plugins

  • Scans Claude Code's skills + commands + agents and Codex's skills. Invoke via the / menu or the โšก button.
  • Skills panel (Settings โ†’ Skills): aggregates skills from all third-party sources plus plugin contributions, with search, viewing, and direct source editing (plugin skills read-only). Edits take effect immediately.
  • Plugin SDK v3: plugins contribute tools, slash commands, hooks, fullscreen panels, and engines. Injected on demand (keyword matching saves ~60% tokens). 26 built-in plugins: office-suite, brainstorm (Excalidraw), math-practice, cpp-learning, low-altitude (drones), an embedded & IoT suite (arduino-dev / platformio-dev / serial-comm / modbus-dev / mqtt-dev / ble-dev / ota-dev / sensor-lookup / logic-analyzer / hw-diag), nestjs-dev, deepseek-harness, gemini-cli, claude-code-router, claude-code, codex, marketing-kit (marketing research: competitors / SEO / funnel / app-review mining + a marketing console panel), and more.

Sidebar (left to right)

  • ๏ผ‹ new session.
  • ๐Ÿ“‚ Workbench โ€” project cards grouped by cwd, each showing recent activity + cost. A "Context" button edits KINET-CONTEXT.md.
  • Live session status โ€” running sessions show the engine's current step (tool executing / retrying / compacting) right under the title in the sidebar, no need to open the channel.
  • ๐Ÿ“Š Dashboard โ€” standalone window with live token usage, cost stats, engine distribution.
  • ๐ŸŒ Files โ€” file browsing + <webview> preview (HTML/SVG/PNG/JPG/PDF) + editor. Multi-tab. The address bar accepts file:// / http(s):// / localhost:<port>.
  • ๐Ÿ˜๏ธ Town โ€” game-style isometric visualization of remote nodes (other KinetAios instances) on your network.
  • ๐Ÿง  Memory โ€” memory panel: current channel / all, inline edit/delete, provenance.
  • ๐Ÿ”Œ Plugins โ€” plugin management: enable/disable, search & filter, category cards.
  • โš™๏ธ Settings โ€” see below.

Main-window tabs (Chat / Files / Git / Rules)

  • Chat โ€” streaming output, collapsible tool steps, live token counts, context inspector, screenshots, voice input.
  • Files โ€” same as ๐ŸŒ, following the current session's cwd.
  • Git โ€” git status (left) + git log (right). Click a changed file โ†’ side-by-side diff; click a commit โ†’ unified git show.
  • Rules โ€” edit KinetAios.md in the cwd (project-level rules, injected into the system prompt).

Pipeline (cross-engine orchestration)

Chain multiple stages, each with its own engine + prompt. The previous stage's output is prepended to the next stage's prompt. 2-minute per-stage timeout polling, abort on failure.

Session branching & handoff

  • Branch from any turn โ€” deep-copies turns/steps into a new session.
  • Export/import sessions โ€” serializes full session state (turns + history + engine + model + cwd) for cross-machine handoff. Export auto-redacts secrets (API keys, passwords โ†’ [REDACTED]).
  • Cross-session references โ€” link related sessions, visualized as a DAG.

Context management (Direct engine)

  • Context inspector โ€” view/edit each session's directHistory array (JSON editor).
  • Auto-compaction โ€” when history exceeds the token budget, early turns are summarized by the LLM. Compaction events are visualized (tokens before vs after).
  • Per-protocol calibration โ€” token/char ratios are tracked separately per API protocol (OpenAI vs Anthropic) so concurrent sessions don't interfere.

Multimodal (Direct engine)

  • Image input: ๐Ÿ“Ž pick/paste images โ†’ vision content parts โ†’ OpenAI image_url or Anthropic base64 format.
  • Voice transcription: ๐ŸŽค record โ†’ Whisper โ†’ fills the input box.
  • Realtime voice chat: ๐ŸŽค โ†’ Volcengine Doubao WebSocket two-way voice โ€” natural TTS, live transcription, parallel agent tool execution. See the voice chat wiki.
  • Screenshots: ๐Ÿ“ธ overlay โ†’ drag a region โ†’ cropped image injected into the prompt.

Global search

Ctrl/Cmd+K overlays a search across all sessions โ€” matching prompt text, answer text, and tool output.

Settings (โš™๏ธ)

  • Two-column layout: vertical tab nav on the left (Models / Appearance / Engines / Advanced / Security / Messages / Plugins / Skills / Goal / Multi-machine), independent scrolling on the right; narrow windows fall back to horizontal tabs; a search box filters across all panels.
  • Providers: OpenAI / Anthropic protocols, base URL, model, key. GLM / DeepSeek / OrcaRouter / OpenAI / Anthropic presets. Zhipu balance check button. Encrypted storage via safeStorage.
  • Security: privacy gate (detects sensitive data leaving the machine).
  • Behavior: shell approval mode, sandbox level, plan mode, CLI engine toggles, window-close behavior (quit / minimize / tray).
  • Pricing: per-model input/output prices for cost calculation.
  • Interface: language (English / ็ฎ€ไฝ“ไธญๆ–‡ / ็น้ซ”ไธญๆ–‡ / ๆ—ฅๆœฌ่ชž), theme (dark / light, live preview).
  • Long-term memory: export/import JSON.

Misc

  • Per-session model (editable dropdown, OpenAI-compatible + Anthropic dual protocol).
  • File attachments: ๐Ÿ“Ž pick/drop multiple text files (large files read header-only), @path references to cwd files.
  • KinetAios.md / AGENTS.md / CLAUDE.md โ€” rule files in the cwd are auto-injected into the system prompt.
  • Tray + global hotkey Ctrl/Cmd+Alt+Space โ†’ quick panel.
  • Compact mode: per-turn meta (duration / tokens / cost) hidden by default, shown on message hover; real file paths in tool output are clickable to open.
  • Update check against GitHub Releases, shown on the About page.
  • Configurable branding (brand.json), encrypted API key storage (safeStorage: macOS Keychain / Windows DPAPI).

Benchmarks: seven engines, one real business task

The same 400k-row medical-device CRM cross-analysis (multi-sheet ร— hospital tier ร— time window, producing an interactive ECharts report) โ€” seven engines, identical prompt, zero human intervention:

EngineScore /10TokensKey difference
Direct (in-house)9.21.31MNative SAX-streaming xlsx โ€” the file never enters the context
Claude Code7.0~2MGreat context management, but no plugin tools โ€” every step detours through Bash+python
Codex5.5~2.4MSandbox-first design, wrong fit for interactive data tasks
PEVJ V2 (in-house)3.53.8M+Four-layer architecture with no guardrails on verify = token amplifier

The most valuable finding: 7.5% of API calls burned 63% of the budget. The root cause wasn't the model โ€” it was tool design. The agent read the same large file 16 times sequentially, resending full history each pass. Switching to a streaming reader zeroed that cost.

Full report: methodology + per-dimension scores + step-by-step traces โ€” includes all the gory details of our own engine's 3.5.

Tech stack

  • Electron + TypeScript โ€” the main process runs the agent runtime; the renderer is a native web UI.
  • better-sqlite3 โ€” SQLite + FTS5 (history / recall_memory full-text search + embedding semantic recall).
  • No frontend framework โ€” the renderer is vanilla TS + HTML/CSS, bundled with esbuild.

Project layout

KinetAios/               # repo root (the "Win" dir name is historical โ€” it's the cross-platform repo now)
  brand.json               # branding config (product name etc., read at startup)
  package.json
  src/
    shared/types.ts         # types + applyEvent (shared by main/renderer, single source of truth)
    shared/i18n.ts          # four-language string table + t()
    main/
      main.ts               # windows / tray / hotkey / IPC / shell-confirm bridge
      TaskManager.ts        # session management + engine dispatch + memory extraction
      engines.ts            # Engine interface + Direct/ClaudeCode/Codex + cross-platform CLI spawn
      AgentLoop.ts          # ReAct loop (Direct) + history compaction + auto-shrink
      V3/                   # Direct V3: intent router + fast/deep paths (deep = DAG parallel)
      glm.ts                # providers + OpenAI/Anthropic SSE streaming + retries
      updater.ts            # GitHub Releases update check
      tools.ts              # 30+ built-in tools + computer-use glue + focus guard
      computer-use.ts       # screenshot / mouse / keyboard (native APIs)
      mcp.ts                # MCP client (scan + stdio + reconnect)
      mcp-server.ts         # MCP server (HTTP+SSE, run_agent, token auth)
      skills.ts             # skills/commands/agents/plugin scanning
      plugins.ts            # plugin loader (SDK v3: tools/slash commands/hooks/panels)
      store.ts              # better-sqlite3 + FTS5
      settings.ts           # config (encrypted API key, lang, embedding)
    preload/preload.ts      # narrow contextBridge API
    renderer/
      index.html quick.html styles.css
      app.ts                # dashboard logic (chat, sidebar, tabs, context inspector)
      quick.ts              # quick panel logic
      dashboard.ts          # cost/token dashboard window
      arena.ts              # deep-analysis dashboard
      memory-graph.ts       # memory graph SVG visualization
      town.ts               # Town view (remote-node visualization)
      files-pane.ts         # file browsing + webview preview + editor
      code-editor.ts        # code editor (syntax highlighting)
      file-drawer.ts        # file drawer UI
      nexus.ts              # Nexus view
      focus-manager.ts      # focus / focus-trap management
      highlight.ts          # chat code-block syntax highlighting
      markdown.ts           # mini markdown renderer
  plugins/                  # 20 built-in plugins (SDK v3)

Build / develop

npm run build       # tsc (main/preload/shared) + esbuild (renderer) + copy brand.json
npm run typecheck   # typecheck both halves, no emit
npm start           # launch (requires a prior build)
npm run dev         # build + start

Packaging

npm run dist         # default target for the current platform
  • Windows: release\KinetAios Setup <ver>.exe (NSIS). Must be built on Windows (cross-building Windows + native modules from macOS is unreliable).
  • macOS: build a dmg with npx electron-builder --mac (requires a Mac toolchain).
  • electron-builder rebuilds better-sqlite3 against Electron's ABI automatically; asar: false avoids native-module-in-asar loading errors.
  • Unsigned builds โ†’ Windows SmartScreen / macOS Gatekeeper will warn; allow manually. Removing the warning needs a signing cert (+ Apple notarization).
  • The icon defaults to Electron's; replace with your own: build/icon.ico (256ร—256) on Windows, build/icon.icns on macOS.

Known constraints

  • Window-close behavior is configurable (quit / minimize / tray), default minimize. The global hotkey only works while the app is running.
  • No cross-building โ€” build Windows installers on a Windows machine or a GitHub Actions windows-latest runner, and dmgs on a Mac (native-module rebuild needs the target toolchain).
  • Platform-specific code paths (shell / PATH / hotkey / tray) should be verified on their target OS.

The Kinet family

KinetAios is part of the Kinet family โ€” 19 apps on the App Store, one app per job:

Flagships

  • KinetAios on the Mac App Store โ€” same agent, one-click install ($12.99); the open-source build in this repo is free
  • KinetTask โ€” local-first task manager, on-device AI, data stays in local SQLite
  • KinetBrief โ€” AI briefing / meeting notes โ€” make today count
  • KinetFit โ€” health companion โ€” wake the body up first
  • KinetSoul โ€” AI journal โ€” give your feelings a way out

Also on the App Store

KinetFlashFind โ€” every file, in under a second ยท KinetMinutes โ€” notes ready when you leave the room ยท KinetMorning โ€” daily check-in, visible from afar ยท KinetElf โ€” a pocket elf that grows on you ยท KinetStudy โ€” mistakes kept, parents not guessing ยท KinetMagicDisk โ€” see who's eating your disk ยท Clasp Focus โ€” close the lid and it begins ยท DriftDesk โ€” a corner of calm in the menu bar ยท DuoFolio โ€” a book built for the fold ยท FurChart โ€” pet records, never in a drawer ยท KinetRain โ€” rain on demand ยท M5Chat โ€” multi-engine AI in your pocket ยท Promptside โ€” one person is the whole crew ยท KinetMemory โ€” spaced repetition, forgetting on schedule

KinetAgent (drive your Mac's Claude Code from iPhone), KinetMagicWindow and KinetDock are in development โ€” full roadmap on the family page.

License

GPL-3.0