Clawdeck CLI

An intelligent AI coding assistant CLI tool powered by Anthropic Claude.

📚 Documentation: https://yiqiao-yin.github.io/clawdeck/

🔗 GitHub Repository: https://github.com/yiqiao-yin/clawdeck

📑 Table of Contents

• Overview
• System Architecture
• Installation
• Quick Start
• Features
  • Core Capabilities
  • Intelligent Features
  • Context Management
  • Model Selection & Optimization
  • Configuration & Personalization
  • Streaming Responses
  • HuggingFace Integration
  • Automatic Test Generation
  • GitHub Integration
  • Web Search
  • Browser Use / Direct Website Fetching
  • Vision Mode for Document Images
  • Autonomous Vision-Based Browsing
• Usage Examples
• Commands
• Documentation
• Development & Testing
• Environment Variables
• Requirements
• Web Terminal
• Contributing
• License
• Author
• Acknowledgments
• Links

🎯 Overview

Clawdeck CLI is an AI-powered coding assistant that helps you build projects, generate code, and improve your codebase through natural language conversations. Built with pydantic-ai and Anthropic Claude, it provides intelligent file operations, command execution, and context-aware assistance.

🏗️ System Architecture

For a detailed architecture overview including all components, layers, and data flows, see SYSTEM.md.

📦 Installation

Basic Installation

pip install clawdeck

Optional: Enable Browser Use (Direct Website Fetching)

If you want to use the fetch_website feature to read specific URLs directly:

# Install Playwright browser binaries (one-time setup, ~200MB)
playwright install chromium

Note: Browser use is optional. Web search and all other features work without it. Only install if you need direct URL fetching (e.g., "Read https://github.com/user/repo").

🚀 Quick Start

1. Choose your AI provider and set up credentials:

Clawdeck CLI supports four AI providers. Choose one:

---

Option 1: Anthropic Claude (Direct API)

Using environment variables:

export CHOOSE_CLIENT=1
export ANTHROPIC_API_KEY=your_key_here
export ANTHROPIC_MODEL=claude-sonnet-4-6

Using .env file (recommended):

# Create .env file in your project directory
CHOOSE_CLIENT=1
ANTHROPIC_API_KEY=your_key_here
ANTHROPIC_MODEL=claude-sonnet-4-6

Get your API key: Anthropic Console Available models: See Claude Model Overview

---

Option 2: AWS Bedrock (Claude via AWS)

Using environment variables:

export CHOOSE_CLIENT=2
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token
export AWS_REGION=us-west-2
export ANTHROPIC_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0

Using .env file (recommended):

# Create .env file in your project directory
CHOOSE_CLIENT=2
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_SESSION_TOKEN=your_session_token
AWS_REGION=us-west-2
ANTHROPIC_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0

Requirements: Valid AWS account with Bedrock access

---

Option 3: Google Gemini 🆕

Using environment variables:

export CHOOSE_CLIENT=3
export GEMINI_API_KEY=your_key_here
export GEMINI_MODEL=gemini-2.5-flash

Using .env file (recommended):

# Create .env file in your project directory
CHOOSE_CLIENT=3
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.5-flash

Get your API key: Google AI Studio Available models: gemini-2.5-flash (fast, cheap), gemini-2.5-pro (powerful) Cost: ~40x cheaper than Claude! ($0.075/M vs $3.00/M input tokens)

Features:

• ✅ All tools supported (file ops, git, docs, browser, etc.)
• ✅ 2M token context window (vs 200K for Claude)
• ✅ Fast and cost-effective
• ⚠️ Web search temporarily disabled (will be added as custom tool)

---

Option 4: OpenAI 🆕

Using environment variables:

export CHOOSE_CLIENT=4
export OPENAI_API_KEY=your_key_here
export OPENAI_MODEL=gpt-4o

Using .env file (recommended):

# Create .env file in your project directory
CHOOSE_CLIENT=4
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4o

Get your API key: OpenAI Platform Available models: gpt-4o (latest), gpt-4 (stable), gpt-3.5-turbo (fast) Cost: Competitive pricing with good performance

Features:

• ✅ All tools supported (file ops, git, docs, browser, etc.)
• ✅ 128K token context window
• ✅ Industry-leading performance
• ✅ Fast response times

---

Auto-Detection (No CHOOSE_CLIENT)

