persuade 0.1.0

Persuade - Generic AI Development Tool Configurator. Sync automation to your AI-assisted development projects.

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

pip install persuade

Quick Start

Basic Sync

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

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

Editable Mode (Template Development)

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

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

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

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:

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

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

# 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

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

Verbose Output

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

Quiet Mode

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

Troubleshooting

"Permission denied" errors

Ensure scripts are executable after sync:

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

# 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

# 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

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