Craft Agents: The Desktop Claude You Can Actually Work With

A no-fluff, step-by-step field guide for college-level readers

1. What problem are we solving?

You already know Claude is useful.
The headache starts when you need it to:

  • read 30 local files without copy-paste
  • save changes back to disk
  • keep each project in its own lane
  • run while your VPN is down

Craft Agents wraps Claude in a desktop shell and gives it a file system, a session manager and a permission gate.
Everything happens on your machine; the cloud only sees the API calls you choose.

2. Is Craft Agents “just another Claude wrapper”?

No.
Typical wrappers add a pretty chat box.
Craft adds:

Layer What you get
Session inbox Todo → In-Progress → Done workflow, flags, archive
Sources MCP servers, REST APIs, local folders in one menu
Permissions Safe / Ask / Allow-all switch, per turn
Diff viewer VS-Code-style side-by-side before you commit
Background jobs Long tasks keep running while you start new chats
Themes App-level + workspace-level cascading JSON files

Result: Claude stops being a fancy search bar and becomes a co-worker who can type, click and commit.

3. One-line install (macOS, Linux, Windows)

Copy-paste the line for your OS, hit Enter, done.

macOS / Linux

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

Windows (PowerShell 5.1 or newer)

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

Installer places the binary in $HOME/Applications (macOS/Linux) or %LOCALAPPDATA%\CraftAgents (Windows).
No admin rights required; portable folder structure lets you move it later.

4. First-run checklist (3 minutes)

  1. Launch → pick “Use your own Anthropic API key”
    (Grab a key at console.anthropic.com; $5 credit lasts weeks.)
  2. Create a workspace – call it “experiments” or whatever.
  3. Leave “Sources” empty for now; you can add GitHub or Google later.
  4. Send a test message to confirm streaming works.

That is literally it.
No phone number, no waiting list, no subscription lock-in.

5. UI map: where things live

┌────────────── Sidebar ───────────────┐
│ 1. Inbox / Archive toggle            │
│ 2. Session list with status badges   │
│ 3. +New  │ Settings │ Themes         │
└──────────────────────────────────────┘
┌────────────── Center ────────────────┐
│ Chat area                            │
│ (Shift+Enter = new line)             │
└──────────────────────────────────────┘
┌────────────── Footer ────────────────┐
│ Permission lamp: green-yellow-red    │
│ Background task spinner              │
└──────────────────────────────────────┘

Keyboard shortcuts worth muscle memory:

Keys Action
Ctrl/Cmd + N new session
Ctrl/Cmd + 1/2/3 focus sidebar / list / chat
Shift + Tab cycle permission mode
Ctrl/Cmd + / show all shortcuts

6. Walk-through 1: edit a README without copy-paste

Goal: translate README.md to Chinese, save as README.zh.md, see the diff.

Steps

  1. Drag the project folder onto “Sources” → choose “Local file system”.
  2. Type:

    Please translate README.md into Chinese, keep the Markdown formatting, and save the result as README.zh.md.

  3. Lamp turns yellow → press Y to allow the write.
  4. Click the file-diff icon that appears in the chat footer; green/red side-by-side pops up.
  5. Not happy? Ask for tweaks; each new write creates a new diff.

Behind the scenes

  • Files larger than ~60 kB are auto-summarised by Claude Haiku so the main agent receives a concise context.
  • Every write is logged as JSONL in ~/.craft-agent/workspaces/{id}/sessions/; you can grep it later.

7. Walk-through 2: batch-update 50 JSON files

Scenario: bump "version" from 1.0.0 → 1.0.1 in all config*.json files.

Prompt

Recursively find every config*.json in this workspace, change the version field to 1.0.1, save in place, and print a list of modified files.

Craft will:

  • show the file list before changing anything
  • apply edits
  • generate rollback.sh (or .bat) that reverts the commit hash-like renames

Safety tip: keep the permission lamp on yellow; you still approve each turn but avoid typing “yes” 50 times.

8. Connecting external data (Google, Slack, GitHub…)

Craft speaks three “languages”:

Protocol Typical services Setup time
MCP (Model Context Protocol) GitHub, Notion, Obsidian, custom 1 min, paste token
REST/OAuth Gmail, Calendar, Drive, Slack 3 min, login once
Local folder any directory or Git repo 0 min, drag-drop

Example: pull last 5 open issues from a repo

  1. Sources → Add → GitHub (MCP) → paste classic token → save.
  2. New session → prompt:

    Get the latest 5 open issues from craft-do/craft-agents-oss, output a Markdown table with columns: number, title, author, labels.

You now have a refreshable report; rerun the prompt any morning.

9. Permission modes demystified

Lamp Mode Meaning Use case
🟢 safe read-only browsing, Q&A
🟡 ask prompt before each write default, recommended
🔴 allow-all auto-approve every tool call CI, bulk scripts

You can switch mid-conversation; the change applies to the next turn.
Craft also filters sensitive env-vars (AWS, GitHub, Anthropic keys) when it spawns local MCP servers, so credentials do not leak to third-party processes.

10. Where is my data stored?

Everything lives under ~/.craft-agent/ (Windows: %USERPROFILE%\.craft-agent\):

.craft-agent/
├── config.json              // workspaces, auth type
├── credentials.enc          // AES-256-GCM encrypted
├── preferences.json         // UI state
├── theme.json               // global theme
└── workspaces/
    └── {uuid}/
        ├── config.json
        ├── theme.json
        ├── sessions/        // *.jsonl, one per chat
        ├── sources/         // MCP configs, OAuth tokens
        ├── skills/          // custom system prompts
        └── statuses/        // workflow labels (Todo, Done…)