If you don't set CHOOSE_CLIENT, the system will auto-detect based on available credentials:

Priority order:

1. ANTHROPIC_API_KEY → Use Anthropic
2. AWS credentials → Use Bedrock
3. GEMINI_API_KEY → Use Google Gemini
4. OPENAI_API_KEY → Use OpenAI

# Just set your preferred API key
export GEMINI_API_KEY=your_key_here
# System will automatically use Gemini

2. Run the CLI:

clawdeck

3. Start chatting:

You: Build a Streamlit app for data visualization

Clawdeck: I'll create a Streamlit app for you...
[Generates complete code and saves to app.py]

✨ Features

Core Capabilities

• 🤖 Interactive AI Assistant - Natural language conversations with Claude
• 📝 Code Generation - Generate production-ready Python code from descriptions
• 🔍 Project Analysis - Understand and improve existing codebases
• 📁 Smart File Operations - Context-aware file creation and updates
• ⚡ Command Execution - Run Python scripts, UV commands, shell scripts, any CLI tool
• ⌨️ Multi-line Input - Press Enter to submit, Shift+Enter for newline
• 🔒 Safety First - Confirmation prompts before executing commands

Intelligent Features (v0.2.x)

• 🧠 Intent Recognition - Understands "update" vs "create new" from natural language
• 🔄 Context-Aware Updates - Reads files before modifying them
• 🔁 Self-Correcting - Smart retry mechanism with 3 attempts
• ⏱️ Timeout Protection - Prevents infinite loops (5 min default)
• 📊 Comprehensive Output - Captures stdout, stderr, and exit codes

Context Management (v0.2.8)

• 💬 Conversation History - Maintains context across multiple interactions
• 📊 Token Tracking - Real-time monitoring of API usage and costs
• 💾 Session Save/Load - Preserve conversations for later continuation
• 🎯 Slash Commands - Quick access to history, stats, and session management

Model Selection & Optimization (v0.3.0)

• 🔄 Dynamic Model Switching - Switch between Haiku, Sonnet, and Opus mid-session
• 💰 Cost Optimization - Choose the right model for your task complexity
• 📊 Model Information - View current model, pricing, and capabilities
• ⚡ Flexible Performance - Balance between speed, capability, and cost

Configuration & Personalization (v0.3.1)

• ⚙️ User Configuration - Personal preferences via ~/.clawdeck/config.yaml
• 📁 Project Configuration - Project-specific settings via .clawdeck.yaml
• 🎯 Custom Instructions - Add your coding standards to every conversation
• 🏗️ Project Context - Help AI understand your tech stack automatically

Streaming Responses (v0.3.2)

• ⚡ Real-Time Output - See responses as they're generated, token-by-token
• 🎯 Immediate Feedback - Start reading while AI is still generating
• 📺 Progress Visibility - Watch code and explanations appear in real-time
• 💨 Faster Perceived Speed - Feels 2-3x faster with instant feedback

HuggingFace Integration (v0.3.3 - v0.3.13)

• 🤗 HuggingFace Authentication - Auto-login with HF_TOKEN environment variable
• 📝 README Generation - Create professional README files for Spaces
• 🚀 Space Creation - Create Streamlit/Gradio Spaces directly from CLI
• 📤 File Upload - Push your code to HuggingFace Spaces automatically
• 🎯 One-Command Deploy - From code to live Space in seconds

Automatic Test Generation (v0.3.18)

• 🧪 Test Generation - Automatically generate pytest tests for Python files
• 📊 Smart Analysis - Analyzes functions and classes to create comprehensive tests
• ⚡ Quick Setup - Creates test files with proper structure and imports
• 🎯 Code Coverage - Generates tests for edge cases and error handling

GitHub Integration (v0.3.22)

• 🔐 GitHub Authentication - Auto-login with GH_TOKEN/GITHUB_TOKEN
• 💾 Commit & Push - Stage, commit, and push changes with one command
• 🔀 Pull Requests - Create PRs with generated descriptions
• 🌿 Branch Management - Create, checkout, and merge branches seamlessly
• 🔄 Merge Operations - Smart branch merging with conflict detection

Web Search (v0.3.21, Enhanced v0.3.23)

• 🔍 Real-Time Search - Access current information from the web
• 🌦️ Weather Queries - Get current weather for any location
• 🔗 URL Reading - Fetch and summarize web page content
• 📚 Resource Finding - Find GitHub repos, libraries, and tutorials
• 📊 Current Data - Latest package versions, documentation, and trends
• 💰 Cost Effective - Limited to 5 searches per session, $10 per 1K searches

