craft-agents-oss README

The project's README from github.com/craft-ai-agents/craft-agents-oss. As one markdown file: README.md.

craft-ai-agents%2Fcraft-agents-oss | Trendshift

Craft Agents

License Contributor Covenant

How it Works (Video)

To understand what Craft Agents does and how it works watch this video.

Demo Video

Click Here (or on the image above) to watch the video on YouTube →

Why Craft Agents was built

Craft Agents is a tool we built so that we (at craft.do) can work effectively with agents. It enables intuitive multitasking, no-fluff connection to any API or Service, sharing sessions, and a more document (vs code) centric workflow - in a beautiful and fluid UI.

It uses the Claude Agent SDK and the Pi SDK side by side—building on what we found great and improving areas where we've desired improvements.

It's built with Agent Native software principles in mind, and is highly customisable out of the box. One of the first of its kind.

Craft Agents is open source under the Apache 2.0 license - so you are free to remix, change anything. And that's actually possible. We ourselves are building Craft Agents with Craft Agents only - no code editors - so really, any customisation is just a prompt away.

We built Craft Agents because we wanted a better, more opinionated (and preferably non-CLI way) of working with the most powerful agents in the world. We'll continue to improve it, based on our experiences and intuition.

image

Things that are hard to believe "just work"

How do I connect to Linear, Gmail, Slack...? Tell the agent "add Linear as a source." It finds public APIs and MCP servers, reads their docs, sets up credentials, and configures everything. No config files, no setup wizards.

Check out how I just connected to Slack →

I already have my MCP config JSON. Paste it. The agent handles the rest.

What about local MCPs? Fully supported. Stdio-based MCP servers run as local subprocesses on your machine. Point it at an npx command, a Python script, or any local binary. It just works.

Can it handle custom APIs? Yes. Paste an OpenAPI spec, some endpoint URLs, screenshots of docs, whatever you have. It figures it out and guides you through the rest.

APIs too? Not just MCPs? Craft Agents connects to anything. We have it hooked up to a direct Postgres DB behind a jumpbox. Skills + Sources = magic.

How do I import my Claude Code skills and MCPs? Tell the agent you want to import your skills from Claude Code. It handles the migration.

Here I imported all my skills in one go →

How do I create a new skill? Describe what the skill should do, give it context. The agent takes care of the rest.

Do I need to restart after changes? No. Everything is instant. Mention new skills or sources with @, even mid-conversation.

So I can just ask it anything? Yes. That's the core idea behind agent-native software. You describe what you want, and it figures out how. That's a good use of tokens.

Installation

macOS / Linux:

curl -fsSL https://thecraftagents.com/install-app.sh | bash

Windows (PowerShell):

irm https://thecraftagents.com/install-app.ps1 | iex

Build from Source

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

Features

Quick Start

  1. Launch the app after installation
  2. Choose API Connection: Use Anthropic (API key or Claude Max), Google AI Studio, ChatGPT Plus (Codex OAuth), or GitHub Copilot OAuth
  3. Create a workspace: Set up a workspace to organize your sessions
  4. Connect sources (optional): Add MCP servers, REST APIs, or local filesystems
  5. Start chatting: Create sessions and interact with Claude

Desktop App Features

Session Management

Sources

Connect external data sources to your workspace:

Type Examples
MCP Servers Craft, Linear, GitHub, Notion, custom servers
REST APIs Google (Gmail, Calendar, Drive, YouTube, Search Console), Slack, Microsoft
Local Files Filesystem, Obsidian vaults, Git repos

Permission Modes

Mode Display Behavior
safe Explore Read-only, blocks all write operations
ask Ask to Edit Prompts for approval (default)
allow-all Auto Auto-approves all commands

Use SHIFT+TAB to cycle through modes in the chat interface.

Keyboard Shortcuts

Shortcut Action
Cmd+N New chat
Cmd+1/2/3 Focus sidebar/list/chat
Cmd+/ Keyboard shortcuts dialog
SHIFT+TAB Cycle permission modes
Enter Send message
Shift+Enter New line

Remote Server (Headless)

