🦀 CrabAgent

AI Knowledge Work Platform — Chat when you need answers, Work when you need results. Two modes, one seamless experience. Runs in terminal, browser, or desktop.

CrabAgent is a local-first AI platform with two working modes that adapt to what you're doing:

You don't pick a mode upfront. Start chatting, and when the AI starts working on a document or code file, the workspace slides open automatically. Switch back to Chat Mode anytime for a clean conversation view.

Chat Mode                          Work Mode
┌──────┬──────────────┐           ┌──┬──────────┬────────────────┐
│      │              │           │  │ AI Chat  │   Workspace    │
│ Sess │  Conversation│           │ 💬│ Sidebar  │  ┌──────────┐  │
│ List │              │           │  │ (350px)  │  │ Document │  │
│      │              │           │  │          │  │ Preview  │  │
│      │              │           │  │ Input    │  │ Code     │  │
│      │              │           │  │          │  │ Prototype│  │
│      │              │           │  │          │  │ Meeting  │  │
└──────┴──────────────┘           │  │          │  └──────────┘  │
                                  └──┴──────────┴────────────────┘

English | 中文

💬 Chat Mode — Pure Conversation

The default mode. Session list on the left, full-width conversation on the right. No distractions.

Best for:

• Asking questions and getting AI-powered answers
• Brainstorming and exploring ideas
• Quick research via web search and browser automation
• Delegating tasks to specialized AI agents (researcher, analyst, coder, writer)
• Multi-turn conversations with full project memory

You: "帮我分析一下这个项目的架构"
AI: [reads files, analyzes patterns, generates structured report]
You: "把分析结果整理成一份 Word 文档"
AI: [creates document] → auto-switches to Work Mode with preview

🛠️ Work Mode — AI + Live Workspace

When the AI creates or opens a file, the interface splits: AI chat shrinks to a 350px sidebar on the left, and the workspace takes over the right side. Everything the AI does is visible in real time.

Workspace types

Work Mode features

• Real-time preview: watch the AI edit a document and see changes reflected instantly
• Inline editing: double-click text in document preview to edit directly
• AI Edit toolbar: Bold, italic, font size, color — one click to style selected text
• Natural language edit: type instructions like "make the heading red" and the AI applies it
• Document timeline: see the full history of AI operations on the document
• File workspace: create folders, multi-select items, drag files or folders between directories, use a floating context menu, and copy text previews without leaving Work Mode
• Collaboration browser: AI navigates websites, fills forms, and extracts data in an embedded browser with page-version safety, sensitive-field blocking, and high-risk click interception — all while you maintain login state and handle human-only steps
• One-click switch back to Chat Mode when you're done

Work Mode in action:

You: "读取 sales.xlsx 汇总 Q1 数据，做成一份报告"
                          │
  ┌───────────────────────┼───────────────────────────────┐
  │  AI Chat Sidebar      │  Workspace (Document Preview) │
  │                       │                               │
  │  AI: Reading file...  │  ┌─────────────────────────┐  │
  │  AI: Q1 total: $1.2M  │  │  Q1 Sales Report        │  │
  │  AI: Creating doc...  │  │  ───────────────        │  │
  │  AI: Done! ✓          │  │  Total: $1.2M           │  │
  │                       │  │  Growth: +23%           │  │
  │  [Input: continue...] │  │  ...                    │  │
  │                       │  └─────────────────────────┘  │
  └───────────────────────┴───────────────────────────────┘

🤖 AI Team

Both modes have access to a team of specialized agents:

Orchestration modes

Delegate      → @researcher "find competitor pricing"
Parallel      → Run 3 agents simultaneously on different tasks
Pipeline      → research → analyze → write (with data flow)
Handoff       → Pass context from one agent to another

Cost control: In Settings → General, map the parent agent's provider|model to a (usually cheaper) provider|model for sub-agents — applied automatically on every delegation, across providers.

📬 Email Intelligence — Tasks from Inbox

CrabAgent watches your inbox and turns emails into action items — automatically.

Incoming email: "明天下午3点开会讨论新功能"
      │
      ├─ 🧠 LLM analyzes: meeting + deadline detected
      ├─ 📝 Drafts a reply for your review
      ├─ ✅ Creates task: "参加关于crabagent的会议" (due tomorrow 3PM)
      └─ 🔗 Links task to email conversation — click to view full context

