[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-55":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":40,"readmeContent":41,"aiSummary":42,"trendingCount":15,"starSnapshotCount":15,"syncStatus":43,"lastSyncTime":44,"discoverSource":45},55,"craft-agents-oss","warpdot-dev\u002Fcraft-agents-oss","warpdot-dev","electron anthropic claude-agent-sdk mcp bun websocket thin-client multi-llm openapi skills automations oauth desktop-ai github-copilot google-ai chatgpt devtools apache-2 headless-server pi-sdk vscode-alternative linux macos windows","https:\u002F\u002Fgithub.com\u002Fwarpdot-dev\u002Fcraft-agents-oss",null,"TypeScript",217,242,221,0,47.16,"Apache License 2.0",false,"main",true,[22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"ai-agents","anthropic","automations","bun","chatgpt","claude","desktop","devtools","electron","github-copilot","google-ai","llm","mcp","openapi","skills","thin-client","typescript","websocket","2026-06-11 04:00:17","# Craft Agents OSS\n\n**Desktop and headless workspace for Claude-class agents**, with **sources** (REST APIs and **Model Context Protocol \u002F MCP** servers), **skills**, **automations**, and a document-first UI. Built on the **Claude Agent SDK** and **Pi SDK** for multi-provider LLM access.\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg)](LICENSE)\n[![Contributor Covenant](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FContributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n\n**Org repository:** [`github.com\u002Fwarpdot-dev\u002Fcraft-agents-oss`](https:\u002F\u002Fgithub.com\u002Fwarpdot-dev\u002Fcraft-agents-oss) · Upstream reference: [**lukilabs\u002Fcraft-agents-oss**](https:\u002F\u002Fgithub.com\u002Flukilabs\u002Fcraft-agents-oss)\n\n---\n\n## Overview (what you get)\n\n| Capability | Description |\n|------------|-------------|\n| **Multi-session inbox** | Organize agent chats with statuses, flags, and persistence |\n| **Sources** | Connect **MCP servers**, **OpenAPI**-backed REST APIs, Google \u002F Slack \u002F Microsoft stacks, and local filesystems |\n| **Skills** | Reusable instruction packs per workspace; reference with `@` mentions |\n| **Providers** | Anthropic (API + OAuth), Google AI Studio, ChatGPT Plus (Codex), GitHub Copilot, OpenAI-compatible endpoints, and more |\n| **Remote mode** | Run a **headless WebSocket server**; use the Electron app as a thin client or drive sessions from the **CLI** |\n| **Automations** | Cron, labels, tool hooks, and other events to spawn prompts and workflows |\n\n**Search terms & synonyms:** *agent desktop app*, *Electron AI client*, *Claude Agent SDK GUI*, *MCP client*, *AI workspace*, *multi-LLM desktop*, *Craft Agents open source*, *Apache 2.0 agent IDE*, *session-based agents*, *thin client agent server*.\n\n---\n\n## Table of contents\n\n- [Product tour (video)](#product-tour-video)\n- [Why Craft Agents exists](#why-craft-agents-exists)\n- [Highlights & FAQ-style capabilities](#highlights)\n- [Install](#installation)\n- [Features at a glance](#features)\n- [Quick start](#quick-start)\n- [Desktop: sessions, sources, permissions, shortcuts](#desktop-app-features)\n- [Remote server (headless)](#remote-server-headless)\n- [CLI client](#cli-client)\n- [Repository layout](#architecture)\n- [Development & Google OAuth](#development)\n- [Supported LLM providers](#supported-llm-providers)\n- [Advanced: automations, large responses, deep links](#advanced-topics)\n- [Tech stack](#tech-stack)\n- [Troubleshooting](#troubleshooting)\n- [License, trademarks, security](#license)\n\n---\n\n## Product tour (video)\n\n[![Craft Agents walkthrough on YouTube](https:\u002F\u002Fimg.youtube.com\u002Fvi\u002FxQouiAIilvU\u002Fhqdefault.jpg)](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=xQouiAIilvU)\n\n[Watch on YouTube →](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=xQouiAIilvU)\n\n---\n\n## Why Craft Agents exists\n\nCraft Agents is the **open-source** app we use at **Craft** to work with frontier models day to day. It emphasizes:\n\n- **Multitasking** across many agent sessions without losing context  \n- **Connected data** through APIs and MCPs—without editing stacks of config files by hand  \n- **Shared session state** and a **document-centric** flow (less terminal-only friction)  \n- **Agent-native UX**: describe intent; the product handles wiring, permissions, and skill discovery where possible  \n\nThe project is **Apache 2.0** so you can fork, theme, and ship custom builds. Internally we **dogfood** development inside Craft Agents itself.\n\n![Craft Agents session and sidebar](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F3f1f2fe8-7cf6-4487-99ff-76f6c8c0a3fb)\n\n---\n\n## Highlights\n\n**Connect Linear, Gmail, Slack, custom APIs, or local MCPs**\n\n- Tell the agent to add a **source**; it can discover public APIs \u002F MCP docs, negotiate credentials, and wire configuration. Prefer files? Paste an **MCP JSON** config—it is applied automatically.  \n- **Stdio MCP servers** run locally (`npx`, Python, custom binaries).  \n- Paste **OpenAPI** specs, endpoint lists, or doc screenshots—the agent proposes a workable integration surface.  \n\n**Skills & live updates**\n\n- Import skills from other Claude-style setups on request.  \n- Reference skills and sources with `@` mid-conversation; changes apply **without restarting** the app.  \n\nDeep dives (hosted examples):\n\n- [Connecting Slack interactively →](https:\u002F\u002Fagents.craft.do\u002Fs\u002FDRNQEiy8w2e1v5LPgKl8b)  \n- [Bulk skill import →](https:\u002F\u002Fagents.craft.do\u002Fs\u002FgWCFqwhObFWaNJIEJmd6j)  \n\n---\n\n## Installation\n\n### One-line install (recommended)\n\n**macOS \u002F Linux**\n\n```bash\ncurl -fsSL https:\u002F\u002Fagents.craft.do\u002Finstall-app.sh | bash\n```\n\n**Windows (PowerShell)**\n\n```powershell\nirm https:\u002F\u002Fagents.craft.do\u002Finstall-app.ps1 | iex\n```\n\n### Build from source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fwarpdot-dev\u002Fcraft-agents-oss.git\ncd craft-agents-oss\nbun install\nbun run electron:start\n```\n\n---\n\n## Features\n\n- **Multi-session inbox** — session management, statuses, archiving, flagging  \n- **Streaming agent UX** — tool traces, progressive responses, realtime updates  \n- **Multiple LLM connections** — per-workspace defaults; mix providers thoughtfully  \n- **Multi-provider backends** — Google AI Studio, ChatGPT Plus (Codex OAuth), GitHub Copilot OAuth, Anthropic Claude paths, plus OpenAI-compatible routes  \n- **Craft MCP bundle** — 30+ Craft document tools (blocks, collections, tasks, search)  \n- **Sources ecosystem** — MCP, REST integrations, filesystem \u002F vault access  \n- **Permission modes** — `safe` \u002F `ask` \u002F `allow-all` with granular policies  \n- **Background jobs** — long-running tasks with visible progress  \n- **Custom statuses** — Kanban-like workflow states  \n- **Theming** — app-level and workspace-level themes  \n- **Multi-file diff** — review edits across files in one pass  \n- **Attachments** — images, PDFs, Office docs with conversion helpers  \n- **Automations** — schedules, label changes, tool hooks, lifecycle events  \n\n---\n\n## Quick start\n\n1. **Launch** the desktop app after install.  \n2. **Connect an LLM**: Anthropic (API key \u002F subscription OAuth), Google AI Studio, Codex-backed ChatGPT, GitHub Copilot, or configured OpenAI-compatible endpoints.  \n3. **Create a workspace** to isolate sessions, skills, and sources.  \n4. **Attach sources** (optional): MCP, REST APIs, or local folders.  \n5. **Open a session** and start prompting; escalate permissions (`SHIFT+TAB`) when you intentionally need writes.  \n\n---\n\n## Desktop app features\n\n### Session management\n\n- **Inbox \u002F archive** with workflow columns  \n- **Flagging** for follow-ups  \n- **Statuses** (`Todo → In Progress → Needs Review → Done`, customizable)  \n- **AI \u002F manual naming** plus durable JSONL history  \n\n### Sources\n\n| Type | Examples |\n|------|----------|\n| **MCP** | Craft, Linear, GitHub, Notion, bespoke servers |\n| **REST APIs** | Google Workspace, Slack, Microsoft Graph |\n| **Local** | Filesystem roots, Obsidian vaults, git checkouts |\n\n### Permission modes\n\n| Internal ID | Label | Behaviour |\n|-------------|-------|-----------|\n| `safe` | Explore | Read-only; blocks mutating operations |\n| `ask` | Ask to edit | Confirmation gates (default) |\n| `allow-all` | Auto | Auto-approves tooling |\n\nPress **`SHIFT+TAB`** inside chat to rotate modes.\n\n### Keyboard shortcuts\n\n| Shortcut | Action |\n|----------|--------|\n| `Cmd+N` | New chat |\n| `Cmd+1\u002F2\u002F3` | Focus sidebar \u002F list \u002F transcript |\n| `Cmd+\u002F` | Shortcut cheat sheet |\n| `SHIFT+TAB` | Cycle permission modes |\n| `Enter` | Send |\n| `Shift+Enter` | New line |\n\n---\n\n## Remote server (headless)\n\nRun logic on a **Linux VPS**, **home lab**, or CI runner while controlling it from Electron or automation.\n\n### Start the server\n\n```bash\nCRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages\u002Fserver\u002Fsrc\u002Findex.ts\n```\n\nCopy the emitted `CRAFT_SERVER_URL` and `CRAFT_SERVER_TOKEN`.\n\n### Thin-client Electron shell\n\n```bash\nCRAFT_SERVER_URL=wss:\u002F\u002F203.0.113.5:9100 CRAFT_SERVER_TOKEN=\u003Ctoken> bun run electron:start\n```\n\n### Environment variables\n\n| Variable | Required | Default | Notes |\n|----------|:--------:|---------|-------|\n| `CRAFT_SERVER_TOKEN` | ✅ | — | Bearer token presented by clients |\n| `CRAFT_RPC_HOST` | | `127.0.0.1` | Set `0.0.0.0` for remote NIC binding |\n| `CRAFT_RPC_PORT` | | `9100` | Plain \u002F TLS WebSocket port |\n| `CRAFT_RPC_TLS_CERT` | | — | PEM cert path (`wss:\u002F\u002F`) |\n| `CRAFT_RPC_TLS_KEY` | | — | PEM private key |\n| `CRAFT_RPC_TLS_CA` | | — | Optional client verification chain |\n| `CRAFT_DEBUG` | | `false` | Verbose RPC logging |\n\n### TLS quick path\n\n```bash\n.\u002Fscripts\u002Fgenerate-dev-cert.sh\nCRAFT_SERVER_TOKEN=\u003Ctoken> \\\nCRAFT_RPC_HOST=0.0.0.0 \\\nCRAFT_RPC_TLS_CERT=certs\u002Fcert.pem \\\nCRAFT_RPC_TLS_KEY=certs\u002Fkey.pem \\\nbun run packages\u002Fserver\u002Fsrc\u002Findex.ts\n```\n\nFor production place **trusted certificates** or terminate TLS behind **nginx**, **Caddy**, or similar.\n\n### Docker sketch\n\n```bash\ndocker run -d \\\n  -p 9100:9100 \\\n  -e CRAFT_SERVER_TOKEN=\u003Ctoken> \\\n  -e CRAFT_RPC_HOST=0.0.0.0 \\\n  -v craft-data:\u002Froot\u002F.craft-agent \\\n  craft-agents-server\n```\n\nMount cert\u002Fkey volumes when enabling `CRAFT_RPC_TLS_*`.\n\n---\n\n## CLI client\n\nScriptable **`ws:\u002F\u002F` \u002F `wss:\u002F\u002F`** client for health checks, session automation, CI validation, or operator workflows.\n\n### Local invocation\n\n```bash\nbun run apps\u002Fcli\u002Fsrc\u002Findex.ts --help\nalias craft-cli=\"bun run $(pwd)\u002Fapps\u002Fcli\u002Fsrc\u002Findex.ts\"\n```\n\n### Connection\n\n```bash\nexport CRAFT_SERVER_URL=ws:\u002F\u002F127.0.0.1:9100\nexport CRAFT_SERVER_TOKEN=\u003Ctoken>\n\ncraft-cli --url ws:\u002F\u002F127.0.0.1:9100 --token \u003Ctoken> ping\n```\n\nAttach `--tls-ca` for private CAs.\n\n### Command reference\n\n| Command | Purpose |\n|---------|---------|\n| `ping` | Latency \u002F client id probe |\n| `health` | Credential store diagnostics |\n| `versions` | Server build metadata |\n| `workspaces` \u002F `sessions` \u002F `connections` \u002F `sources` | Inventory RPCs |\n| `session create` | `--name`, `--mode` |\n| `session messages \u003Cid>` | Dump transcript |\n| `session delete \u003Cid>` | Remove session |\n| `send \u003Cid> \u003Cprompt>` | Stream assistant output |\n| `cancel \u003Cid>` | Stop generation |\n| `invoke` \u002F `listen` | Raw RPC plumbing |\n| `run \u003Cprompt>` | Ephemeral server + session + teardown |\n| `--validate-server` | 21-step integration harness |\n\n#### `run` flags (common)\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--workspace-dir` | — | Pre-register filesystem workspace |\n| `--source` | — | Repeatable source slug activation |\n| `--output-format` | `text` | `text` or `stream-json` |\n| `--mode` | `allow-all` | Permission preset |\n| `--no-cleanup` | false | Retain spawned session artifacts |\n| `--provider` | `anthropic` | `openai`, `google`, routers, etc. |\n| `--model` | provider default | e.g., `gpt-4o`, `gemini-2.0-flash` |\n| `--api-key` | env fallbacks | Explicit secret |\n| `--base-url` | — | Proxies \u002F self-hosted gateways |\n\nExamples:\n\n```bash\ncraft-cli ping\ncraft-cli sessions\ncraft-cli send abc-123 \"Summarize ~\u002Fnotes\"\ncraft-cli --json workspaces | jq '.[].name'\ncraft-cli run \"Explain this repository structure\"\ncraft-cli run --workspace-dir .\u002Fsvc --provider openai --model gpt-4o \"Lint findings\"\nCRAFT_SERVER_URL=wss:\u002F\u002F... CRAFT_SERVER_TOKEN=... craft-cli --validate-server\n```\n\n---\n\n## Architecture\n\n```\ncraft-agent\u002F\n├── apps\u002F\n│   ├── cli\u002F\n│   └── electron\u002F\n│       └── src\u002F{main,preload,renderer}\n└── packages\u002F\n    ├── core\u002F        # Shared types \u002F contracts\n    └── shared\u002F\n        └── src\u002F\n            ├── agent\u002F        # Permissions + orchestration\n            ├── auth\u002F         # Tokens \u002F OAuth UX\n            ├── config\u002F       # Themes + preferences persistence\n            ├── credentials\u002F  # AES-256-GCM bundle\n            ├── sessions\u002F     # JSONL transcripts\n            ├── sources\u002F      # MCP + REST ingestion\n            └── statuses\u002F     # Workflow metadata\n```\n\n---\n\n## Development\n\n```bash\nbun run electron:dev     # Hot reload Electron shell\nbun run electron:start   # Production-ish bundle\nbun run typecheck:all    # Type coverage\n\n# Logs (dev): ~\u002FLibrary\u002FLogs\u002F@craft-agent\u002Felectron\u002F on macOS\n```\n\n### Build-time OAuth secrets (Slack \u002F Microsoft)\n\n```bash\nMICROSOFT_OAUTH_CLIENT_ID=...\nSLACK_OAUTH_CLIENT_ID=...\nSLACK_OAUTH_CLIENT_SECRET=...\n```\n\nGoogle OAuth is **user-supplied** per workspace—see below.\n\n### Google OAuth (Gmail, Calendar, Drive, YouTube, Search Console)\n\n1. Create a project in [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com).  \n2. Enable the APIs you need (Gmail, Calendar, Drive, etc.).  \n3. Configure the **OAuth consent screen** (External + test users while in testing).  \n4. Create **Desktop** OAuth client credentials.  \n5. Provide `googleOAuthClientId` \u002F secrets via the source **`config.json`** or let the onboarding agent capture them:\n\n```json\n{\n  \"api\": {\n    \"googleService\": \"gmail\",\n    \"googleOAuthClientId\": \"*.apps.googleusercontent.com\",\n    \"googleOAuthClientSecret\": \"...\"\n  }\n}\n```\n\nNever commit plaintext secrets—Craft encrypts sourced credentials locally.\n\n---\n\n## Supported LLM providers\n\n### First-party integrations\n\n| Provider | Auth mechanisms |\n|----------|-----------------|\n| **Anthropic** | API keys, Claude Max\u002FPro OAuth |\n| **Google AI Studio** | API key (Gemini + Google Search grounding) |\n| **ChatGPT Plus \u002F Pro** | Codex OAuth surfaces |\n| **GitHub Copilot** | OAuth device flow |\n\n### Compatible gateways & self-hosted stacks\n\nRouted through configurable Anthropic-compatible or OpenAI-compatible bases:\n\n| Target | Typical base URL |\n|--------|------------------|\n| **OpenRouter** | `https:\u002F\u002Fopenrouter.ai\u002Fapi` |\n| **Vercel AI Gateway** | `https:\u002F\u002Fai-gateway.vercel.sh` |\n| **Ollama** | `http:\u002F\u002Flocalhost:11434` |\n| **Custom** | Any compatible proxy |\n\n**Runtime split:** Claude-path traffic uses **`@anthropic-ai\u002Fclaude-agent-sdk`**; Pi-path traffic handles Studio \u002F Codex \u002F Copilot integrations.\n\n---\n\n## Advanced topics\n\n### Large tool payloads\n\nResponses beyond ~60 KB are summarized with **Claude Haiku** guidance; MCP schemas include `_intent` metadata so summarization preserves operator goals.\n\n### Deep links (`craftagents:\u002F\u002F`)\n\n```\ncraftagents:\u002F\u002FallSessions\ncraftagents:\u002F\u002FallSessions\u002Fsession\u002Fsession123\ncraftagents:\u002F\u002Fsettings\ncraftagents:\u002F\u002Fsources\u002Fsource\u002Fgithub\ncraftagents:\u002F\u002Faction\u002Fnew-chat\n```\n\n### Automations (`automations.json`)\n\nDeclarative cron + hook automations stored per workspace. Example excerpt:\n\n```json\n{\n  \"version\": 2,\n  \"automations\": {\n    \"SchedulerTick\": [\n      {\n        \"cron\": \"0 9 * * 1-5\",\n        \"timezone\": \"America\u002FNew_York\",\n        \"labels\": [\"Scheduled\"],\n        \"actions\": [\n          { \"type\": \"prompt\", \"prompt\": \"Check @github for new issues assigned to me\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\nFull reference: [Automations documentation](https:\u002F\u002Fagents.craft.do\u002Fdocs\u002Fautomations\u002Foverview).\n\n---\n\n## Configuration\n\nState lives under `~\u002F.craft-agent\u002F`:\n\n```\n~\u002F.craft-agent\u002F\n├── config.json\n├── credentials.enc\n├── preferences.json\n├── theme.json\n└── workspaces\u002F\n    └── \u003Cid>\u002F\n        ├── config.json\n        ├── theme.json\n        ├── automations.json\n        ├── sessions\u002F*.jsonl\n        ├── sources\u002F\n        ├── skills\u002F\n        └── statuses\u002F\n```\n\n---\n\n## Tech stack\n\n| Layer | Choice |\n|-------|--------|\n| Runtime | [Bun](https:\u002F\u002Fbun.sh\u002F) |\n| Agents | Claude Agent SDK + Pi agent services |\n| Desktop | Electron + React |\n| UI | shadcn\u002Fui + Tailwind CSS v4 |\n| Bundler | esbuild (main), Vite (renderer) |\n\n---\n\n## Troubleshooting\n\n### Verbose packaged app logs\n\nAppend `-- --debug` **after** the binary (note the spacer):\n\n```bash\n# macOS\n\u002FApplications\u002FCraft\\ Agents.app\u002FContents\u002FMacOS\u002FCraft\\ Agents -- --debug\n\n# Windows PowerShell\n& \"$env:LOCALAPPDATA\\Programs\\@craft-agentelectron\\Craft Agents.exe\" -- --debug\n\n# Linux AppImage\u002Fbinary\n.\u002Fcraft-agents -- --debug\n```\n\n**Log locations**\n\n- macOS: `~\u002FLibrary\u002FLogs\u002F@craft-agent\u002Felectron\u002Fmain.log`  \n- Windows: `%APPDATA%\\@craft-agent\\electron\\logs\\main.log`  \n- Linux: `~\u002F.config\u002F@craft-agent\u002Felectron\u002Flogs\u002Fmain.log`  \n\n---\n\n## License\n\nLicensed under **[Apache License 2.0](LICENSE)**.\n\n### Third-party notices\n\nBundled **[Claude Agent SDK](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@anthropic-ai\u002Fclaude-agent-sdk)** usage falls under **[Anthropic Commercial Terms](https:\u002F\u002Fwww.anthropic.com\u002Flegal\u002Fcommercial-terms)**.\n\n### Trademarks\n\n“Craft” and “Craft Agents” are trademarks of **Craft Docs Ltd.** — refer to [TRADEMARK.md](TRADEMARK.md).\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Security\n\nLocal MCP subprocesses strip high-risk env vars (`ANTHROPIC_API_KEY`, cloud tokens, etc.)—whitelist per server via explicit `env` maps. Disclosure policy: [SECURITY.md](SECURITY.md).\n\n---\n\n## Appendix: discoverability cheat sheet\n\nIf you are browsing by keyword: **Electron AI assistant**, **MCP desktop client**, **Claude OAuth desktop**, **OpenAPI agent connector**, **headless AI server**, **`CRAFT_SERVER_TOKEN`**, **`craft-cli run`**, **workspace-local skills**, **JSONL transcripts**, **multi-provider LLM switcher**.\n","Craft Agents OSS 是一个基于 Claude Agent SDK 和 Pi SDK 构建的桌面和无头工作空间，专为 Claude 级别的 AI 代理设计。该项目支持多会话收件箱、多种数据源连接（包括 MCP 服务器和 OpenAPI 支持的 REST API）、可重用技能包以及与多个 LLM 提供商集成等功能。其核心特点在于通过 WebSocket 实现远程模式下的无头服务器运行，并提供 CLI 客户端以驱动会话。此外，Craft Agents 还具备自动化功能，如定时任务、标签管理和工具钩子等。此项目适用于需要在一个统一环境中管理多个 AI 代理及其交互的开发者或团队，尤其适合那些希望在日常工作中高效利用前沿模型的用户。",2,"2026-05-06 17:18:28","CREATED_QUERY"]