Browser Use / Direct Website Fetching (v0.3.24+)

• 🌐 Direct URL Fetching - Fetch specific websites directly (not just search results)
• 📄 Full DOM Extraction - Get complete page content, not just search snippets
• 🧠 LLM-Optimized - Automatic conversion to clean, structured markdown
• ⚡ Smart Caching - 30-minute TTL cache for faster repeated access
• 📏 Smart Truncation - Preserves document structure while staying under token limits
• 🎯 Configurable - Adjust max tokens, cache settings, truncation strategy
• 💾 Cache Management - View stats, clear cache, manage storage
• 🖥️ Browser Debugging - Use --show-browser flag or CLAWDECK_BROWSER_SHOW=1 to see automation in action
• 🔄 Interactive Error Recovery - LLM-assisted error analysis with intelligent recovery options when automation fails

Vision Mode for Document Images (v0.3.30)

• 🖼️ Image Processing - Intelligently describe images in Word and PDF documents
• 📊 Chart Recognition - Extract insights from charts, graphs, and data visualizations
• 📐 Diagram Understanding - Analyze flowcharts, architecture diagrams, and technical illustrations
• 🖥️ Screenshot Analysis - Understand UI mockups and interface screenshots
• 💰 Cost Transparency - Separate tracking of vision API costs vs. text processing
• 🎯 Three Processing Modes - skip (default), describe (alt text only), vision (full AI processing)
• ⚡ Batch Processing - Efficient handling of documents with multiple images

Autonomous Vision-Based Browsing (v0.3.52 - v0.3.56)

• 🤖 Fully Autonomous - Agent navigates websites and completes tasks without manual intervention
• 👁️ Vision-Powered - Uses Claude Vision API to "see" and understand web pages
• 🎯 Multi-Step Tasks - Handles complex workflows (search, filter, compare, extract)
• 🔗 Tool Chaining - Seamlessly integrates with WebSearchTool and login_to_website
• 🔒 Authenticated Browsing - Works with saved login sessions

Agentic Features (v0.4.0) 🆕

• 🧠 Persistent Memory - Cross-session memory with YAML frontmatter files and keyword relevance selection
• 🤖 Sub-Agent Workers - Spawn parallel pydantic-ai agents for concurrent research and verification
• 📋 Plan Mode - AI proactively enters plan mode for complex tasks, presents step-by-step plans for approval
• 🔄 Token Budget Auto-Continue - Automatically continues responses cut off by max_tokens
• ⚡ Extensible Skills - User-defined slash commands via YAML files in ~/.clawdeck/skills/
• 🔧 Hook System - Pre/post response hooks with built-in safety checks (runs automatically)

Advanced Agentic Features (v0.5.0) 🆕

• 💤 Dream System - Background memory consolidation reviews recent sessions automatically
• 📦 Context Compaction - Auto-drops old messages when conversation exceeds 50 messages
• ⌨️ Vim Mode - Vi-style editing in the terminal (toggle with /vim)
• 🎙️ Voice Input - Speech-to-text via Google (free) or OpenAI Whisper
• 🐱 Buddy Companion - Virtual pet with species, rarity, personality, and event reactions
• ⏰ Cron Agents - Schedule recurring background tasks (e.g., monitor CI every 5 minutes)
• 🔌 Plugin System - Install/create plugins in ~/.clawdeck/plugins/ with YAML manifests
• 🔍 LSP Diagnostics - Run pyright/ruff diagnostics with /diagnostics
• ⏪ Rewind - Undo mistakes by reverting to previous conversation states

🎮 Usage Examples

Starting a New Project

You: Create a FastAPI app with authentication

Clawdeck:
- Generates main.py with FastAPI setup
- Creates auth middleware
- Adds example routes
- Provides setup instructions

Updating Existing Code

You: Add logging to my script.py

Clawdeck:
- Reads current script.py
- Adds logging configuration
- Updates functions with log statements
- Preserves existing functionality

Executing Commands

You: Run the analysis script

Clawdeck: [Generates the command to run]

======================================================================
⚠️  COMMAND EXECUTION CONFIRMATION
======================================================================
Command: python analysis.py
Directory: /current/working/directory
Permissions: Full user permissions
======================================================================

