A local-first coding agent backend that drives CLI, desktop, and custom clients through a unified WebSocket protocol, featuring persistent sessions, 12 LLM providers, MCP support, and a Skills system.
agent-coworker is a local-first coding agent backend built on a Server-Centric architecture. All agent business logic — reasoning turns, tool execution, session persistence, MCP integration, and provider management — runs server-side. CLI, Electron desktop, and custom clients act as thin clients communicating through a unified JSON-RPC over WebSocket protocol (cowork.jsonrpc.v1).
Key features include SQLite-based persistent sessions with cross-restart recovery; a rich built-in toolchain (shell execution, file read/write/edit, workspace search via glob/grep, web search and fetch, workflow control); a multi-layer Skills discovery system based on SKILL.md instruction packages; full MCP (Model Context Protocol) support with stdio/HTTP/SSE transports, three-tier configuration, and API-key/OAuth authentication; sub-agent creation and management; and OpenTelemetry + Langfuse observability integration.
The project supports 12 LLM providers (Google, OpenAI, Anthropic, Bedrock, Together, Fireworks, NVIDIA, LM Studio, Baseten, OpenCode Go/Zen, Codex CLI), switchable via environment variables, the CLI /connect flow, or the desktop UI. The security model provides dangerous operation approval with a --yolo bypass mode, and sessions support checkpoint backup and restore.
Built on the Bun runtime with TypeScript (94.4%), it can be compiled into a standalone cowork-server binary for headless deployment. The desktop app is built with Electron (electron-vite), and a mobile directory (Expo/React Native) exists but its release status is unclear. Licensed under a custom "Forking and Attribution License with Commercial Permission Requirement 1.0" — forking and modification are allowed, but commercial sale requires written permission from the author. The author states the architecture is stable enough for building, but protocol design, desktop polish, and provider/runtime behavior are still under rapid iteration.
Installation & Running
Prerequisite: Install Bun
git clone https://github.com/mweinbach/agent-coworker.git
cd agent-coworker
bun install
export OPENAI_API_KEY=...
bun run cli # CLI REPL
bun run start # Electron desktop app (dev mode)
bun run serve # Standalone server (headless)
Build standalone binary:
bun run build:server-binary
./dist/cowork-server --host 0.0.0.0 --port 7337
CLI REPL Common Commands
| Command | Function |
|---|---|
/connect <provider> | Start provider authentication flow |
/provider <name> | Switch provider |
/model <id> | Switch model |
/new | New session |
/resume <sessionId> | Resume historical session |
/sessions | List sessions |
/tools | List available tools |
/cwd <path> | Change working directory |
Core Source Structure
| Path | Responsibility |
|---|---|
src/agent.ts | Core agent turn logic |
src/server/ | WebSocket server, JSON-RPC routing, session orchestration |
src/tools/ | Built-in server-side tools |
src/providers/ | 12 provider adapters |
src/mcp/ | MCP config and client lifecycle |
src/skills/ | Skill discovery and trigger extraction |
apps/desktop/ | Electron desktop app |
apps/mobile/ | Expo mobile app |