Sessions are plain JSONL; you can back them up with Git, rsync, or Time Machine.
Deleting a workspace folder removes all traces—no cloud ghost copies.

11. Large response handling

When a tool returns >60 kB (e.g., a big log), Craft injects an _intent field into the schema and asks Claude Haiku to produce a concise summary.
The main agent still sees the full context if needed, but the chat UI stays snappy.
You can raise or lower the threshold in preferences.json (key: summaryThreshold).

12. Deep-linking: open a session from anywhere

External apps or browser bookmarks can jump directly:

craftagents://allChats                      # open app, all-chats view
craftagents://allChats/chat/{sessionId}     # specific session
craftagents://settings                      # preferences pane
craftagents://sources/source/github         # edit GitHub source
craftagents://action/new-chat               # blank session

Use them in Alfred, Raycast, or your own automation scripts.

13. Themes and branding

Themes cascade:

  1. App-level theme.json
  2. Workspace-level theme.json (optional override)
  3. Session-level temporary tweaks (via /theme command)

Colors use Tailwind CSS v4 names; you can change radius, font family, even sidebar width.
Share a theme by copying the JSON file—no rebuild required.

14. Keyboard-only flow

If you prefer typing to pointing:

Task Sequence
New session Ctrl/Cmd + N
Rename session Ctrl/Cmd + R
Toggle sidebar Ctrl/Cmd + 1
Focus chat Ctrl/Cmd + 3
Cycle permission Shift + Tab
Open diff Ctrl/Cmd + D (after a file change)

All shortcuts are in Ctrl/Cmd + / cheat-sheet; print it once, thank yourself later.

15. Background tasks

Long-running commands (transcribing 200 audio files, cloning a fat repo) continue after you start a new chat.
A spinner in the footer shows live progress; click it to jump back to the controlling session.
Results are streamed to disk first, then summarised in chat, so you can safely quit the app and resume later.

16. Diff viewer: trust, but verify

Every file change appears as a collapsible card with:

  • old/new line count
  • syntax highlighting
  • toggle for unified or side-by-side
  • “Revert hunk” button (works like VS Code)

If the agent creates new files, they show up green; deletes are red.
You can copy the patch as raw .patch text and email it to a teammate who doesn’t use Craft.

17. Skills: store custom instructions per workspace

A “skill” is a Markdown file dropped into workspace/{id}/skills/.
Example: blog-proofreader.md

You are a blog proof-reader. Fix grammar, keep US spelling, and add alt text to images.

In any session type /skill blog-proofreader to load it.
Skills are version-controlled alongside sessions, so you can rollback a bad instruction.

18. Session export / import

Right-click any session → Export → .craftsession file.
The archive contains:

  • full message history (JSONL)
  • referenced files (base64)
  • used skills & themes snapshots

Your peer drags the file into their Inbox; Craft restores the exact context.
No API re-run, no cost, no “file not found” errors.

19. Building from source (optional)

If you want the absolute latest commit or need to patch Electron flags:

git clone https://github.com/lukilabs/craft-agents-oss.git
cd craft-agents-oss
bun install
bun run electron:dev      # hot reload
bun run electron:start    # production build

Requirements: Node ≥ 20, Bun ≥ 1.1, Python 3 (for node-gyp rebuilds).
The repo is Apache 2.0; fork and change anything—Craft itself is dog-food-developed inside Craft without external IDEs.

20. Environment variables for OAuth

Create .env in the repo root (dev) or ~/.craft-agent/.env (binary install):

MICROSOFT_OAUTH_CLIENT_ID=xxxxxxxx
MICROSOFT_OAUTH_CLIENT_SECRET=xxxx
GOOGLE_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=xxxx
SLACK_OAUTH_CLIENT_ID=xxxx
SLACK_OAUTH_CLIENT_SECRET=xxxx

Craft ships the OAuth redirect URI already; you only need to paste the credentials.
Keys are encrypted at rest; the plain-text .env file is wiped after import.

21. Security notes

  • Local MCP servers run in a stripped environment; AWS, GitHub, Anthropic keys are removed before spawn.
  • Credentials file uses AES-256-GCM with a key derived from your login password.
  • No analytics, no crash telemetry, no Mixpanel.
  • Code-sign certificates: Windows (EV), macOS (Apple notary), Linux (PGP signature in releases).

22. Troubleshooting corner

Symptom Fix
App will not start Delete ~/.craft-agent/gpu-cache folder (bad GPU blacklist)
Claude replies garbled Check VPN MTU; streaming chunks can fragment
OAuth redirect loops Ensure localhost:4455 is not grabbed by another service
High idle CPU Turn off “Index local files” in Settings → Sources
Missing menu bar Ctrl/Cmd + Shift + M toggles it; on Windows it follows system “hide title bar”

Still stuck? Open ~/Library/Logs/Craft Agents/ (macOS), %APPDATA%\Craft Agents\logs (Win), or ~/.local/share/Craft Agents/logs (Linux).
Debug logs are always verbose in dev builds.

23. Roadmap snapshot (from public repo issues)

  • Plugin marketplace for community MCP servers
  • Agent scheduling (run session every hour)
  • Built-in vector DB for semantic search across sessions
  • Terminal multiplexer (tmux-style tabs inside chat)

Everything is milestone-tracked; up-vote the issues that matter to you.

24. Take-away recipe

  1. Install with the one-liner.
  2. Create one workspace per project.
  3. Keep permissions on yellow until you trust the prompt.
  4. Use diff viewer like you would in Git.
  5. Back up .craft-agent with the same rigor you give your code.

Do those five things and Claude graduates from “clever chatbot” to “colleague who never sleeps.”
Enjoy the desktop upgrade.