Craft Agents OSS

Desktop and headless workspace for Claude-class agents, with sources (REST APIs and Model Context Protocol / MCP servers), skills, automations, and a document-first UI. Built on the Claude Agent SDK and Pi SDK for multi-provider LLM access.

Org repository: github.com/warpdot-dev/craft-agents-oss · Upstream reference: lukilabs/craft-agents-oss

Overview (what you get)

Capability	Description
Multi-session inbox	Organize agent chats with statuses, flags, and persistence
Sources	Connect MCP servers, OpenAPI-backed REST APIs, Google / Slack / Microsoft stacks, and local filesystems
Skills	Reusable instruction packs per workspace; reference with `@` mentions
Providers	Anthropic (API + OAuth), Google AI Studio, ChatGPT Plus (Codex), GitHub Copilot, OpenAI-compatible endpoints, and more
Remote mode	Run a headless WebSocket server; use the Electron app as a thin client or drive sessions from the CLI
Automations	Cron, labels, tool hooks, and other events to spawn prompts and workflows

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.

Product tour (video)
Why Craft Agents exists
Highlights & FAQ-style capabilities
Install
Features at a glance
Quick start
Desktop: sessions, sources, permissions, shortcuts
Remote server (headless)
CLI client
Repository layout
Development & Google OAuth
Supported LLM providers
Advanced: automations, large responses, deep links
Tech stack
Troubleshooting
License, trademarks, security

Product tour (video)

Watch on YouTube →

Why Craft Agents exists

Craft Agents is the open-source app we use at Craft to work with frontier models day to day. It emphasizes:

Multitasking across many agent sessions without losing context
Connected data through APIs and MCPs—without editing stacks of config files by hand
Shared session state and a document-centric flow (less terminal-only friction)
Agent-native UX: describe intent; the product handles wiring, permissions, and skill discovery where possible

The project is Apache 2.0 so you can fork, theme, and ship custom builds. Internally we dogfood development inside Craft Agents itself.

Highlights

Connect Linear, Gmail, Slack, custom APIs, or local MCPs

Tell the agent to add a source; it can discover public APIs / MCP docs, negotiate credentials, and wire configuration. Prefer files? Paste an MCP JSON config—it is applied automatically.
Stdio MCP servers run locally (npx, Python, custom binaries).
Paste OpenAPI specs, endpoint lists, or doc screenshots—the agent proposes a workable integration surface.

Skills & live updates

Import skills from other Claude-style setups on request.
Reference skills and sources with @ mid-conversation; changes apply without restarting the app.

Deep dives (hosted examples):

Installation

One-line install (recommended)

macOS / Linux

curl -fsSL https://agents.craft.do/install-app.sh | bash

Windows (PowerShell)

irm https://agents.craft.do/install-app.ps1 | iex

Build from source

git clone https://github.com/warpdot-dev/craft-agents-oss.git
cd craft-agents-oss
bun install
bun run electron:start

Features

Multi-session inbox — session management, statuses, archiving, flagging
Streaming agent UX — tool traces, progressive responses, realtime updates
Multiple LLM connections — per-workspace defaults; mix providers thoughtfully
Multi-provider backends — Google AI Studio, ChatGPT Plus (Codex OAuth), GitHub Copilot OAuth, Anthropic Claude paths, plus OpenAI-compatible routes
Craft MCP bundle — 30+ Craft document tools (blocks, collections, tasks, search)
Sources ecosystem — MCP, REST integrations, filesystem / vault access
Permission modes — safe / ask / allow-all with granular policies
Background jobs — long-running tasks with visible progress
Custom statuses — Kanban-like workflow states
Theming — app-level and workspace-level themes
Multi-file diff — review edits across files in one pass
Attachments — images, PDFs, Office docs with conversion helpers
Automations — schedules, label changes, tool hooks, lifecycle events

Quick start

Launch the desktop app after install.
Connect an LLM: Anthropic (API key / subscription OAuth), Google AI Studio, Codex-backed ChatGPT, GitHub Copilot, or configured OpenAI-compatible endpoints.
Create a workspace to isolate sessions, skills, and sources.
Attach sources (optional): MCP, REST APIs, or local folders.
Open a session and start prompting; escalate permissions (SHIFT+TAB) when you intentionally need writes.

Desktop app features

Session management

Inbox / archive with workflow columns
Flagging for follow-ups
Statuses (Todo → In Progress → Needs Review → Done, customizable)
AI / manual naming plus durable JSONL history

Sources

Type	Examples
MCP	Craft, Linear, GitHub, Notion, bespoke servers
REST APIs	Google Workspace, Slack, Microsoft Graph
Local	Filesystem roots, Obsidian vaults, git checkouts

Permission modes

Internal ID	Label	Behaviour
`safe`	Explore	Read-only; blocks mutating operations
`ask`	Ask to edit	Confirmation gates (default)
`allow-all`	Auto	Auto-approves tooling

Press SHIFT+TAB inside chat to rotate modes.

Keyboard shortcuts

