Metadata-Version: 2.4
Name: crabagent
Version: 0.13.5
Summary: CrabAgent - AI Agent Platform with dual-mode (CLI + Serve)
Project-URL: Homepage, https://github.com/xcl1989/CrabAgent
Project-URL: Repository, https://github.com/xcl1989/CrabAgent
Project-URL: Issues, https://github.com/xcl1989/CrabAgent/issues
Author-email: Xie Congling <xcl1989@live.com>
License: Commercial
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: apscheduler>=3.10
Requires-Dist: bcrypt<5.0,>=4.0
Requires-Dist: ddgs>=7.0
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: icalendar>=5.0
Requires-Dist: jieba>=0.42
Requires-Dist: litellm>=1.40
Requires-Dist: lxml>=6.1.1
Requires-Dist: mcp>=1.0
Requires-Dist: passlib[bcrypt]>=1.7
Requires-Dist: pillow>=10.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-jose[cryptography]>=3.3
Requires-Dist: redis>=5.0
Requires-Dist: rich>=13.0
Requires-Dist: scrapling>=0.4.9
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn>=0.29
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: memory
Requires-Dist: sentence-transformers>=3.0; extra == 'memory'
Description-Content-Type: text/markdown

# 🦀 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:

| | Chat Mode 💬 | Work Mode 🛠️ |
|---|---|---|
| **Layout** | Session list + conversation | AI sidebar + live workspace |
| **Focus** | Talk, ask, brainstorm | Create, edit, build |
| **Right panel** | — | Document preview / code editor / prototype / meeting notes |
| **Switch** | Click 🛠️ icon in toolbar | Click 💬 icon or AI auto-switches when opening files |

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  │  │
└──────┴──────────────┘           │  │          │  └──────────┘  │
                                  └──┴──────────┴────────────────┘
```

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)

**[English](README.md)** | **[中文](README.zh-CN.md)**

---

## 💬 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

| Type | What shows | Trigger |
|------|-----------|---------|
| 📄 **Document** | Office document preview (`.docx` / `.xlsx` / `.pptx`) with outline, timeline, and inline edit | AI creates/opens an Office file |
| 💻 **Code** | Monaco-based code editor with syntax highlighting | AI works on a code file |
| 🔬 **Prototype** | Split-pane: source code on left, live preview on right | AI builds an HTML/JS prototype |
| 📝 **Meeting** | Structured meeting notes panel with action item extraction | You click "Start Meeting" |

### 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
- **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:

| Agent | Role | Best for |
|-------|------|----------|
| **Researcher** | Web researcher | Search, browse, collect data |
| **Analyst** | Data analyst | Compare, identify patterns, generate reports |
| **Coder** | Code expert | Write, review, debug, refactor |
| **Writer** | Content writer | Write, edit, translate, format |
| **Plan Creator** | Task planner | Decompose complex tasks into workflows |

### 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:

| Layer | Scope | What's stored |
|-------|-------|---------------|
| **Project Memory** | Per workspace | Recent lessons, tech stack, activity timeline |
| **User Preferences** | Per user | Communication style, tool preferences, rejected patterns |
| **Agent Lessons** | Per agent | Technical strategies, pitfalls, effective approaches |

---

## Quick Start

```bash
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):

```bash
# 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.

### 📊 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. Auto-detects vision model support. 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.

### 🗂️ 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
```bash
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

```bash
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

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

---

## CLI / TUI Commands

| Command | Description |
|---------|-------------|
| `/exit`, `/quit` | Exit |
| `/help` | Help |
| `/clear` | Clear context |
| `/model [name]` | Switch model |
| `/models` | List models |
| `/provider [cmd]` | Manage providers |
| `/sessions` / `/session [id]` | List/load sessions |
| `/new` | New session |
| `/agents [cmd]` | Agent team management |
| `/agent [name]` | Switch agent |
| `/agent_stats <name>` | Agent growth stats |
| `/delegate [@agent] [task]` | Delegate task |
| `/memory [list|search|clear]` | Team memory |
| `/skills` / `/skill <name>` | List/view skills |
| `/molt [cmd]` | Snapshot management |
| `/todo [cmd]` | Todo management |
| `/export` | Export as Markdown |
| `/image <path>` | Send image |
| `/runs [agent]` | View run history |
| `/abort` | Abort execution |

---

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `CRAB_DB_URL` | `sqlite+aiosqlite:///./crabagent.db` | Database URL |
| `CRAB_JWT_SECRET` | auto-generated | JWT signing key |
| `CRAB_SERVE_HOST` | `0.0.0.0` | Server host |
| `CRAB_SERVE_PORT` | `5210` | Server port |
| `CRAB_MAX_ITERATIONS` | `50` | Max agent iterations |
| `CRAB_MAX_TOKENS` | `4096` | Max response tokens |
| `CRAB_BROWSER_HEADLESS` | `true` | Browser headless mode |
| `CRAB_WEB_PROXY` | (empty) | HTTP proxy for web tools |
| `CRAB_MEMORY_EMBEDDING` | `auto` | Memory vector search: `auto` / `on` / `off` |

---

## 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](LICENSE).
