Metadata-Version: 2.4
Name: clud
Version: 1.0.22
Summary: Claude Code in YOLO mode
License: BSD 3-Clause License
Keywords: claude,cli,ai
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyring>=24.0.0
Requires-Dist: fasteners>=0.17.0
Requires-Dist: appdirs>=1.4.4
Requires-Dist: disklru>=0.1.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pywinpty>=3.0.0; sys_platform == "win32"
Requires-Dist: running-process>=1.0.7
Requires-Dist: codeup>=1.0.8
Requires-Dist: nodeenv>=1.8.0
Requires-Dist: nodejs-wheel>=22.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: markdown2>=2.4.0
Requires-Dist: websockets>=12.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.12.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-telegram-bot>=20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=2.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pyright>=1.1.0; extra == "dev"
Provides-Extra: keyring-fallbacks
Requires-Dist: keyrings.cryptfile>=1.3.0; extra == "keyring-fallbacks"
Requires-Dist: cryptography>=3.0.0; extra == "keyring-fallbacks"
Provides-Extra: posix
Requires-Dist: zcmds_win32>=1.2.0; sys_platform == "win32" and extra == "posix"
Provides-Extra: full
Requires-Dist: zcmds_win32>=1.2.0; sys_platform == "win32" and extra == "full"
Dynamic: license-file

# clud