>>> WAITING FOR YOUR RESPONSE <<<

Execute this command? (y/N): y

✅ Command executed successfully
[Shows output]

Note: When you see the confirmation prompt, the "thinking" spinner may still appear in the background. This is normal - just type y and press Enter to proceed, or N to cancel.

Web Search & Resource Finding

You: Find a popular GitHub repo for machine learning

Clawdeck: [Searches the web]

Here are some popular GitHub repositories for machine learning:

1. **tensorflow/tensorflow** ⭐ 185k stars
   https://github.com/tensorflow/tensorflow
   - End-to-end machine learning platform
   - Used by Google and industry leaders

2. **pytorch/pytorch** ⭐ 82k stars
   https://github.com/pytorch/pytorch
   - Deep learning framework by Meta
   - Popular in research and production

3. **scikit-learn/scikit-learn** ⭐ 59k stars
   https://github.com/scikit-learn/scikit-learn
   - Classic ML algorithms for Python
   - Great for beginners and experts

[Sources: GitHub search results, updated recently]

You: What's the weather in San Francisco?

Clawdeck: [Searches for current weather]

Current weather in San Francisco:
🌤️ 62°F (17°C), Partly cloudy
💨 Wind: 12 mph
💧 Humidity: 65%
🌅 Sunrise: 7:15 AM | Sunset: 5:02 PM

Source: [Weather service URL]

Direct Website Fetching

You: Read https://github.com/yiqiao-yin/deepspeed-course

Clawdeck: [Fetches the specific URL directly]

📄 **Fetched:** https://github.com/yiqiao-yin/deepspeed-course

# DeepSpeed Course Repository

## Overview
This repository contains comprehensive course materials for DeepSpeed training...

## Course Contents
1. **Distributed Training** - Multi-GPU training strategies
2. **Memory Optimization** - ZeRO optimization techniques
3. **Pipeline Parallelism** - Efficient model parallelism
4. **Performance Tuning** - Best practices and optimizations

[Full page content extracted and converted to markdown]

When to use what:

• fetch_website: When you have a specific URL → Read https://example.com
• Web Search: When you want to find something → Find ML repos

You: Show cache stats

Clawdeck: 📊 **Website Cache Statistics**

**Location:** `~/.clawdeck/cache/fetched_sites`

**Total Entries:** 3
**Total Size:** 2.4 MB
**Expired Entries:** 0

**Cached URLs:**
- ✓ 5m old: https://github.com/yiqiao-yin/deepspeed-course
- ✓ 12m old: https://python.org/downloads
- ✓ 25m old: https://docs.anthropic.com

Document Reading with Vision Mode

You: Read quarterly_report.docx with vision mode

Clawdeck: [Extracts and processes document with image descriptions]

# Quarterly Report Summary

## Executive Overview
Revenue increased by 23% year-over-year, driven by strong performance in...

📊 **[Image 1]:** Bar chart showing quarterly revenue growth from Q1 to Q4.
Q4 shows the highest revenue at approximately $2.5M, representing a 23%
increase from Q3. All quarters show positive growth compared to the previous year.

## Market Analysis
Our market share expanded across all regions...

📐 **[Image 2]:** System architecture diagram depicting three layers:
frontend (React), API layer (FastAPI), and database (PostgreSQL).
Shows data flow from user requests through authentication middleware
to the backend services.

💰 **Vision API Cost:** $0.06 (2 images processed)
📊 **Token Usage:** 1,175 input tokens, 125 output tokens

[Use /tokens to see detailed cost breakdown]

Image Handling Modes:

• skip (default) - Ignore images entirely, no API calls
• describe - Extract alt text and captions only (no API calls)
• vision - Full Claude Vision API processing (costs ~$0.01-0.05 per image)

🎯 Commands

Chat Commands

Command	Description
<message>	Chat with the AI assistant
Enter	Submit your message
Ctrl+Enter	Add a new line (multi-line input)
exit or quit	End the session

Slash Commands

