# Persuade (Generic AI Development Tool Configurator)

A powerful CLI tool to sync Claude Code automation to your projects.

## Features

- **Smart Syncing**: Intelligent file categorization (sync, merge, skip, copy-once)
- **Settings Merging**: Preserves your local settings while importing template updates
- **Backup & Rollback**: Automatic backups before each sync with easy rollback
- **Shadow Mode**: Sync files but exclude from git (perfect for open-source projects)
- **Editable Mode**: Symlink files for live development on the template
- **Validation**: Doctor command to check and fix common misconfigurations

## Installation

```bash
pip install persuade
```

## Quick Start

### Basic Sync

```bash
# Sync Claude Code automation to your project
persuade sync ~/projects/my-app

# Preview changes without applying (dry run)
persuade sync --dry-run ~/projects/my-app
```

### Shadow Mode (Open Source Projects)

```bash
# Sync files but exclude from git (adds to .gitignore)
persuade sync --shadow ~/projects/open-source-app
```

### Editable Mode (Template Development)

```bash
# Symlink files for live development
persuade sync --editable ~/projects/my-app

# Changes to template instantly reflect in target
```

## Commands

### `persuade sync`

Sync Claude Code automation to target project.

**Options:**
- `--dry-run`: Preview changes without applying
- `--strict`: Remove non-template permissions
- `--force`: Skip confirmation prompts
- `--no-backup`: Skip backup creation (not recommended)
- `--exclude PATTERN`: Exclude files matching pattern (can be used multiple times)
- `--shadow`: Sync files but exclude from git
- `--editable, -e`: Symlink files for live development

**Examples:**
```bash
# Basic sync with backup
persuade sync ~/projects/my-app

# Preview changes
persuade sync --dry-run ~/projects/my-app

# Exclude specific patterns
persuade sync --exclude "*.yml" --exclude "hooks/*" ~/projects/my-app

# Shadow mode for open-source projects
persuade sync --shadow ~/projects/open-source-app
```

### `persuade doctor`

Validate and fix common misconfigurations.

**Options:**
- `--fix`: Automatically fix issues
- `--check-only`: Only report issues, don't fix

**Examples:**
```bash
# Check for issues
persuade doctor ~/projects/my-app

# Check and fix issues
persuade doctor --fix ~/projects/my-app
```

### `persuade help-command`

Show installation state and help for a project.

**Example:**
```bash
persuade help-command ~/projects/my-app
```

### `persuade rollback`

Restore from backup.

**Options:**
- `--list`: List available backups
- `--timestamp TIMESTAMP`: Restore specific backup
- `--latest`: Restore most recent backup

**Examples:**
```bash
# List backups
persuade rollback --list ~/projects/my-app

# Restore latest backup
persuade rollback --latest ~/projects/my-app

# Restore specific backup
persuade rollback --timestamp 20231215_143022 ~/projects/my-app
```

### `persuade iterate-pr`

Iterate on PR feedback with deterministic two-phase execution.

**Options:**
- `--auto-approve, -y`: Skip approval prompt (for CI/CD)
- `--project-dir PATH`: Project directory (defaults to git repository root)
- `--allow-non-git`: Allow running in non-git directories (not recommended)
- `--no-resolve-root`: Don't auto-resolve to git repository root

**Examples:**
```bash
# Interactive mode (shows plan, prompts for approval)
persuade iterate-pr 67

# Auto-approve mode for CI/CD
persuade iterate-pr 67 --auto-approve

# Run from subdirectory without resolving to git root
persuade iterate-pr 67 --no-resolve-root
```

**Two-Phase Execution:**
1. **Plan Phase**: Read-only analysis and classification of PR feedback
2. **Execute Phase**: Apply changes only after user approval

This ensures deterministic behavior - you always see what will happen before any changes are made.

**Requires:** `pip install persuade[agents]`

### `persuade serve`

Start the agent HTTP server for programmatic access.