Shortcut	Action
`Cmd+N`	New chat
`Cmd+1/2/3`	Focus sidebar / list / transcript
`Cmd+/`	Shortcut cheat sheet
`SHIFT+TAB`	Cycle permission modes
`Enter`	Send
`Shift+Enter`	New line

Remote server (headless)

Run logic on a Linux VPS, home lab, or CI runner while controlling it from Electron or automation.

Start the server

CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

Copy the emitted CRAFT_SERVER_URL and CRAFT_SERVER_TOKEN.

Thin-client Electron shell

CRAFT_SERVER_URL=wss://203.0.113.5:9100 CRAFT_SERVER_TOKEN=<token> bun run electron:start

Environment variables

Variable	Required	Default	Notes
`CRAFT_SERVER_TOKEN`	✅	—	Bearer token presented by clients
`CRAFT_RPC_HOST`		`127.0.0.1`	Set `0.0.0.0` for remote NIC binding
`CRAFT_RPC_PORT`		`9100`	Plain / TLS WebSocket port
`CRAFT_RPC_TLS_CERT`		—	PEM cert path (`wss://`)
`CRAFT_RPC_TLS_KEY`		—	PEM private key
`CRAFT_RPC_TLS_CA`		—	Optional client verification chain
`CRAFT_DEBUG`		`false`	Verbose RPC logging

TLS quick path

./scripts/generate-dev-cert.sh
CRAFT_SERVER_TOKEN=<token> \
CRAFT_RPC_HOST=0.0.0.0 \
CRAFT_RPC_TLS_CERT=certs/cert.pem \
CRAFT_RPC_TLS_KEY=certs/key.pem \
bun run packages/server/src/index.ts

For production place trusted certificates or terminate TLS behind nginx, Caddy, or similar.

Docker sketch

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=<token> \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

Mount cert/key volumes when enabling CRAFT_RPC_TLS_*.

CLI client

Scriptable ws:// / wss:// client for health checks, session automation, CI validation, or operator workflows.

Local invocation

bun run apps/cli/src/index.ts --help
alias craft-cli="bun run $(pwd)/apps/cli/src/index.ts"

Connection

export CRAFT_SERVER_URL=ws://127.0.0.1:9100
export CRAFT_SERVER_TOKEN=<token>

craft-cli --url ws://127.0.0.1:9100 --token <token> ping

Attach --tls-ca for private CAs.

Command reference

Command	Purpose
`ping`	Latency / client id probe
`health`	Credential store diagnostics
`versions`	Server build metadata
`workspaces` / `sessions` / `connections` / `sources`	Inventory RPCs
`session create`	`--name`, `--mode`
`session messages <id>`	Dump transcript
`session delete <id>`	Remove session
`send <id> <prompt>`	Stream assistant output
`cancel <id>`	Stop generation
`invoke` / `listen`	Raw RPC plumbing
`run <prompt>`	Ephemeral server + session + teardown
`--validate-server`	21-step integration harness

`run` flags (common)

Flag	Default	Description
`--workspace-dir`	—	Pre-register filesystem workspace
`--source`	—	Repeatable source slug activation
`--output-format`	`text`	`text` or `stream-json`
`--mode`	`allow-all`	Permission preset
`--no-cleanup`	false	Retain spawned session artifacts
`--provider`	`anthropic`	`openai`, `google`, routers, etc.
`--model`	provider default	e.g., `gpt-4o`, `gemini-2.0-flash`
`--api-key`	env fallbacks	Explicit secret
`--base-url`	—	Proxies / self-hosted gateways

Examples:

craft-cli ping
craft-cli sessions
craft-cli send abc-123 "Summarize ~/notes"
craft-cli --json workspaces | jq '.[].name'
craft-cli run "Explain this repository structure"
craft-cli run --workspace-dir ./svc --provider openai --model gpt-4o "Lint findings"
CRAFT_SERVER_URL=wss://... CRAFT_SERVER_TOKEN=... craft-cli --validate-server

Architecture

craft-agent/
├── apps/
│   ├── cli/
│   └── electron/
│       └── src/{main,preload,renderer}
└── packages/
    ├── core/        # Shared types / contracts
    └── shared/
        └── src/
            ├── agent/        # Permissions + orchestration
            ├── auth/         # Tokens / OAuth UX
            ├── config/       # Themes + preferences persistence
            ├── credentials/  # AES-256-GCM bundle
            ├── sessions/     # JSONL transcripts
            ├── sources/      # MCP + REST ingestion
            └── statuses/     # Workflow metadata

Development

bun run electron:dev     # Hot reload Electron shell
bun run electron:start   # Production-ish bundle
bun run typecheck:all    # Type coverage

# Logs (dev): ~/Library/Logs/@craft-agent/electron/ on macOS

Build-time OAuth secrets (Slack / Microsoft)

MICROSOFT_OAUTH_CLIENT_ID=...
SLACK_OAUTH_CLIENT_ID=...
SLACK_OAUTH_CLIENT_SECRET=...