No rules, no regex. Just LLM-powered understanding.

💬 WeChat Channel — AI in Your Pocket

Bind your WeChat account via QR code, and CrabAgent becomes reachable from your phone.

You (WeChat): "看一下26年1月有啥工作"
       │
       ├─ 🤖 Agent processes with full project context
       ├─ 💬 Replies directly in WeChat chat
       └─ 🔔 Pushes notifications: task overdue, scheduled task done, email summary

Three modes:

• Command execution — send instructions from WeChat, Agent executes and replies
• Proactive notifications — task deadlines, scheduled task results, email summaries auto-pushed
• Conversational — multi-turn chat with full project memory

🔑 ChatGPT Subscription — Use Your Plus/Pro Membership

Already paying for ChatGPT Plus or Pro? Use it directly in CrabAgent — no API key, no extra cost.

Settings → Providers → Add → "ChatGPT Subscription (Plus/Pro)"
       │
       ├─ 🔐 Click "Login ChatGPT" → get a device code
       ├─ 🌐 Open auth.openai.com/codex/device in browser
       ├─ ✍️ Sign in with ChatGPT, enter the code
       ├─ ✅ CrabAgent auto-detects login
       └─ 📊 Click "View Usage" → see real-time quota:
            ┌──────────────────────────────────┐
            │ Plan: PLUS     Limit: premium     │
            │                                   │
            │ 5h window   ██░░░░░░░  12.3%      │
            │ 7d window   █░░░░░░░░   3.1%      │
            │ Reset in: 4.2h / 6.2d             │
            └──────────────────────────────────┘

Available models: gpt-5.4, gpt-5.3-codex, gpt-5.3-instant, gpt-5.2-codex, and more — all powered by your ChatGPT subscription.

How it works: CrabAgent uses the same OAuth Device Code flow as the official OpenAI Codex CLI. Your ChatGPT login is stored locally and auto-refreshed. All API calls go through chatgpt.com/backend-api/codex, using your subscription quota — not paid API credits.

🧠 Project Memory & Self-Evolving Agents

Every time you work in a project, CrabAgent automatically extracts lessons and preferences. Next time you open it, it already knows:

=== 项目上下文 ===
上次活跃：06-05 15:30
技术栈：Python / FastAPI / SQLAlchemy
项目经验：N+1 查询用 selectinload 优化；API 文档用 OpenAPI 规范
====================