Craft Agents can run as a headless server on a remote machine (e.g., a Linux VPS), with the desktop app connecting as a thin client. This lets you keep long-running sessions alive, access them from multiple machines, and run compute-heavy tasks on a powerful server.

Quick Start

From the monorepo root:

# Generate a token and start the server
CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

The server prints the connection details on startup:

CRAFT_SERVER_URL=ws://203.0.113.5:9100
CRAFT_SERVER_TOKEN=<generated-token>

Copy these values and use them to connect the desktop app.

Connecting the Desktop App

Launch the Electron app in thin-client mode by passing the server URL and token:

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

In thin-client mode, the desktop app renders the UI but all session logic, tool execution, and LLM calls run on the remote server.

Environment Variables

Variable Required Default Description
CRAFT_SERVER_TOKEN Yes — Bearer token for client authentication
CRAFT_RPC_HOST No 127.0.0.1 Bind address (0.0.0.0 for remote access)
CRAFT_RPC_PORT No 9100 Bind port
CRAFT_RPC_TLS_CERT No — Path to PEM certificate file (enables wss://)
CRAFT_RPC_TLS_KEY No — Path to PEM private key file (required with cert)
CRAFT_RPC_TLS_CA No — Path to PEM CA chain file (optional, for client cert verification)
CRAFT_DEBUG No false Enable debug logging

When exposing the server over the network, TLS encrypts the WebSocket connection (wss:// instead of ws://).

Generate a self-signed certificate (development/testing):

./scripts/generate-dev-cert.sh
# Creates certs/cert.pem and certs/key.pem (valid 365 days)

Start the server with TLS:

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

The server will print CRAFT_SERVER_URL=wss://<your-public-ip>:9100.

For production, use certificates from a trusted CA (e.g., Let's Encrypt) or place the server behind a reverse proxy (nginx, Caddy) that terminates TLS.

Docker

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

To enable TLS in Docker, mount your certificates and set the env vars:

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=<token> \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem \
  -e CRAFT_RPC_TLS_KEY=/certs/key.pem \
  -v ./certs:/certs:ro \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

CLI Client

A terminal client that connects to a running Craft Agent server over WebSocket (ws:// or wss://). Use it for scripting, CI/CD pipelines, server validation, or when you prefer the command line.

Installation

# From the monorepo (requires Bun)
bun run apps/cli/src/index.ts --help

# Or add to your PATH
alias craft-cli="bun run $(pwd)/apps/cli/src/index.ts"

Connection

The CLI reads connection details from flags or environment variables:

# Via environment (set once)
export CRAFT_SERVER_URL=ws://127.0.0.1:9100
export CRAFT_SERVER_TOKEN=<your-token>

# Or via flags
craft-cli --url ws://127.0.0.1:9100 --token <token> ping

For TLS connections (wss://), use --tls-ca <path> for self-signed certificates.

Commands

Command Description
ping Verify connectivity (clientId + latency)
health Check credential store health
versions Show server runtime versions
workspaces List workspaces
sessions List sessions in workspace
connections List LLM connections
sources List configured sources
session create Create a session (--name, --mode)
session messages <id> Print session message history
session delete <id> Delete a session
send <id> <message> Send message and stream AI response
cancel <id> Cancel in-progress processing
invoke <channel> [args] Raw RPC call with JSON args
listen <channel> Subscribe to push events (Ctrl+C to stop)
run <prompt> Self-contained: spawn server, run prompt, stream response, exit
--validate-server 21-step integration test (auto-spawns server if no --url)

Run Command Flags

Flag Default Description
--workspace-dir <path> — Register a workspace directory before running
--source <slug> — Enable a source (repeatable)
--output-format <fmt> text Output format: text or stream-json
--mode <mode> allow-all Permission mode for the session
--no-cleanup false Skip session deletion on exit
--server-entry <path> — Custom server entry point
--provider <name> anthropic LLM provider (anthropic, openai, google, openrouter, groq, mistral, xai, etc.)
--model <id> (provider default) Model ID (e.g., claude-sonnet-4-5-20250929, gpt-4o, gemini-2.0-flash)
--api-key <key> — API key (or $LLM_API_KEY, or provider-specific env var)
--base-url <url> — Custom API endpoint for proxies or self-hosted models

The run command is fully self-contained — it spawns a headless server, creates a session, sends the prompt, streams the response, and exits. No separate server setup needed. An API key is resolved from --api-key, $LLM_API_KEY, or a provider-specific env var (e.g., $ANTHROPIC_API_KEY, $OPENAI_API_KEY).

Examples

# Quick connectivity check
craft-cli ping

# List sessions (human-readable)
craft-cli sessions

# Send a message and stream the AI response
craft-cli send abc-123 "What files are in the current directory?"

# Pipe input
echo "Summarize this" | craft-cli send abc-123

# JSON output for scripting
craft-cli --json workspaces | jq '.[].name'

# Self-contained run (spawns its own server)
craft-cli run "Summarize the README"
craft-cli run --workspace-dir ./my-project --source github "List open PRs"

# Multi-provider support
craft-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash "Hello"
craft-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

# Validate the server (auto-spawns if no --url)
craft-cli --validate-server
craft-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

Architecture

craft-agent/
├── apps/
│   ├── cli/                   # Terminal client (CLI)
│   └── electron/              # Desktop GUI (primary)
│       └── src/
│           ├── main/          # Electron main process
│           ├── preload/       # Context bridge
│           └── renderer/      # React UI (Vite + shadcn)
└── packages/
    ├── core/                  # Shared types
    └── shared/                # Business logic
        └── src/
            ├── agent/         # CraftAgent, permissions
            ├── auth/          # OAuth, tokens
            ├── config/        # Storage, preferences, themes
            ├── credentials/   # AES-256-GCM encrypted storage
            ├── sessions/      # Session persistence
            ├── sources/       # MCP, API, local sources
            └── statuses/      # Dynamic status system

Development

# Hot reload development
bun run electron:dev

# Build and run
bun run electron:start

# Type checking
bun run typecheck:all

# Debug logging (writes to ~/Library/Logs/@craft-agent/electron/)
# Logs are automatically enabled in development

Environment Variables

OAuth integrations (Slack, Microsoft) require credentials baked into the build. Create a .env file:

MICROSOFT_OAUTH_CLIENT_ID=your-client-id
SLACK_OAUTH_CLIENT_ID=your-slack-client-id
SLACK_OAUTH_CLIENT_SECRET=your-slack-client-secret

Note: Google OAuth credentials are NOT baked into the build. Users provide their own credentials via source configuration. See the Google OAuth Setup section below.

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

Google integrations require you to create your own OAuth credentials. This is a one-time setup.

1. Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project (or select an existing one)
  3. Note your Project ID

2. Enable Required APIs

Go to APIs & Services → Library and enable the APIs you need:

  1. Go to APIs & Services → OAuth consent screen
  2. Select External user type (unless you have Google Workspace)
  3. Fill in required fields:
    • App name: e.g., "My Craft Agent"
    • User support email: your email
    • Developer contact: your email
  4. Add scopes (optional - can leave default)
  5. Add yourself as a test user (required for External apps in testing mode)
  6. Complete the wizard

4. Create OAuth Credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth Client ID
  3. Application type: Web application (not "Desktop app" — Craft Agent routes every OAuth flow through a hosted callback, which a Desktop-app client rejects with redirect_uri_mismatch)
  4. Name: e.g., "Craft Agent"
  5. Under Authorized redirect URIs, add: https://thecraftagents.com/auth/callback
  6. Click Create
  7. Note the Client ID and Client Secret

5. Configure in Craft Agent

When setting up a Google source (Gmail, Calendar, Drive, YouTube, Search Console, etc.), add these fields to your source's config.json:

{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "your-client-id.apps.googleusercontent.com",
    "googleOAuthClientSecret": "your-client-secret"
  }
}

Or simply tell the agent you want to connect Gmail/Calendar/Drive - it will guide you through entering your credentials.

Security Notes

Supported LLM Providers

Craft Agents supports multiple ways to connect to LLM providers:

Direct Connections

Provider Auth Notes
Anthropic API key or Claude Max/Pro OAuth Direct Claude connection via the Claude Agent SDK
Google AI Studio API key Gemini models with native Google Search grounding built in
ChatGPT Plus / Pro Codex OAuth Sign in with your ChatGPT subscription — uses OpenAI's Codex models
GitHub Copilot OAuth (device code) One-click authentication with your Copilot subscription

Third-Party & Self-Hosted Providers

Additional providers are supported through the Claude / Anthropic API Key connection by choosing a custom endpoint:

Provider Endpoint Notes
OpenRouter https://openrouter.ai/api Access Claude, GPT, Llama, Gemini, and hundreds of other models through a single API key. Use provider/model-name format (e.g. anthropic/claude-opus-4.7).
Vercel AI Gateway https://ai-gateway.vercel.sh Route requests through Vercel's AI Gateway with built-in observability and caching.
Ollama http://localhost:11434 Run open-source models locally. No API key required.
Custom Any URL Any OpenAI-compatible or Anthropic-compatible endpoint.

Architecture

Craft Agents uses two agent backends:

Configuration

Configuration is stored at ~/.craft-agent/:

~/.craft-agent/
├── config.json              # Main config (workspaces, LLM connections)
├─�

craft-agents-oss (craft-ai-agents/craft-agents-oss)

Searching Database…

7.3K ·GitHub
Craft-agents-oss
这是什么？Craft Agents 是由 Craft.do 团队开发的开源桌面应用，让你以文档为中心、无需命令行，就能与 Claude 等 AI 智能体协作。它同时使用 Claude Agent SDK 和 Pi SDK。
它只是一个桌面应用吗？还有命令行工具和 SDK 吗？它主要是一个 Electron 桌面应用，但也提供终端命令行客户端和无界面的服务器模式。会话既可以在本机运行，也可以在远程机器上运行，桌面应用则作为轻量客户端连接过去。
怎么把它跑起来？可以用 macOS/Linux 的一键安装脚本，或 Windows 上的 PowerShell 命令安装（也可以在 monorepo 中从源码构建）。然后启动应用，选择 AI 服务商，创建工作区，就可以开始对话了。
用它必须要有 Anthropic API 密钥吗？不一定。你可以通过 Anthropic（API 密钥或 Claude Max）、Google AI Studio、ChatGPT Plus（Codex OAuth）或 GitHub Copilot OAuth 连接，只需准备你所选服务商的凭据即可。
Google 集成（Gmail、日历、云端硬盘）开箱即用吗？不是。与 Slack 或 Microsoft 不同，Google 的 OAuth 凭据没有内置在构建版本中。因此在连接这些数据源之前，你需要先自己创建 Google Cloud 的 OAuth 客户端。
我连接的服务凭据存放在哪里？已连接数据源的凭据（包括 Google OAuth 令牌）都以加密形式存储在你自己的电脑上。
这和直接在终端里用 Claude Code 有什么区别？Craft Agents 放弃了纯命令行的工作方式，提供以文档为中心的桌面界面，包括多会话收件箱、可视化差异对比，以及拖放添加文件。底层仍然运行在 Claude Agent SDK 之上。
怎么连接 Slack 这类服务或自定义数据库？直接告诉智能体即可，例如“添加 Linear 作为数据源”。它会自己找到公开 API 或 MCP 服务器，阅读文档，并自行配置凭据。粘贴的 OpenAPI 规范、原始接口地址，甚至直接连接 Postgres 数据库，它也都能处理。
我能把现有的 Claude Code 技能和 MCP 服务器迁移过来吗？可以。告诉智能体你想从 Claude Code 导入技能，它会自动为你完成迁移。
能让长时间运行的会话在服务器上持续跑，我只用笔记本连接吗？可以。Craft Agents 支持无界面的远程服务器模式（例如在 Linux VPS 上运行）。桌面应用通过 WebSocket 以轻量客户端的方式连接，长时间的会话可以持续运行，繁重的计算则在服务器端完成。
What are similar projects?evenfire, ruflo, claude-code, trueforge, casbin-gateway, brigade, qwen-code, hermes-agent
Which topics is it in?vps, node, oauth, websocket, model-context-protocol, electron, skills, agentic-ai, gemini, sdk, anthropic, mcp-server
Creator
craft-ai-agents
Size
102.2 MB
Stars
7.3K
Updated
CommitOct 16Releasev0.15.3Oct 16
Age
8mo
Commits · 90 Days