**Options:**
- `--host HOST`: Host to bind to (default: 127.0.0.1)
- `--port PORT`: Port to bind to (default: 8765)
- `--reload`: Enable auto-reload for development

**Examples:**
```bash
# Start server
persuade serve --port 8765

# Call from external tool
curl -X POST http://localhost:8765/agent/run \
  -H "Content-Type: application/json" \
  -d '{"agent_type": "iterate-pr", "params": {"pr_number": 67}}'
```

**Endpoints:**
- `POST /agent/run` - Run an agent (plan or execute)
- `POST /agent/{id}/execute` - Execute a pending plan
- `GET /agent/{id}` - Get pending plan details
- `DELETE /agent/{id}` - Cancel a pending plan
- `GET /health` - Health check

**Requires:** `pip install persuade[server]`

## File Categories

Persuade categorizes files into four types:

1. **SYNC_ALWAYS**: Commands, hooks, scripts - always overwritten
2. **MERGE_SMART**: `settings.json` - intelligently merged
3. **SKIP_ALWAYS**: `settings.local.json`, state/, logs/ - never synced
4. **COPY_IF_MISSING**: README - copied only if missing

## Directory Structure

After syncing, your project will have:

```
your-project/
├── .claude/
│   ├── commands/       # Custom Claude commands
│   ├── hooks/          # Claude event hooks
│   ├── git-hooks/      # Git hooks (installed to .git/hooks/)
│   ├── scripts/        # Automation scripts
│   ├── prompts/        # Reusable prompts
│   ├── docs/           # AI-optimized engineering standards
│   ├── knowledge/      # Knowledge base
│   ├── settings.json   # Claude settings (merged)
│   ├── state/          # Runtime state (local only)
│   ├── logs/           # Debug logs (local only)
│   └── .backup/        # Sync backups (local only)
├── .git/
│   └── hooks/          # Git hooks (synced from .claude/git-hooks/)
└── .github/
    └── workflows/      # CI/CD workflows (if present in template)
```

## Advanced Usage

### Custom Exclude Patterns

```bash
# Exclude multiple patterns
persuade sync \
  --exclude "workflows/*.yml" \
  --exclude "hooks/pre-push" \
  ~/projects/my-app
```

### Verbose Output

```bash
# See detailed sync information
persuade -v sync ~/projects/my-app
```

### Quiet Mode

```bash
# Minimal output (useful for scripts)
persuade -q sync ~/projects/my-app
```

## Troubleshooting

### "Permission denied" errors

Ensure scripts are executable after sync:
```bash
chmod +x .claude/scripts/*.sh
chmod +x .claude/hooks/*.sh
```

### Merge conflicts in settings.json

Persuade intelligently merges settings, but you can:
1. Check backup: `persuade rollback --list ~/projects/my-app`
2. Restore if needed: `persuade rollback --latest ~/projects/my-app`
3. Manually edit `.claude/settings.json`

### Symlinks not working (Windows)

Windows requires Developer Mode or Administrator privileges for symlinks:
1. Enable Developer Mode in Windows Settings
2. Or run terminal as Administrator

### Files not syncing

Check if files are:
1. Gitignored: `git check-ignore <file>`
2. Excluded by pattern: `persuade sync --dry-run -v ~/projects/my-app`
3. In skip patterns: See package documentation for SKIP_PATTERNS

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/unit/persuade/ -v

# With coverage
pytest tests/unit/persuade/ --cov=persuade --cov-report=term-missing
```

### Code Quality

```bash
# Lint and format
ruff check --fix persuade/
ruff format persuade/

# Type check
mypy persuade/
```

## Requirements

- Python ≥ 3.11
- click ≥ 8.1.0 (CLI framework)
- rich ≥ 13.0.0 (terminal formatting)

### Optional Dependencies

```bash
# For iterate-pr CLI command (two-phase PR iteration)
pip install persuade[agents]

# For HTTP server (programmatic agent access)
pip install persuade[server]

# For development
pip install persuade[dev]
```

## License

MIT License

Copyright (c) 2025 stavxyz

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