After each task, agents reflect on what worked (and what didn't) and store the insight permanently:

Quick Start

pip install crabagent
crabagent init

# TUI — interactive REPL with slash commands
crabagent

# Web UI — Chat Mode & Work Mode
crabagent --serve          # → http://localhost:5210
                           #   Default login: admin / xcl1989

# Single-shot CLI
crabagent "organize this directory"

Desktop App (macOS & Windows)

Build the Electron wrapper (requires Python + crabagent installed on your system):

# One-command build (from git clone):
make desktop                       # macOS → CrabAgent-x.x.x-arm64.dmg

# Or from pip install (auto-detects platform):
crabagent --build-desktop          # macOS → .dmg | Windows → .exe installer

# Windows (PowerShell):
.\scripts\build-desktop.ps1        # → CrabAgent-x.x.x-setup.exe

The desktop app includes a floating desktop pet that reacts to agent state (idle, thinking, working, waiting, celebrating, error). Drag it anywhere on screen; use the tray or app menu to show/hide it.

Features

🎯 Goal Mode

Create a durable goal for the current conversation with the target button or /goal <objective>. A goal keeps its objective, success criteria, constraints, checkpoints, and evidence visible while all planning, tool calls, tests, and results remain in the normal chat stream.

Pause, resume, edit, or inspect the goal timeline at any time. With Auto Continue enabled, CrabAgent starts the next focused session turn after the current response, stopping safely when the goal is completed, paused, blocked, or reaches its configured token or turn budget.

🛠️ Work Mode

Split-pane workspace with live document preview, code editor, prototype builder, meeting notes, and Markdown editor. AI chat sidebar stays interactive while you work.

📈 Usage Insights

Track token consumption by time range and workspace. The Usage page highlights period totals, calls, cache health, and active sessions, then lets you compare model and agent consumption, search and sort sessions, and expand a session to inspect its recent calls.

🔍 Execution Trace

Every agent run records a structured span tree — LLM calls, tool invocations, and sub-agent delegations — with per-step token usage, duration, and status. Click "Trace" on the stats bar to open a side panel with a color-coded tree, token share bars, expandable details, and automated insights (tool loop detection, token hotspots, context bloat, error concentration).

📊 Rich Conversation Visualizations

Assistant responses can turn Markdown into shareable visuals: Mermaid flowcharts, sequence/state/ER diagrams, architecture diagrams, and bar, line, area, pie, or scatter charts. KPI cards summarize a key metric. Open any visualization in a larger view, then copy it as a PNG or download a high-resolution PNG to share.

Mermaid diagrams render after a streamed response is complete and are syntax-validated before display, so incomplete diagram text never replaces the conversation with raw parser-error graphics.

📝 Markdown Editor

Split-pane editor for .md files — source on the left, live rendered preview on the right. Bidirectional scroll sync, GFM tables, syntax-highlighted code blocks. Switch between Source / Split / Preview views.

📄 Intelligent Document Processing

AI agents can read, create, edit, and preview Office documents (.docx, .xlsx, .pptx) directly in conversations.

🧠 Project Memory

Remembers your project context across sessions. Zero extra cost.

🖼️ Multi-modal

Paste/drop images into conversations or ask the agent to read an image already in the workspace. Vision-capable models receive the image directly (large files are resized automatically), without routing ordinary inspection through a generic image-analysis MCP tool. Specialized OCR, UI, diagram, chart, comparison, and video tools remain available. On text-only models (e.g. kimi-k2, moonshot-v1), images degrade gracefully to text placeholders and the session keeps running. AI-generated images persist across sessions with inline rendering. Lazy loading: images are fetched on-demand after text renders, so opening image-heavy sessions is instant. AI image editing (image_edit) creates new images from an attached reference — modify style or background, or place the same subject in a new scene; the model slug is resolved dynamically from the provider, so provider-side model changes need no update.

🗂️ Multi-Workspace

Work across multiple projects simultaneously. The workspace switcher shows a live badge with the count of active sessions in each workspace — no need to switch back and forth to check if a background agent has finished. Running sessions in the current workspace are marked with a pulsing green indicator.

🌐 Browser Automation

pip install 'crabagent[browser]'
playwright install chromium

🔌 MCP Client

Connect external MCP servers (stdio + HTTP). Tools auto-discover and get prefixed.

⏱ Scheduled Tasks

> Open Hacker News at 9 AM every day and screenshot top 5
> Check product page every 30 min, notify me if below $500

🦀 Snapshots (Molt)

Auto-snapshot files before changes. Roll back anytime without Git.

🔧 Custom Tools

Drop a .py file in .crabagent/tools/ — or let the AI create one for you in a conversation.

Installation

pip install crabagent                    # CLI + Web UI + API (all-in-one)
pip install 'crabagent[browser]'        # Browser automation
pip install 'crabagent[memory]'         # Semantic memory search (recommended)
pip install 'crabagent[dev]'            # Testing + linting

Development

make install            # Build frontend + install (editable)
ruff check src/ tests/  # Lint
ruff format src/ tests/ # Format
pytest                   # Run tests

CLI / TUI Commands

Configuration

Project Structure

CrabAgent/
├── src/crabagent/
│   ├── cli/           # CLI + TUI
│   ├── core/agent/    # Agent loop, tools, compression, agents
│   ├── core/mcp/      # MCP client manager
│   ├── core/          # Database, config, project memory, embedding
│   └── serve/         # FastAPI + API + scheduler
├── frontend/          # React SPA
├── electron/          # Electron desktop app
├── scripts/           # Build scripts
├── crabagent.spec     # PyInstaller config
└── crabagent.db       # SQLite database

License

GNU Affero General Public License v3 (AGPLv3) for non-commercial use. Commercial use requires a separate license. Contact the author.

See LICENSE.