# QwenClaw 🐾

**A persistent personal assistant daemon for Qwen Code that never sleeps.**

QwenClaw runs as a background daemon, executing scheduled tasks, responding to Telegram messages, and providing a web dashboard for monitoring and management. It automatically starts with your system and persists across all restarts.

![Version](https://img.shields.io/badge/version-1.4.2-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)
![Rust](https://img.shields.io/badge/Rust-1.70+-orange)
![Skills](https://img.shields.io/badge/skills-77-green)

---

## Features

| Feature | Description |
|---------|-------------|
| **💓 Heartbeat** | Periodic check-ins on configurable intervals with quiet hours support |
| **⏰ Cron Jobs** | Schedule any prompt using standard cron syntax (timezone-aware) |
| **📱 Telegram Bot** | Chat with your agent via text, images, and voice commands |
| **🌐 Web Dashboard** | Monitor runs, edit jobs, and view logs in real-time |
| **🔒 Security Levels** | Four granular levels from read-only to full system access |
| **🔄 Auto-Start** | Automatically starts when you log in (Windows/Linux/macOS) |
| **💾 Persistent State** | All settings, jobs, and sessions saved to disk |

---

## Quick Install

### One-Command Install

**Windows (PowerShell):**
```powershell
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
cd QwenClaw-with-Auth
.\install.ps1
```

**Linux/macOS (Bash):**
```bash
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
cd QwenClaw-with-Auth
chmod +x install.sh
./install.sh
```

This will:
1. Install dependencies (Bun if missing)
2. Create all necessary directories
3. Set up auto-start for your system
4. Create default configuration
5. Add example scheduled job

### Configure Qwen Provider (Default)

QwenClaw uses **Qwen** as the default AI provider.

1. Get API key: https://platform.qwen.ai/
2. Create `rig-service/.env`:
   ```bash
   cd rig-service
   cp .env.example .env
   ```
3. Edit `.env`:
   ```env
   QWEN_API_KEY=sk-your-key-here
   QWEN_BASE_URL=https://api.qwen.ai/v1
   RIG_DEFAULT_PROVIDER=qwen
   RIG_DEFAULT_MODEL=qwen-plus
   ```

See `docs/QWEN-SETUP.md` for detailed setup.

---

## Manual Installation

### Prerequisites

- [Qwen Code](https://github.com/QwenLM/Qwen-Code) installed and configured
- [Bun](https://bun.sh/) package manager
- Git

### Steps

```bash
# Clone the repository
git clone https://github.rommark.dev/admin/QwenClaw-with-Auth.git
cd QwenClaw-with-Auth

# Install dependencies
bun install

# Start the daemon
bun run start --web
```

---

## Auto-Start Configuration

QwenClaw is configured to start automatically when you log in.

### Windows
- Uses Startup Folder (`shell:startup`)
- No admin privileges required
- To disable: Run `.\scripts\uninstall-startup.ps1`

### Linux
- **Systemd service** (if available, requires sudo)
- **Desktop autostart** (for GUI sessions)
- To disable: `systemctl disable qwenclaw.service` or remove `~/.config/autostart/qwenclaw.desktop`

### macOS
- Uses LaunchAgent
- To disable: `launchctl unload ~/Library/LaunchAgents/com.qwenclaw.daemon.plist`

---

## Usage

### Start the Daemon

```bash
# Start with web UI
bun run start --web

# Start with custom port
bun run start --web --web-port 8080

# Start with trigger prompt
bun run start --trigger --prompt "Check my pending tasks"

# One-shot prompt (no daemon)
bun run start --prompt "What's the weather?"
```

### Check Status

```bash
bun run status
```

### Stop the Daemon

```bash
bun run stop
```

### Send a Prompt

```bash
# Send to running daemon
bun run send "Check my calendar"

# Send and forward to Telegram
bun run send --telegram "Summarize my tasks"
```

### Clear State

```bash
bun run clear
```

---

## Configuration

### Settings File

Location: `~/.qwen/qwenclaw/settings.json`

```json
{
  "model": "qwen-plus",
  "api": "",
  "autoStart": true,
  "fallback": {
    "model": "",
    "api": ""
  },
  "timezone": "UTC",
  "timezoneOffsetMinutes": 0,
  "heartbeat": {
    "enabled": true,
    "interval": 15,
    "prompt": "",
    "excludeWindows": [
      {
        "start": "22:00",
        "end": "08:00",
        "days": [0, 1, 2, 3, 4, 5, 6]
      }
    ]
  },
  "telegram": {
    "token": "",
    "allowedUserIds": []
  },
  "security": {
    "level": "moderate",
    "allowedTools": [],
    "disallowedTools": []
  },
  "web": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 4632
  }
}
```

### Security Levels

| Level | Description |
|-------|-------------|
| `locked` | Read-only access (Read, Grep, Glob tools only) |
| `strict` | No Bash, WebSearch, or WebFetch |
| `moderate` | All tools available, scoped to project directory |
| `unrestricted` | All tools, no directory restrictions |

---

## Scheduled Jobs

Create jobs in `~/.qwen/qwenclaw/jobs/` as markdown files with frontmatter.

### Example: Daily Standup

File: `~/.qwen/qwenclaw/jobs/daily-standup.md`

```markdown
---
schedule: 0 9 * * *
recurring: true
notify: true
---

Good morning! Here's your daily check-in:
1. What are today's priorities?
2. Any pending tasks from yesterday?
3. Summarize my calendar for today.
```

### Cron Syntax

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6)
│ │ │ │ │
* * * * *
```

### Examples

| Expression | Description |
|------------|-------------|
| `*/5 * * * *` | Every 5 minutes |
| `0 */2 * * *` | Every 2 hours |
| `0 9 * * 1-5` | 9 AM on weekdays |
| `0 0 1 * *` | First day of every month |
| `0 0 * * 0` | Every Sunday at midnight |

---

## Telegram Integration

### Setup

1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram
2. Get your bot token
3. Find your Telegram user ID (use [@userinfobot](https://t.me/userinfobot))
4. Add to settings:

```json
{
  "telegram": {
    "token": "YOUR_BOT_TOKEN",
    "allowedUserIds": [YOUR_USER_ID]
  }
}
```

### Bot Commands

- `/start` - Get started with the bot
- `/reset` - Reset the conversation session

### Features

- Text messages
- Image attachments (bot downloads and sends to Qwen)
- Voice messages (transcription requires whisper setup)
- Group chat support (mention bot or reply to its messages)
- Reactions support using `[react:emoji]` syntax in responses

---

## Web Dashboard

Access at: **http://127.0.0.1:4632** (or your configured port)

### Features

- Real-time daemon status
- Heartbeat configuration
- Job management (view, add, delete)
- Logs viewer
- Technical information

---

## Project Structure

```
QwenClaw-with-Auth/
├── src/
│   ├── commands/         # CLI commands
│   │   ├── start.ts      # Daemon start
│   │   ├── stop.ts       # Daemon stop
│   │   ├── status.ts     # Status check
│   │   ├── send.ts       # Send prompt
│   │   ├── clear.ts      # Clear state
│   │   └── telegram.ts   # Telegram bot
│   ├── ui/               # Web dashboard
│   │   ├── page/         # HTML/CSS/JS
│   │   └── services/     # API handlers
│   ├── config.ts         # Configuration management
│   ├── cron.ts           # Cron parsing
│   ├── jobs.ts           # Job scheduling
│   ├── runner.ts         # Qwen execution
│   ├── sessions.ts       # Session management
│   ├── timezone.ts       # Timezone utilities
│   ├── pid.ts            # PID file management
│   ├── statusline.ts     # Status line widget
│   ├── preflight.ts      # Plugin setup
│   └── index.ts          # Main entry point
├── prompts/              # Prompt templates
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── SOUL.md
│   └── heartbeat/
│       └── HEARTBEAT.md
├── scripts/              # Installation scripts
│   ├── install.sh        # Linux/macOS install
│   ├── install.ps1       # Windows install
│   ├── autostart.ps1     # Auto-start script
│   ├── install-startup.ps1   # Install auto-start
│   └── uninstall-startup.ps1 # Remove auto-start
├── package.json
├── tsconfig.json
├── README.md
└── QUICKSTART.md
```

---

## Data Locations

| Data | Location |
|------|----------|
| Settings | `~/.qwen/qwenclaw/settings.json` |
| Jobs | `~/.qwen/qwenclaw/jobs/*.md` |
| Logs | `~/.qwen/qwenclaw/logs/*.log` |
| Session | `~/.qwen/qwenclaw/session.json` |
| State | `~/.qwen/qwenclaw/state.json` |
| PID File | `~/.qwen/qwenclaw/daemon.pid` |

---

## Troubleshooting

### Daemon not starting on login

1. Check auto-start is configured:
   - Windows: Check `shell:startup` folder for shortcut
   - Linux: Check `systemctl status qwenclaw.service`
   - macOS: Check `launchctl list | grep qwenclaw`

2. Check logs:
   ```bash
   # Auto-start logs
   cat ~/.qwen/qwenclaw/autostart.log
   
   # Daemon logs
   ls -la ~/.qwen/qwenclaw/logs/
   ```

3. Start manually:
   ```bash
   bun run start --web
   ```

### Port already in use

Edit `~/.qwen/qwenclaw/settings.json`:
```json
{
  "web": {
    "port": 4633
  }
}
```

### Telegram bot not responding

1. Verify token is correct in settings
2. Check your user ID is in `allowedUserIds`
3. Enable debug mode: add `--debug` flag when starting

### Jobs not running

1. Verify cron syntax (use [crontab.guru](https://crontab.guru))
2. Check timezone settings
3. Review job file format (frontmatter + prompt)

---

## Updating

```bash
# Navigate to repository
cd QwenClaw-with-Auth

# Pull latest changes
git pull

# Reinstall dependencies
bun install

# Restart daemon
bun run stop
bun run start --web
```

---

## Uninstall

### Remove Auto-Start

**Windows:**
```powershell
.\scripts\uninstall-startup.ps1
```

**Linux:**
```bash
sudo systemctl disable qwenclaw.service
sudo systemctl stop qwenclaw.service
rm ~/.config/autostart/qwenclaw.desktop
```

**macOS:**
```bash
launchctl unload ~/Library/LaunchAgents/com.qwenclaw.daemon.plist
rm ~/Library/LaunchAgents/com.qwenclaw.daemon.plist
```

### Remove Data

```bash
# Remove all QwenClaw data
rm -rf ~/.qwen/qwenclaw

# Remove repository
rm -rf QwenClaw-with-Auth
```

---

## Versioning & Changelog

QwenClaw follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH).

### [1.4.2] - 2026-02-26

#### Added
- **QwenBot Integration** - AI assistant tool for Qwen Code:
  - Code analysis and review
  - Documentation generation
  - Test generation
  - Code explanation
  - Chat assistance
  - Configurable via ~/.qwen/qwenbot/config.json

### [1.4.1] - 2026-02-26

#### Added
- **shadcn/ui Design Skill** - Professional UI component design patterns:
  - 50+ shadcn/ui components (forms, navigation, feedback, overlays)
  - Accessible (WCAG compliant) patterns
  - Dark mode support
  - Responsive design patterns
  - React + Tailwind CSS + Radix UI
  - Integration with Rig UI agents

### [1.4.0] - 2026-02-26

#### Added
- **UI/UX Pro Max Skill** - Professional design intelligence with:
  - Design System Generator
  - 100+ reasoning rules
  - 67 UI styles
  - Multi-platform support (React, Vue, Next.js, Flutter, SwiftUI, etc.)
- **Claude Codex Settings** - Enhanced development workflow with plugins:
  - Azure Tools, GitHub Dev, Linear Tools
  - Supabase Tools, Playwright Tools
  - Plugin Dev, MCP Integration
- **Superpowers Skills** - Complete SDLC workflow:
  - Brainstorming, Writing Plans, TDD
  - Subagent-driven Development
  - Code Review, Git Worktrees
- **Spawner MCP Integration** - Auto-spawning specialist agents:
  - 50+ expert skills via MCP
  - Stack detection and auto-matching
  - Sharp edges detection
  - YAML-powered skills

#### Changed
- Updated skills index to v1.4.0 (75 total skills)
- Added Spawner MCP documentation

### [1.3.1] - 2026-02-26

#### Changed
- Qwen set as DEFAULT provider (was OpenAI)
- Default model: qwen-plus (was gpt-4)
- Added QWEN_BASE_URL support for custom endpoints
- Created docs/QWEN-SETUP.md - Complete Qwen setup guide

### [1.3.0] - 2026-02-26

#### Added
- **Full Rig Integration** - Rust-based AI agent framework
- **rig-service/** - Standalone Rust microservice with:
  - Multi-agent orchestration (Agent Councils)
  - Dynamic tool calling with ToolSet registry
  - RAG workflows with SQLite vector store
  - HTTP/REST API for TypeScript integration
- **TypeScript Client** - `src/rig/client.ts` for seamless integration
- **API Endpoints**:
  - `/api/agents` - Agent management
  - `/api/councils` - Multi-agent orchestration
  - `/api/tools` - Tool registry and search
  - `/api/documents` - Vector store for RAG
- **Documentation**: `docs/RIG-INTEGRATION.md` with full usage guide

#### Changed
- Updated Rig analysis doc with implementation details

### [1.2.0] - 2026-02-26

#### Added
- **10 OpenClaw Skills** from [awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills):
  - achurch (community sanctuary)
  - agent-council (multi-agent orchestration)
  - agent-identity-kit (AI agent identity)
  - mcp-builder (Model Context Protocol)
  - coder-workspaces (dev environment management)
  - backend-patterns (architecture patterns)
  - code-mentor (programming tutor with references)
  - coding-agent (run multiple coding agents)
  - ec-task-orchestrator (autonomous task management)
  - essence-distiller (content analysis)
- **Total Skills**: 35 (25 Claude + 10 OpenClaw)

### [1.1.0] - 2026-02-26

#### Added
- **Skills Integration**: Imported 25+ skills from [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills)
  - Content Research Writer
  - File Organizer
  - Developer Growth Analysis
  - Changelog Generator
  - Document Skills
  - Image Enhancer
  - Video Downloader
  - And 19 more...
- **Cross-platform support**: Full compatibility for Windows, Linux, and macOS
- **Skills index**: `skills/skills-index.json` for skill discovery
- **Installation scripts**: `install.sh` (Linux/macOS) and `install.ps1` (Windows)

#### Fixed
- Daemon startup issue on Windows (qwen.cmd path resolution)
- Settings file path (`.qwen/qwenclaw/settings.json`)
- Statusline command path (`.qwen/statusline.cjs`)
- Async/await handling in main entry point
- Shell execution for cross-platform command spawning

#### Changed
- Removed debug logging from production code
- Improved error handling and reporting
- Updated README with comprehensive documentation
- Added versioning and changelog section

### [1.0.0] - 2026-02-26

#### Added
- Initial release
- Daemon with auto-start capability
- Heartbeat system with quiet hours
- Cron job scheduling
- Telegram bot integration
- Web dashboard (http://127.0.0.1:4632)
- Four security levels (locked, strict, moderate, unrestricted)
- Session persistence
- Hot-reload configuration
- Windows Task Scheduler integration
- Linux systemd service support
- macOS LaunchAgent support

---

## License

MIT License - See [LICENSE](LICENSE) file for details.

---

## Acknowledgments

QwenClaw is inspired by [ClaudeClaw](https://github.com/moazbuilds/claudeclaw) by @moazbuilds.

---

## Support

For issues, questions, or contributions:
- Repository: https://github.rommark.dev/admin/QwenClaw-with-Auth
- Issues: https://github.rommark.dev/admin/QwenClaw-with-Auth/issues