craft-agents-oss

Craft Agents

How it Works (Video)

To understand what Craft Agents does and how it works watch this 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.

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

One-Line Install (Recommended)

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

• Multi-Session Inbox: Desktop app with session management, status workflow, and flagging
• Claude Code Experience: Streaming responses, tool visualization, real-time updates
• Multiple LLM Connections: Add multiple AI providers and set per-workspace defaults
• Multi-Provider Support: Run sessions with Google AI Studio, ChatGPT Plus, GitHub Copilot, or OpenAI API keys alongside Anthropic
• Craft MCP Integration: Access to 32+ Craft document tools (blocks, collections, search, tasks)
• Sources: Connect to MCP servers, REST APIs (Google, Slack, Microsoft), and local filesystems
• Permission Modes: Three-level system (Explore, Ask to Edit, Auto) with customizable rules
• Background Tasks: Run long-running operations with progress tracking
• Dynamic Status System: Customizable session workflow states (Todo, In Progress, Done, etc.)
• Theme System: Cascading themes at app and workspace levels
• Multi-File Diff: VS Code-style window for viewing all file changes in a turn
• Skills: Specialized agent instructions stored per-workspace
• File Attachments: Drag-drop images, PDFs, Office documents with auto-conversion
• Automations: Event-driven automation — create agent sessions on label changes, schedules, tool use, and more

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

• Inbox/Archive: Sessions organized by workflow status
• Flagging: Mark important sessions for quick access
• Status Workflow: Todo → In Progress → Needs Review → Done
• Session Naming: AI-generated titles or manual naming
• Session Persistence: Full conversation history saved to disk

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

TLS (Recommended for Remote Access)

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