Google OAuth is user-supplied per workspace—see below.

Google OAuth (Gmail, Calendar, Drive, YouTube, Search Console)

Create a project in Google Cloud Console.
Enable the APIs you need (Gmail, Calendar, Drive, etc.).
Configure the OAuth consent screen (External + test users while in testing).
Create Desktop OAuth client credentials.
Provide googleOAuthClientId / secrets via the source config.json or let the onboarding agent capture them:

{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "*.apps.googleusercontent.com",
    "googleOAuthClientSecret": "..."
  }
}

Never commit plaintext secrets—Craft encrypts sourced credentials locally.

Supported LLM providers

First-party integrations

Provider	Auth mechanisms
Anthropic	API keys, Claude Max/Pro OAuth
Google AI Studio	API key (Gemini + Google Search grounding)
ChatGPT Plus / Pro	Codex OAuth surfaces
GitHub Copilot	OAuth device flow

Compatible gateways & self-hosted stacks

Routed through configurable Anthropic-compatible or OpenAI-compatible bases:

Target	Typical base URL
OpenRouter	`https://openrouter.ai/api`
Vercel AI Gateway	`https://ai-gateway.vercel.sh`
Ollama	`http://localhost:11434`
Custom	Any compatible proxy

Runtime split: Claude-path traffic uses @anthropic-ai/claude-agent-sdk; Pi-path traffic handles Studio / Codex / Copilot integrations.

Advanced topics

Large tool payloads

Responses beyond ~60 KB are summarized with Claude Haiku guidance; MCP schemas include _intent metadata so summarization preserves operator goals.

Deep links (`craftagents://`)

craftagents://allSessions
craftagents://allSessions/session/session123
craftagents://settings
craftagents://sources/source/github
craftagents://action/new-chat

Automations (`automations.json`)

Declarative cron + hook automations stored per workspace. Example excerpt:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Check @github for new issues assigned to me" }
        ]
      }
    ]
  }
}

Full reference: Automations documentation.

Configuration

State lives under ~/.craft-agent/:

~/.craft-agent/
├── config.json
├── credentials.enc
├── preferences.json
├── theme.json
└── workspaces/
    └── <id>/
        ├── config.json
        ├── theme.json
        ├── automations.json
        ├── sessions/*.jsonl
        ├── sources/
        ├── skills/
        └── statuses/

Tech stack

Layer	Choice
Runtime	Bun
Agents	Claude Agent SDK + Pi agent services
Desktop	Electron + React
UI	shadcn/ui + Tailwind CSS v4
Bundler	esbuild (main), Vite (renderer)

Troubleshooting

Verbose packaged app logs

Append -- --debug after the binary (note the spacer):

# macOS
/Applications/Craft\ Agents.app/Contents/MacOS/Craft\ Agents -- --debug

# Windows PowerShell
& "$env:LOCALAPPDATA\Programs\@craft-agentelectron\Craft Agents.exe" -- --debug

# Linux AppImage/binary
./craft-agents -- --debug

Log locations

macOS: ~/Library/Logs/@craft-agent/electron/main.log
Windows: %APPDATA%\@craft-agent\electron\logs\main.log
Linux: ~/.config/@craft-agent/electron/logs/main.log

License

Licensed under Apache License 2.0.

Third-party notices

Bundled Claude Agent SDK usage falls under Anthropic Commercial Terms.

Trademarks

“Craft” and “Craft Agents” are trademarks of Craft Docs Ltd. — refer to TRADEMARK.md.

Contributing

See CONTRIBUTING.md.

Security

Local MCP subprocesses strip high-risk env vars (ANTHROPIC_API_KEY, cloud tokens, etc.)—whitelist per server via explicit env maps. Disclosure policy: SECURITY.md.

Appendix: discoverability cheat sheet

If 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.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.github		.github
apps		apps
docs		docs
packages		packages
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.server		Dockerfile.server
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
TRADEMARK.md		TRADEMARK.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Craft Agents OSS

Overview (what you get)

Table of contents

Product tour (video)

Why Craft Agents exists

Highlights

Installation

One-line install (recommended)

Build from source

Features

Quick start

Desktop app features

Session management

Sources

Permission modes

Keyboard shortcuts

Remote server (headless)

Start the server

Thin-client Electron shell

Environment variables

TLS quick path

Docker sketch

CLI client

Local invocation

Connection

Command reference

run flags (common)

Architecture

Development

Build-time OAuth secrets (Slack / Microsoft)

Google OAuth (Gmail, Calendar, Drive, YouTube, Search Console)

Supported LLM providers

First-party integrations

Compatible gateways & self-hosted stacks

Advanced topics

Large tool payloads

Deep links (craftagents://)

Automations (automations.json)

Configuration

Tech stack

Troubleshooting

Verbose packaged app logs

License

Third-party notices

Trademarks

Contributing

Security

Appendix: discoverability cheat sheet

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`run` flags (common)

Deep links (`craftagents://`)

Automations (`automations.json`)

Packages