[![Build and Push Multi Docker Image](https://github.com/zackees/clud/actions/workflows/build_multi_docker_image.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/build_multi_docker_image.yml)[![Windows Tests](https://github.com/zackees/clud/actions/workflows/windows-test.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/windows-test.yml)[![macOS Tests](https://github.com/zackees/clud/actions/workflows/macos-test.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/macos-test.yml)[![Linux Tests](https://github.com/zackees/clud/actions/workflows/linux-test.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/linux-test.yml)
[![Integration Tests](https://github.com/zackees/clud/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/integration-tests.yml)

![hero-clud](https://github.com/user-attachments/assets/4009dfee-e703-446d-b073-80d826708a10)

**A Python CLI that runs Claude Code in God mode by default, eliminating permission prompts and optimizing for long term agent work**

The name `clud` is simply a shorter, easier-to-type version of `claude`.

## Why is clud better?

Because safety is number three.

<img width="556" height="500" alt="image" src="https://github.com/user-attachments/assets/520f6131-5409-4b29-927a-2b946c4ecb79" />

## Installation

```bash
pip install clud  # Everything included: CLI, service, and central control plane
```

## Quick Start

```bash
# Unleash Claude Code instantly (YOLO mode enabled by default)
clud

# Execute with specific prompt
clud -p "refactor this entire app"

# Send direct message
clud -m "add error handling"
```

## Operation Modes

### Default Mode

Launches Claude Code directly with YOLO mode enabled - no permission prompts, maximum velocity:

```bash
clud [directory]                    # Unleash Claude Code in directory
clud -p "refactor this entire app"  # Execute with specific prompt
clud -m "add error handling"        # Send direct message
clud --continue                     # Continue previous conversation
```

**Features:**
- Claude Code with dangerous permissions enabled by default
- Zero interruption workflow - no safety prompts
- Direct prompt execution for rapid iteration
- Supports all standard Claude Code arguments

### Advanced Modes

#### Fix Mode - Automated Linting & Testing
Automatically fix linting issues and run tests in a loop:

```bash
clud fix                          # Fix linting and run tests locally
clud fix https://github.com/...   # Fix issues from GitHub URL logs
```

Fix mode runs:
1. `codeup --lint --dry-run` up to 5 times, fixing issues each iteration
2. `codeup --test --dry-run` up to 5 times, fixing issues each iteration
3. Final lint pass to ensure code quality

#### Up Mode - Project Maintenance
Run the global `codeup` command with auto-fix capabilities:

```bash
clud up                           # Run codeup with auto-fix (up to 5 retries)
clud --codeup-publish            # Run codeup -p for publishing
```

### Task System

Clud includes a powerful task management system for structured development workflows:

```bash
clud --task task.md               # Open task file and execute autonomously
```

**Task Workflow:**
- Opens task file in editor for review/editing
- Executes task autonomously using research-plan-implement-test-fix-lint cycle
- Continues until completion, needs feedback, or reaches 50 iterations
- Provides final summary with status (SUCCESS, NEED FEEDBACK, or NOT DONE)

### Kanban Board

Launch an interactive kanban board for task management:

```bash
clud --kanban                     # Launch vibe-kanban board
```

### Central Control Plane

`clud` now includes a central control plane for monitoring and managing agents across your development environment:

```bash
clud-central serve                # Start central control plane (default port :8000)
clud-central serve --host 0.0.0.0 --port 9000  # Custom host/port
clud-central migrate              # Run database migrations
clud-central bot                  # Run Telegram bot (requires bot extra)
```

**Features:**
- Web-based UI for agent monitoring and management
- Real-time WebSocket updates for agent status
- JWT authentication for secure access
- SQLite database for persistent storage
- Telegram bot integration for notifications
- RESTful API for programmatic access

**Port Assignments:**
- Background service: `:7565`
- Central control plane: `:8000` (default, configurable)

**Architecture:**
The central control plane provides a unified interface for monitoring all `clud` agents running on your system. Agents register with the background service (`:7565`), which communicates with the central control plane to provide real-time status updates, metrics, and control capabilities.

## Configuration

### API Key Setup

```bash
# Interactive setup (recommended)
clud --login

# Use environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

# Use command line
clud --api-key "sk-ant-..."
```

The API key is stored securely in `~/.clud/anthropic-api-key.key` for future use.



## Command Reference

### Main Commands
```bash
clud [directory]                  # Launch in directory
clud -p "prompt"                  # Execute with prompt
clud -m "message"                 # Send message
clud --continue                   # Continue conversation
clud --api-key KEY                # Specify API key
clud --dry-run                    # Show command without executing
```

### Utility Commands
```bash
clud --login                      # Configure API key
clud --task PATH                  # Process task file
clud --lint                       # Run linting workflow
clud --test                       # Run testing workflow
clud --fix [URL]                  # Fix linting and tests
clud --codeup                     # Run codeup with auto-fix
clud --codeup-publish             # Run codeup -p
clud --kanban                     # Launch kanban board
clud --help                       # Show help
```

### Central Control Plane Commands
```bash
clud-central serve                # Start central control plane
clud-central serve --host HOST    # Specify host
clud-central serve --port PORT    # Specify port
clud-central serve --reload       # Enable auto-reload
clud-central migrate              # Run database migrations
clud-central bot                  # Run Telegram bot
clud-central --help               # Show help
```

### Quick Mode Aliases
```bash
clud fix                          # Alias for --fix
clud up                           # Alias for --codeup
```

## Development

### Setup Development Environment

```bash
# Install dependencies (requires uv)
bash install

# Activate virtual environment
source activate

# Run tests
bash test

# Run linting
bash lint
```

### Project Structure

```
clud/
├── src/clud/              # Main package source
│   ├── cli.py            # CLI router and main entry point
│   ├── agent/            # Agent execution subpackage
│   │   ├── foreground.py      # Direct Claude Code execution
│   │   ├── foreground_args.py # Argument parsing
│   │   ├── completion.py      # Completion detection
│   │   └── tracking.py        # Agent tracking
│   ├── service/          # Background service (formerly daemon)
│   │   ├── server.py          # HTTP server on :7565
│   │   ├── registry.py        # Agent registry
│   │   ├── models.py          # Shared models
│   │   └── central_client.py  # Connects to central
│   ├── central/          # Central control plane
│   │   ├── app.py            # FastAPI application
│   │   ├── cli.py            # Central CLI entry point
│   │   ├── auth.py           # JWT authentication
│   │   ├── database.py       # SQLAlchemy models
│   │   ├── telegram_bot.py   # Telegram integration
│   │   ├── websocket_handlers.py # WebSocket protocol
│   │   └── static/           # Built React UI
│   ├── task.py           # Task management system
│   └── ...
├── packages/web/         # React frontend source
├── tests/                # Unit and integration tests
├── pyproject.toml        # Package configuration
└── ...
```

### Requirements

- **Python 3.13+** (uses modern Python features)
- **uv** (package manager) - https://docs.astral.sh/uv/
- **git-bash** (on Windows)

### Windows Development

This project is designed to work on Windows using `git-bash` for proper Unix-like shell support. UTF-8 encoding is handled automatically in all shell scripts.

### Testing

```bash
# Run all tests
bash test

# Run with verbose output
bash test -v

# Run integration tests (sequential, avoid resource conflicts)
uv run pytest tests/integration/ -v --tb=short --maxfail=1

# Run specific test file
bash test tests/test_task.py
```

### Code Quality

```bash
# Run full linting suite
bash lint

# Run ruff check with auto-fix
uv run ruff check --fix src/ tests/

# Run ruff format
uv run ruff format src/ tests/

# Run type checking
uv run pyright
```

## Entry Points

The package provides two CLI entry points:

- `clud` - Main CLI (runs Claude Code in YOLO mode)
- `clud-central` - Central control plane for monitoring and managing agents

## Cool Projects

### Curated Lists & Frameworks
- **Awesome Claude Code**: https://github.com/hesreallyhim/awesome-claude-code - Curated list of commands, files, and workflows
- **SuperClaude Framework**: https://github.com/SuperClaude-Org/SuperClaude_Framework - Framework for building Claude Code applications
- **AB Method**: https://github.com/ayoubben18/ab-method - Workflow methodology for Claude Code

### Web UIs
- **Claude Code WebUI** (sugyan): https://github.com/sugyan/claude-code-webui - Web interface for Claude Code
- **ClaudeCodeUI**: https://github.com/siteboon/claudecodeui - Alternative web UI for Claude Code

### Official Tools
- **Claude Code GitHub Action**: https://github.com/anthropics/claude-code-action - AI-powered automation for GitHub PRs and issues

### IDE Integrations
- **claude-code.nvim**: Neovim integration for Claude Code
- **claude-code-ide.el**: Emacs integration with ediff-based code suggestions

### Monitoring & Management
- **CC Usage**: CLI tool for managing and analyzing Claude Code usage and costs
- **ccflare**: Claude Code usage dashboard with web UI

### Workflow Tools
- **Crystal**: Desktop application for orchestrating and monitoring Claude Code agents
- **Happy Coder**: Spawn and control multiple Claude Codes in parallel with push notifications
- **Claude Task Runner**: Manages context isolation and focused task execution

## License

BSD 3-Clause License

## Contributing

Contributions are welcome! Please ensure all tests pass and code is properly linted before submitting PRs.







```bash
# Setup environment
bash install

# Run tests
bash test

# Lint code
bash lint
```