Command	Description	Version
/clear	Clear conversation history and reset counters	v0.2.8
/history	Display conversation history	v0.2.8
/save <file>	Save session to JSON	v0.2.8
/load <file>	Load session from JSON	v0.2.8
/tokens	Show token usage and costs	v0.2.8
/model [name]	Show/switch model (haiku/sonnet/opus)	v0.3.0
/config	Show current configuration	v0.3.1
/help	Display help	v0.2.8
/memory [list|save|search|delete]	Manage persistent memories	v0.4.0
/plan [approve|reject|skip|status]	Manage execution plans	v0.4.0
/skills	List custom skills	v0.4.0
/hooks	Show registered hooks and stats	v0.4.0
/workers	Show sub-agent task status	v0.4.0
/budget	Show token budget stats	v0.4.0
/dream	Show dream consolidation status	v0.5.0
/compact	Show context compaction stats	v0.5.0
/vim	Toggle vim editing mode	v0.5.0
/voice	Toggle voice input	v0.5.0
/buddy	Toggle virtual companion	v0.5.0
/cron [add|delete|pause|resume]	Manage scheduled jobs	v0.5.0
/plugins [create|install|uninstall|reload]	Manage plugins	v0.5.0
/diagnostics	Run pyright/ruff diagnostics	v0.5.0
/rewind [undo|<id>]	Revert conversation state	v0.5.0

Example Usage:

You: Write a data analysis script
Clawdeck: [Creates analysis.py]

You: /tokens
[Shows token usage: 1,500 input tokens, 800 output tokens, $0.02 cost]

You: /model
[Shows current model: Sonnet 4, pricing: $3.00/$15.00 per M tokens]

You: /model haiku
✓ Switched to Haiku (claude-haiku-4-5)

You: /save my_analysis_session.json
✓ Session saved to: my_analysis_session.json

You: /clear
✓ Conversation history cleared. Token counters reset.

You: /load my_analysis_session.json
✓ Session loaded from: my_analysis_session.json

📚 Documentation

Full documentation: https://yiqiao-yin.github.io/clawdeck/docs/

Key pages:

• Features Overview - All features with comparisons
• Memory & Skills - Persistent memory and custom commands
• Planning & Sub-Agents - Plan mode and parallel workers
• Hooks & Token Budget - Pipeline hooks and auto-continue
• Dream & Compaction - Background memory consolidation
• Vim, Voice & Buddy - Input modes and companion
• Cron, Plugins & LSP - Scheduled agents, plugins, diagnostics, rewind
• System Architecture - Architecture overview with diagrams
• Commands Reference - All slash commands

🛠️ Development & Testing

Prerequisites

• Python >= 3.10
• Poetry (package manager)
• Anthropic API key

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/yiqiao-yin/clawdeck.git
cd clawdeck

2. Install Poetry (if not already installed):

curl -sSL https://install.python-poetry.org | python3 -

3. Install dependencies:

poetry install

This will:

• Create a virtual environment
• Install all production dependencies from pyproject.toml
• Install development dependencies (pytest, pytest-asyncio, pytest-mock)
• Install the package in editable mode

Running Tests

Run all tests with verbose output:

# Skip command confirmation prompts in tests
CLAWDECK_SKIP_CONFIRM=1 poetry run pytest tests/ -v

Run tests with short traceback:

CLAWDECK_SKIP_CONFIRM=1 poetry run pytest tests/ -v --tb=short

Run specific test file:

poetry run pytest tests/test_agent.py -v

Run specific test class:

poetry run pytest tests/test_utils.py::TestExecuteCommandSafe -v

Run with coverage report:

poetry run pytest tests/ --cov=clawdeck --cov-report=html

Test Structure

tests/
├── __init__.py
├── test_agent.py          # Agent and tool tests (93 tests)
├── test_cli.py            # CLI and slash command tests (33 tests)
├── test_config.py         # Configuration tests (25 tests)
├── test_utils.py          # Utility function tests (29 tests)
├── test_memory.py         # Memory system tests (14 tests)
├── test_subagent.py       # Sub-agent worker tests (14 tests)
├── test_planner.py        # Plan mode tests (26 tests)
├── test_token_budget.py   # Token budget tests (12 tests)
├── test_skills.py         # Skills system tests (13 tests)
├── test_hooks.py          # Hook system tests (20 tests)
├── test_dream.py          # Dream consolidation tests (11 tests)
└── test_v050_features.py  # Compaction, vim, voice, buddy, cron,
                           # plugins, LSP, rewind tests (62 tests)
                           # Total: 333+ tests

Expected Output

When all tests pass, you should see:

