[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74777":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":8,"pushedAt":8,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":14,"starSnapshotCount":14,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},74777,"craft-agents-oss","craft-ai-agents\u002Fcraft-agents-oss","craft-ai-agents",null,"TypeScript",6252,859,25,291,0,35,70,332,105,111.8,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:01:15","\u003Cdiv align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F20714\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Ftrendshift.io\u002Fapi\u002Fbadge\u002Frepositories\u002F20714\" alt=\"craft-ai-agents%2Fcraft-agents-oss | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n# Craft Agents\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## How it Works (Video)\nTo understand what Craft Agents does and how it works watch this video.\n\n[![Demo Video](https:\u002F\u002Fimg.youtube.com\u002Fvi\u002FxQouiAIilvU\u002Fhqdefault.jpg)](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=xQouiAIilvU)\n\n[Click Here (or on the image above) to watch the video on YouTube →](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=xQouiAIilvU)\n\n\n## Why Craft Agents was built\nCraft 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.\n\nIt 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.\n\nIt's built with Agent Native software principles in mind, and is highly customisable out of the box. One of the first of its kind.\n\nCraft 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.\n\nWe 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.\n\n\u003Cimg width=\"1578\" height=\"894\" alt=\"image\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F3f1f2fe8-7cf6-4487-99ff-76f6c8c0a3fb\" \u002F>\n\n## Things that are hard to believe \"just work\"\n\n**How do I connect to Linear, Gmail, Slack...?**\nTell 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.\n\n[Check out how I just connected to Slack →](https:\u002F\u002Fagents.craft.do\u002Fs\u002FDRNQEiy8w2e1v5LPgKl8b)\n\n**I already have my MCP config JSON.**\nPaste it. The agent handles the rest.\n\n**What about local MCPs?**\nFully 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.\n\n**Can it handle custom APIs?**\nYes. Paste an OpenAPI spec, some endpoint URLs, screenshots of docs, whatever you have. It figures it out and guides you through the rest.\n\n**APIs too? Not just MCPs?**\nCraft Agents connects to anything. We have it hooked up to a direct Postgres DB behind a jumpbox. Skills + Sources = magic.\n\n**How do I import my Claude Code skills and MCPs?**\nTell the agent you want to import your skills from Claude Code. It handles the migration.\n\n[Here I imported all my skills in one go →](https:\u002F\u002Fagents.craft.do\u002Fs\u002FgWCFqwhObFWaNJIEJmd6j)\n\n**How do I create a new skill?**\nDescribe what the skill should do, give it context. The agent takes care of the rest.\n\n**Do I need to restart after changes?**\nNo. Everything is instant. Mention new skills or sources with `@`, even mid-conversation.\n\n**So I can just ask it anything?**\nYes. 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.\n\n\n## Installation\n\n### One-Line Install (Recommended)\n\n**macOS \u002F Linux:**\n```bash\ncurl -fsSL https:\u002F\u002Fagents.craft.do\u002Finstall-app.sh | bash\n```\n\n**Windows (PowerShell):**\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\u002Flukilabs\u002Fcraft-agents-oss.git\ncd craft-agents-oss\nbun install\nbun run electron:start\n```\n\n## Features\n\n- **Multi-Session Inbox**: Desktop app with session management, status workflow, and flagging\n- **Claude Code Experience**: Streaming responses, tool visualization, real-time updates\n- **Multiple LLM Connections**: Add multiple AI providers and set per-workspace defaults\n- **Multi-Provider Support**: Run sessions with Google AI Studio, ChatGPT Plus, GitHub Copilot, or OpenAI API keys alongside Anthropic\n- **Craft MCP Integration**: Access to 32+ Craft document tools (blocks, collections, search, tasks)\n- **Sources**: Connect to MCP servers, REST APIs (Google, Slack, Microsoft), and local filesystems\n- **Permission Modes**: Three-level system (Explore, Ask to Edit, Auto) with customizable rules\n- **Background Tasks**: Run long-running operations with progress tracking\n- **Dynamic Status System**: Customizable session workflow states (Todo, In Progress, Done, etc.)\n- **Theme System**: Cascading themes at app and workspace levels\n- **Multi-File Diff**: VS Code-style window for viewing all file changes in a turn\n- **Skills**: Specialized agent instructions stored per-workspace\n- **File Attachments**: Drag-drop images, PDFs, Office documents with auto-conversion\n- **Automations**: Event-driven automation — create agent sessions on label changes, schedules, tool use, and more\n\n## Quick Start\n\n1. **Launch the app** after installation\n2. **Choose API Connection**: Use Anthropic (API key or Claude Max), Google AI Studio, ChatGPT Plus (Codex OAuth), or GitHub Copilot OAuth\n3. **Create a workspace**: Set up a workspace to organize your sessions\n4. **Connect sources** (optional): Add MCP servers, REST APIs, or local filesystems\n5. **Start chatting**: Create sessions and interact with Claude\n\n## Desktop App Features\n\n### Session Management\n\n- **Inbox\u002FArchive**: Sessions organized by workflow status\n- **Flagging**: Mark important sessions for quick access\n- **Status Workflow**: Todo → In Progress → Needs Review → Done\n- **Session Naming**: AI-generated titles or manual naming\n- **Session Persistence**: Full conversation history saved to disk\n\n### Sources\n\nConnect external data sources to your workspace:\n\n| Type | Examples |\n|------|----------|\n| **MCP Servers** | Craft, Linear, GitHub, Notion, custom servers |\n| **REST APIs** | Google (Gmail, Calendar, Drive, YouTube, Search Console), Slack, Microsoft |\n| **Local Files** | Filesystem, Obsidian vaults, Git repos |\n\n### Permission Modes\n\n| Mode | Display | Behavior |\n|------|---------|----------|\n| `safe` | Explore | Read-only, blocks all write operations |\n| `ask` | Ask to Edit | Prompts for approval (default) |\n| `allow-all` | Auto | Auto-approves all commands |\n\nUse **SHIFT+TAB** to cycle through modes in the chat interface.\n\n### Keyboard Shortcuts\n\n| Shortcut | Action |\n|----------|--------|\n| `Cmd+N` | New chat |\n| `Cmd+1\u002F2\u002F3` | Focus sidebar\u002Flist\u002Fchat |\n| `Cmd+\u002F` | Keyboard shortcuts dialog |\n| `SHIFT+TAB` | Cycle permission modes |\n| `Enter` | Send message |\n| `Shift+Enter` | New line |\n\n## Remote Server (Headless)\n\nCraft 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.\n\n### Quick Start\n\nFrom the monorepo root:\n\n```bash\n# Generate a token and start the server\nCRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages\u002Fserver\u002Fsrc\u002Findex.ts\n```\n\nThe server prints the connection details on startup:\n\n```\nCRAFT_SERVER_URL=ws:\u002F\u002F203.0.113.5:9100\nCRAFT_SERVER_TOKEN=\u003Cgenerated-token>\n```\n\nCopy these values and use them to connect the desktop app.\n\n### Connecting the Desktop App\n\nLaunch the Electron app in thin-client mode by passing the server URL and token:\n\n```bash\nCRAFT_SERVER_URL=wss:\u002F\u002F203.0.113.5:9100 CRAFT_SERVER_TOKEN=\u003Ctoken> bun run electron:start\n```\n\nIn thin-client mode, the desktop app renders the UI but all session logic, tool execution, and LLM calls run on the remote server.\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CRAFT_SERVER_TOKEN` | Yes | — | Bearer token for client authentication |\n| `CRAFT_RPC_HOST` | No | `127.0.0.1` | Bind address (`0.0.0.0` for remote access) |\n| `CRAFT_RPC_PORT` | No | `9100` | Bind port |\n| `CRAFT_RPC_TLS_CERT` | No | — | Path to PEM certificate file (enables `wss:\u002F\u002F`) |\n| `CRAFT_RPC_TLS_KEY` | No | — | Path to PEM private key file (required with cert) |\n| `CRAFT_RPC_TLS_CA` | No | — | Path to PEM CA chain file (optional, for client cert verification) |\n| `CRAFT_DEBUG` | No | `false` | Enable debug logging |\n\n### TLS (Recommended for Remote Access)\n\nWhen exposing the server over the network, TLS encrypts the WebSocket connection (`wss:\u002F\u002F` instead of `ws:\u002F\u002F`).\n\n**Generate a self-signed certificate (development\u002Ftesting):**\n\n```bash\n.\u002Fscripts\u002Fgenerate-dev-cert.sh\n# Creates certs\u002Fcert.pem and certs\u002Fkey.pem (valid 365 days)\n```\n\n**Start the server with TLS:**\n\n```bash\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\nThe server will print `CRAFT_SERVER_URL=wss:\u002F\u002F\u003Cyour-public-ip>:9100`.\n\n**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.\n\n### Docker\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\nTo enable TLS in Docker, mount your certificates and set the env vars:\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  -e CRAFT_RPC_TLS_CERT=\u002Fcerts\u002Fcert.pem \\\n  -e CRAFT_RPC_TLS_KEY=\u002Fcerts\u002Fkey.pem \\\n  -v .\u002Fcerts:\u002Fcerts:ro \\\n  -v craft-data:\u002Froot\u002F.craft-agent \\\n  craft-agents-server\n```\n\n## CLI Client\n\nA terminal client that connects to a running Craft Agent server over WebSocket (`ws:\u002F\u002F` or `wss:\u002F\u002F`). Use it for scripting, CI\u002FCD pipelines, server validation, or when you prefer the command line.\n\n### Installation\n\n```bash\n# From the monorepo (requires Bun)\nbun run apps\u002Fcli\u002Fsrc\u002Findex.ts --help\n\n# Or add to your PATH\nalias craft-cli=\"bun run $(pwd)\u002Fapps\u002Fcli\u002Fsrc\u002Findex.ts\"\n```\n\n### Connection\n\nThe CLI reads connection details from flags or environment variables:\n\n```bash\n# Via environment (set once)\nexport CRAFT_SERVER_URL=ws:\u002F\u002F127.0.0.1:9100\nexport CRAFT_SERVER_TOKEN=\u003Cyour-token>\n\n# Or via flags\ncraft-cli --url ws:\u002F\u002F127.0.0.1:9100 --token \u003Ctoken> ping\n```\n\nFor TLS connections (`wss:\u002F\u002F`), use `--tls-ca \u003Cpath>` for self-signed certificates.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `ping` | Verify connectivity (clientId + latency) |\n| `health` | Check credential store health |\n| `versions` | Show server runtime versions |\n| `workspaces` | List workspaces |\n| `sessions` | List sessions in workspace |\n| `connections` | List LLM connections |\n| `sources` | List configured sources |\n| `session create` | Create a session (`--name`, `--mode`) |\n| `session messages \u003Cid>` | Print session message history |\n| `session delete \u003Cid>` | Delete a session |\n| `send \u003Cid> \u003Cmessage>` | Send message and stream AI response |\n| `cancel \u003Cid>` | Cancel in-progress processing |\n| `invoke \u003Cchannel> [args]` | Raw RPC call with JSON args |\n| `listen \u003Cchannel>` | Subscribe to push events (Ctrl+C to stop) |\n| `run \u003Cprompt>` | Self-contained: spawn server, run prompt, stream response, exit |\n| `--validate-server` | 21-step integration test (auto-spawns server if no `--url`) |\n\n#### Run Command Flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--workspace-dir \u003Cpath>` | — | Register a workspace directory before running |\n| `--source \u003Cslug>` | — | Enable a source (repeatable) |\n| `--output-format \u003Cfmt>` | `text` | Output format: `text` or `stream-json` |\n| `--mode \u003Cmode>` | `allow-all` | Permission mode for the session |\n| `--no-cleanup` | `false` | Skip session deletion on exit |\n| `--server-entry \u003Cpath>` | — | Custom server entry point |\n| `--provider \u003Cname>` | `anthropic` | LLM provider (`anthropic`, `openai`, `google`, `openrouter`, `groq`, `mistral`, `xai`, etc.) |\n| `--model \u003Cid>` | (provider default) | Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`, `gemini-2.0-flash`) |\n| `--api-key \u003Ckey>` | — | API key (or `$LLM_API_KEY`, or provider-specific env var) |\n| `--base-url \u003Curl>` | — | Custom API endpoint for proxies or self-hosted models |\n\nThe `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`).\n\n### Examples\n\n```bash\n# Quick connectivity check\ncraft-cli ping\n\n# List sessions (human-readable)\ncraft-cli sessions\n\n# Send a message and stream the AI response\ncraft-cli send abc-123 \"What files are in the current directory?\"\n\n# Pipe input\necho \"Summarize this\" | craft-cli send abc-123\n\n# JSON output for scripting\ncraft-cli --json workspaces | jq '.[].name'\n\n# Self-contained run (spawns its own server)\ncraft-cli run \"Summarize the README\"\ncraft-cli run --workspace-dir .\u002Fmy-project --source github \"List open PRs\"\n\n# Multi-provider support\ncraft-cli run --provider openai --model gpt-4o \"Summarize this repo\"\nGOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash \"Hello\"\ncraft-cli run --provider anthropic --base-url https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1 --api-key $OR_KEY \"Hello\"\n\n# Validate the server (auto-spawns if no --url)\ncraft-cli --validate-server\ncraft-cli --validate-server --url ws:\u002F\u002F127.0.0.1:9100 --token \u003Ctoken>\n```\n\n## Architecture\n\n```\ncraft-agent\u002F\n├── apps\u002F\n│   ├── cli\u002F                   # Terminal client (CLI)\n│   └── electron\u002F              # Desktop GUI (primary)\n│       └── src\u002F\n│           ├── main\u002F          # Electron main process\n│           ├── preload\u002F       # Context bridge\n│           └── renderer\u002F      # React UI (Vite + shadcn)\n└── packages\u002F\n    ├── core\u002F                  # Shared types\n    └── shared\u002F                # Business logic\n        └── src\u002F\n            ├── agent\u002F         # CraftAgent, permissions\n            ├── auth\u002F          # OAuth, tokens\n            ├── config\u002F        # Storage, preferences, themes\n            ├── credentials\u002F   # AES-256-GCM encrypted storage\n            ├── sessions\u002F      # Session persistence\n            ├── sources\u002F       # MCP, API, local sources\n            └── statuses\u002F      # Dynamic status system\n```\n\n## Development\n\n```bash\n# Hot reload development\nbun run electron:dev\n\n# Build and run\nbun run electron:start\n\n# Type checking\nbun run typecheck:all\n\n# Debug logging (writes to ~\u002FLibrary\u002FLogs\u002F@craft-agent\u002Felectron\u002F)\n# Logs are automatically enabled in development\n```\n\n### Environment Variables\n\nOAuth integrations (Slack, Microsoft) require credentials baked into the build. Create a `.env` file:\n\n```bash\nMICROSOFT_OAUTH_CLIENT_ID=your-client-id\nSLACK_OAUTH_CLIENT_ID=your-slack-client-id\nSLACK_OAUTH_CLIENT_SECRET=your-slack-client-secret\n```\n\n**Note:** Google OAuth credentials are NOT baked into the build. Users provide their own credentials via source configuration. See the [Google OAuth Setup](#google-oauth-setup-gmail-calendar-drive) section below.\n\n### Google OAuth Setup (Gmail, Calendar, Drive, YouTube, Search Console)\n\nGoogle integrations require you to create your own OAuth credentials. This is a one-time setup.\n\n#### 1. Create a Google Cloud Project\n\n1. Go to [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com)\n2. Create a new project (or select an existing one)\n3. Note your Project ID\n\n#### 2. Enable Required APIs\n\nGo to **APIs & Services → Library** and enable the APIs you need:\n- **Gmail API** - for email integration\n- **Google Calendar API** - for calendar integration\n- **Google Drive API** - for file storage integration\n\n#### 3. Configure OAuth Consent Screen\n\n1. Go to **APIs & Services → OAuth consent screen**\n2. Select **External** user type (unless you have Google Workspace)\n3. Fill in required fields:\n   - App name: e.g., \"My Craft Agent\"\n   - User support email: your email\n   - Developer contact: your email\n4. Add scopes (optional - can leave default)\n5. Add yourself as a test user (required for External apps in testing mode)\n6. Complete the wizard\n\n#### 4. Create OAuth Credentials\n\n1. Go to **APIs & Services → Credentials**\n2. Click **Create Credentials → OAuth Client ID**\n3. Application type: **Desktop app**\n4. Name: e.g., \"Craft Agent Desktop\"\n5. Click **Create**\n6. Note the **Client ID** and **Client Secret**\n\n#### 5. Configure in Craft Agent\n\nWhen setting up a Google source (Gmail, Calendar, Drive, YouTube, Search Console, etc.), add these fields to your source's `config.json`:\n\n```json\n{\n  \"api\": {\n    \"googleService\": \"gmail\",\n    \"googleOAuthClientId\": \"your-client-id.apps.googleusercontent.com\",\n    \"googleOAuthClientSecret\": \"your-client-secret\"\n  }\n}\n```\n\nOr simply tell the agent you want to connect Gmail\u002FCalendar\u002FDrive - it will guide you through entering your credentials.\n\n#### Security Notes\n\n- Your OAuth credentials are stored encrypted alongside other source credentials\n- Never commit credentials to version control\n- For production use, consider getting your OAuth consent screen verified by Google\n\n## Supported LLM Providers\n\nCraft Agents supports multiple ways to connect to LLM providers:\n\n### Direct Connections\n\n| Provider | Auth | Notes |\n|----------|------|-------|\n| **Anthropic** | API key or Claude Max\u002FPro OAuth | Direct Claude connection via the Claude Agent SDK |\n| **Google AI Studio** | API key | Gemini models with native Google Search grounding built in |\n| **ChatGPT Plus \u002F Pro** | Codex OAuth | Sign in with your ChatGPT subscription — uses OpenAI's Codex models |\n| **GitHub Copilot** | OAuth (device code) | One-click authentication with your Copilot subscription |\n\n### Third-Party & Self-Hosted Providers\n\nAdditional providers are supported through the **Claude \u002F Anthropic API Key** connection by choosing a custom endpoint:\n\n| Provider | Endpoint | Notes |\n|----------|----------|-------|\n| **OpenRouter** | `https:\u002F\u002Fopenrouter.ai\u002Fapi` | Access Claude, GPT, Llama, Gemini, and hundreds of other models through a single API key. Use `provider\u002Fmodel-name` format (e.g. `anthropic\u002Fclaude-opus-4.7`). |\n| **Vercel AI Gateway** | `https:\u002F\u002Fai-gateway.vercel.sh` | Route requests through Vercel's AI Gateway with built-in observability and caching. |\n| **Ollama** | `http:\u002F\u002Flocalhost:11434` | Run open-source models locally. No API key required. |\n| **Custom** | Any URL | Any OpenAI-compatible or Anthropic-compatible endpoint. |\n\n### Architecture\n\nCraft Agents uses two agent backends:\n\n- **Claude** — powered by the [Claude Agent SDK](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@anthropic-ai\u002Fclaude-agent-sdk), which natively supports custom base URLs and provider routing. Anthropic API key, Claude Max\u002FPro OAuth, and all third-party endpoints use this backend.\n- **Pi** — powered by the Pi SDK, which handles Google AI Studio, ChatGPT Plus (Codex OAuth), GitHub Copilot OAuth, and OpenAI API key connections. Pi connections route through their own provider infrastructure.\n\n## Configuration\n\nConfiguration is stored at `~\u002F.craft-agent\u002F`:\n\n```\n~\u002F.craft-agent\u002F\n├── config.json              # Main config (workspaces, LLM connections)\n├── credentials.enc          # Encrypted credentials (AES-256-GCM)\n├── preferences.json         # User preferences\n├── theme.json               # App-level theme\n└── workspaces\u002F\n    └── {id}\u002F\n        ├── config.json      # Workspace settings\n        ├── theme.json       # Workspace theme override\n        ├── automations.json  # Event-driven automations\n        ├── sessions\u002F        # Session data (JSONL)\n        ├── sources\u002F         # Connected sources\n        ├── skills\u002F          # Custom skills\n        └── statuses\u002F        # Status configuration\n```\n\n### Automations\n\nAutomations let you automate workflows by triggering actions when events happen — labels change, sessions start, tools run, or on a cron schedule.\n\n**Just ask the agent:**\n- \"Set up a daily standup briefing every weekday at 9am\"\n- \"Notify me when a session is labelled urgent\"\n- \"Track permission mode changes and summarise them\"\n- \"Every Friday at 5pm, summarise this week's completed tasks\"\n\nOr configure manually in `~\u002F.craft-agent\u002Fworkspaces\u002F{id}\u002Fautomations.json`:\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    \"LabelAdd\": [\n      {\n        \"matcher\": \"^urgent$\",\n        \"actions\": [\n          { \"type\": \"prompt\", \"prompt\": \"An urgent label was added. Triage the session and summarise what needs attention.\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\n**Prompt actions** create a new agent session with a prompt. They support `@mentions` for sources and skills, and environment variables like `$CRAFT_LABEL` and `$CRAFT_SESSION_ID` are expanded automatically.\n\n**Supported events:** `LabelAdd`, `LabelRemove`, `PermissionModeChange`, `FlagChange`, `SessionStatusChange`, `SchedulerTick`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, and more.\n\nSee the [Automations documentation](https:\u002F\u002Fagents.craft.do\u002Fdocs\u002Fautomations\u002Foverview) for the full reference.\n\n## Advanced Features\n\n### Large Response Handling\n\nTool responses exceeding ~60KB are automatically summarized using Claude Haiku with intent-aware context. The `_intent` field is injected into MCP tool schemas to preserve summarization focus.\n\n### Deep Linking\n\nExternal apps can navigate using `craftagents:\u002F\u002F` URLs:\n\n```\ncraftagents:\u002F\u002FallSessions                      # All sessions view\ncraftagents:\u002F\u002FallSessions\u002Fsession\u002Fsession123   # Specific session\ncraftagents:\u002F\u002Fsettings                         # Settings\ncraftagents:\u002F\u002Fsources\u002Fsource\u002Fgithub            # Source info\ncraftagents:\u002F\u002Faction\u002Fnew-chat                  # Create new session\n```\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Runtime | [Bun](https:\u002F\u002Fbun.sh\u002F) |\n| AI | [@anthropic-ai\u002Fclaude-agent-sdk](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@anthropic-ai\u002Fclaude-agent-sdk) |\n| AI (Pi) | Pi SDK agent server |\n| Desktop | [Electron](https:\u002F\u002Fwww.electronjs.org\u002F) + React |\n| UI | [shadcn\u002Fui](https:\u002F\u002Fui.shadcn.com\u002F) + Tailwind CSS v4 |\n| Build | esbuild (main) + Vite (renderer) |\n| Credentials | AES-256-GCM encrypted file storage |\n\n## Troubleshooting\n\n### Debug Mode\n\nTo launch the packaged app with verbose logging enabled, use `-- --debug` (note the double dash separator):\n\n**macOS:**\n```bash\n\u002FApplications\u002FCraft\\ Agents.app\u002FContents\u002FMacOS\u002FCraft\\ Agents -- --debug\n```\n\n**Windows (PowerShell):**\n```powershell\n& \"$env:LOCALAPPDATA\\Programs\\@craft-agentelectron\\Craft Agents.exe\" -- --debug\n```\n\n**Linux:**\n```bash\n.\u002Fcraft-agents -- --debug\n```\n\nLogs are written to:\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## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n### Third-Party Licenses\n\nThis project uses the [Claude Agent SDK](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@anthropic-ai\u002Fclaude-agent-sdk), which is subject to [Anthropic's Commercial Terms of Service](https:\u002F\u002Fwww.anthropic.com\u002Flegal\u002Fcommercial-terms).\n\n### Trademark\n\n\"Craft\" and \"Craft Agents\" are trademarks of Craft Docs Ltd. See [TRADEMARK.md](TRADEMARK.md) for usage guidelines.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Security\n\n### Local MCP Server Isolation\n\nWhen spawning local MCP servers (stdio transport), sensitive environment variables are filtered out to prevent credential leakage to subprocesses. Blocked variables include:\n\n- `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` (app auth)\n- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`\n- `GITHUB_TOKEN`, `GH_TOKEN`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `STRIPE_SECRET_KEY`, `NPM_TOKEN`\n\nTo explicitly pass an env var to a specific MCP server, use the `env` field in the source config.\n\nTo report security vulnerabilities, please see [SECURITY.md](SECURITY.md).\n","Craft Agents 是一个旨在提高与智能代理协作效率的工具，支持直观多任务处理、无缝连接到任何API或服务、会话共享以及更偏向文档的工作流程。项目采用TypeScript编写，利用Claude Agent SDK和Pi SDK的优势进行构建，具有高度可定制性。适用于需要与多种API和服务集成并追求高效工作流的场景，如开发人员在日常工作中快速接入新服务或数据源时。其简洁直观的操作界面降低了用户的学习成本，使得即使是非技术人员也能轻松上手使用。",2,"2026-06-11 03:50:47","high_star"]