============================= test session starts ==============================
platform linux -- Python 3.10.12, pytest-8.4.2, pluggy-1.6.0
cachedir: .pytest_cache
rootdir: /home/workbench/clawdeck/clawdeck
configfile: pyproject.toml
plugins: asyncio-1.2.0, mock-3.15.1
collected 133 items

tests/test_agent.py::TestClawdeckAgent::test_agent_initialization PASSED   [  1%]
tests/test_agent.py::TestHistoryManagement::test_clear_history PASSED    [ 18%]
tests/test_agent.py::TestStreaming::test_chat_stream_method_exists PASSED [ 40%]
tests/test_cli.py::TestSlashCommands::test_clear_command PASSED          [ 42%]
tests/test_config.py::TestClawdeckConfig::test_default_values PASSED       [ 60%]
...
tests/test_utils.py::TestExecuteCommandSafe::test_execute_python_script PASSED [100%]

============================== 133 passed in 2.64s

Building and Publishing

Build the package:

poetry build

This creates:

• dist/clawdeck-X.Y.Z.tar.gz (source distribution)
• dist/clawdeck-X.Y.Z-py3-none-any.whl (wheel)

Publish to PyPI:

poetry publish

Build and publish in one command:

poetry build && poetry publish

Version Management

Update version in these files:

• pyproject.toml - version = "X.Y.Z"
• clawdeck/__init__.py - __version__ = "X.Y.Z"
• USE_CASES.md - Update changelog and version number

Development Workflow

1. Create a feature branch:

git checkout -b feature/your-feature-name

2. Make changes and test:

# Make your changes
CLAWDECK_SKIP_CONFIRM=1 poetry run pytest tests/ -v

3. Update version and documentation:

# Update version in pyproject.toml, __init__.py, USE_CASES.md

4. Commit and push:

git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

5. Build and publish:

poetry build && poetry publish
git push origin main

🧪 Environment Variables

Core Configuration

Variable	Description	Default
CHOOSE_CLIENT	AI provider selection: 1=Anthropic, 2=Bedrock, 3=Gemini, 0=Auto-detect	0 (auto)
MAX_TOKEN	Maximum tokens for model output (can also use --max-token CLI arg)	4096
MAX_INTERNET_SEARCH_LIMIT	Maximum web searches per session (can also use --max-internet-search-limit CLI arg)	5
CLAWDECK_SKIP_CONFIRM	Skip command execution confirmations	0 (disabled)
CLAWDECK_BROWSER_SHOW	Show browser window during automation (can also use --show-browser CLI arg)	0 (headless)

Anthropic Claude (CHOOSE_CLIENT=1)

Variable	Description	Default
ANTHROPIC_API_KEY	Anthropic API key	None (required)
ANTHROPIC_MODEL	Model to use (e.g., claude-sonnet-4-6)	Auto-selected

Google Gemini (CHOOSE_CLIENT=3) 🆕

Variable	Description	Default
GEMINI_API_KEY or GOOGLE_API_KEY	Google Gemini API key	None (required)
GEMINI_MODEL	Model to use (e.g., gemini-2.5-flash, gemini-2.5-pro)	gemini-2.5-flash

AWS Bedrock (CHOOSE_CLIENT=2)

Variable	Description	Default
AWS_ACCESS_KEY_ID	AWS access key ID	None (required)
AWS_SECRET_ACCESS_KEY	AWS secret access key	None (required)
AWS_SESSION_TOKEN	AWS session token (optional, for temporary credentials)	None
AWS_REGION	AWS region for Bedrock (e.g., us-west-2)	us-east-1
ANTHROPIC_MODEL	Model ARN (e.g., us.anthropic.claude-sonnet-4-5-20250929-v1:0)	Auto-selected

Integration Tokens (Optional)

Variable	Description	Default
HF_TOKEN or HUGGINGFACE_TOKEN	HuggingFace API token (for HF features)	None
GH_TOKEN or GITHUB_TOKEN	GitHub access token (for GitHub features)	None

Setup Example (Anthropic API):

# .env file
CHOOSE_CLIENT=1
ANTHROPIC_API_KEY=your_anthropic_key
MAX_TOKEN=4096
MAX_INTERNET_SEARCH_LIMIT=5
GH_TOKEN=ghp_your_github_token
HF_TOKEN=hf_your_huggingface_token
CLAWDECK_SKIP_CONFIRM=0
CLAWDECK_BROWSER_SHOW=0

Setup Example (Google Gemini): 🆕

# .env file
CHOOSE_CLIENT=3
GEMINI_API_KEY=your_gemini_key
GEMINI_MODEL=gemini-2.5-flash
MAX_TOKEN=4096
GH_TOKEN=ghp_your_github_token
HF_TOKEN=hf_your_huggingface_token
CLAWDECK_SKIP_CONFIRM=0
CLAWDECK_BROWSER_SHOW=0

Setup Example (AWS Bedrock):

# .env file
CHOOSE_CLIENT=2
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_SESSION_TOKEN=your_session_token
AWS_REGION=us-west-2
ANTHROPIC_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0
MAX_TOKEN=4096
GH_TOKEN=ghp_your_github_token
HF_TOKEN=hf_your_huggingface_token
CLAWDECK_SKIP_CONFIRM=0
CLAWDECK_BROWSER_SHOW=0

Notes:

• Set CHOOSE_CLIENT=0 (or omit it) for auto-detection based on available API keys
• Set CLAWDECK_SKIP_CONFIRM=1 to skip confirmation prompts (useful for testing or automation)
• Set CLAWDECK_BROWSER_SHOW=1 to show browser window during automation (useful for debugging)
• Gemini is ~40x cheaper than Claude and has 2M context window!

📋 Requirements

• Python >= 3.10, < 4.0
• Dependencies (automatically installed):
  • click>=8.1.0 - CLI framework
  • pydantic-ai>=1.13.0 - AI agent framework with web search support
  • anthropic>=0.39.0 - Anthropic API client
  • rich>=13.0.0 - Terminal formatting
  • python-dotenv>=1.2.1 - Environment variable management
  • prompt-toolkit>=3.0.0 - Advanced input handling
  • pyyaml>=6.0.0 - Configuration file support
  • huggingface-hub>=0.20.0 - HuggingFace integration
  • crawl4ai>=0.7.6 - LLM-optimized web crawler for browser use

Note: Browser use requires Playwright browser binaries (~200MB):

playwright install chromium

Web Terminal

Clawdeck is also available as a browser-based terminal at:

https://clawdeckterminal-app.azurewebsites.net

This is a real Linux terminal running in your browser with clawdeck pre-installed. No account or login required -- just open the URL and start using it.

Usage

1. Open the terminal URL in your browser
2. Export your API key:

   export ANTHROPIC_API_KEY=sk-ant-your-key-here
   

3. Launch the assistant:

   clawdeck
   

All four AI providers are supported (Anthropic, AWS Bedrock, Google Gemini, OpenAI). Your API keys are never stored on the server -- they only exist in your browser terminal session and are discarded when you close the tab.

Self-Hosting

To deploy your own instance, you need Docker and Azure CLI:

az login
bash deploy-azure.sh

This creates four Azure resources (all prefixed clawdeckterminal):

Resource	Name	Purpose
Resource Group	clawdeckterminal-rg	Container for all resources
Container Registry	clawdeckterminalacr	Stores the Docker image
App Service Plan	clawdeckterminal-plan (B1)	Compute for the web app
Web App	clawdeckterminal-app	Serves the terminal UI

The container uses ttyd to expose a bash shell over WebSocket, with clawdeck pre-installed. No secrets are baked into the image.

To tear down:

az group delete --name clawdeckterminal-rg --yes

Related Files

• Dockerfile.web -- Container image definition
• deploy-azure.sh -- Azure deployment script
• terminal-motd.sh -- Welcome message shown on terminal connect
• docker-compose.web.yml -- Local development with Docker Compose

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (CLAWDECK_SKIP_CONFIRM=1 poetry run pytest tests/ -v)
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Yiqiao Yin

• Email: yiqiao.yin@wyn-associates.com
• GitHub: @yiqiao-yin

🙏 Acknowledgments

• Built with Anthropic Claude - Advanced AI assistant
• Powered by pydantic-ai - Python agent framework
• CLI framework by Click
• Terminal UI by Rich

🔗 Links

• PyPI: https://pypi.org/project/clawdeck/
• GitHub: https://github.com/yiqiao-yin/clawdeck
• Documentation:
  • USE_CASES.md - Usage examples and workflows
  • COST.md - Pricing and token configuration
  • SYSTEM.md - Architecture overview
• Get API Key: https://console.anthropic.com/

---

Current Version: 0.5.3 Last Updated: April 2026