prompts-conductor/examples/tap-usage.md

⚡ Wire up your AI prompts - The ultimate CLI for AI workflow orchestration. Create, manage, and chain prompts across 400+ AI platforms with enterprise security, version control, and automation. Includes comprehensive CLI documentation.

# Tap Command Usage Examples

> Copyright (c) 2025 Friedrich Timm. All rights reserved.
> 
> This software is provided free of charge for personal and commercial use, but modification, redistribution, and forking are strictly prohibited. See [LICENSE](../LICENSE) for full details.

The `tap` command allows you to add hooks to existing commands for monitoring, logging, or custom behavior.

## Basic Usage

### Add a hook
```bash
# Add a before hook to template create command
pc tap add "template create" before "echo 'Creating template...'"

# Add an after hook to template run command
pc tap add "template run" after "echo 'Template executed successfully'"

# Add an error hook to conductor create command
pc tap add "conductor create" error "echo 'Error creating conductor'"
```

### List hooks
```bash
# List all configured hooks
pc tap list

# List hooks in JSON format
pc tap list --json
```

### Remove a hook
```bash
# Remove a hook by ID
pc tap remove hook_1234567890_abc123
```

### Enable/Disable hooks
```bash
# Enable all hooks
pc tap enable

# Disable all hooks
pc tap disable

# Toggle a specific hook
pc tap toggle hook_1234567890_abc123
```

### Test a hook
```bash
# Test a hook without executing the actual command
pc tap test hook_1234567890_abc123
```

## Hook Types

- **before**: Executed before the command runs
- **after**: Executed after the command completes successfully
- **error**: Executed when the command fails

## Script Types

### Shell Commands
```bash
# Simple echo
pc tap add "template create" before "echo 'Starting template creation'"

# Complex shell command
pc tap add "template run" after "echo 'Template completed at $(date)' >> /tmp/pc-logs.txt"

# Using environment variables
pc tap add "conductor create" before "echo 'Creating conductor: $CONDUCTOR_NAME'"
```

### JavaScript Code
```bash
# Simple logging
pc tap add "template list" after "console.log('Templates listed successfully')"

# Accessing context
pc tap add "template create" before "console.log('Creating template:', context.args[0])"

# Using chalk for colored output
pc tap add "template run" after "console.log(chalk.green('Template executed successfully'))"
```

## Wildcard Commands

You can use `*` to hook into all commands:

```bash
# Hook into all commands before execution
pc tap add "*" before "echo 'Executing command...'"

# Hook into all commands after execution
pc tap add "*" after "echo 'Command completed'"
```

## Advanced Examples

### Performance Monitoring
```bash
# Track execution time
pc tap add "template run" before "console.log('Start time:', Date.now())"
pc tap add "template run" after "console.log('End time:', Date.now())"
```

### Logging to File
```bash
# Log all template operations
pc tap add "template create" after "echo '$(date): Template created' >> ~/prompts-conductor-data/activity.log"
pc tap add "template run" after "echo '$(date): Template run' >> ~/prompts-conductor-data/activity.log"
```

### Validation
```bash
# Validate template name before creation
pc tap add "template create" before "if (context.args[0].length < 3) { console.log('Template name too short'); process.exit(1); }"
```

### Integration with External Tools
```bash
# Send notification on completion
pc tap add "template run" after "curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL -d '{\"text\":\"Template executed successfully\"}'"

# Update external system
pc tap add "conductor create" after "echo 'Conductor created' | nc localhost 8080"
```

## Configuration

Hooks are stored in `~/prompts-conductor-data/config/tap-config.json`:

```json
{
  "hooks": [
    {
      "id": "hook_1234567890_abc123",
      "command": "template create",
      "type": "before",
      "script": "echo 'Creating template...'",
      "enabled": true,
      "created": "2025-07-26T10:00:00.000Z",
      "description": "Log template creation start"
    }
  ],
  "enabled": true
}
```

## Best Practices

1. **Use descriptive hook IDs**: The system generates IDs automatically, but you can add descriptions
2. **Keep scripts simple**: Avoid complex logic that might fail and break the main command
3. **Use appropriate hook types**: Use `before` for validation, `after` for logging, `error` for error handling
4. **Test your hooks**: Use `pc tap test` to verify hooks work correctly
5. **Monitor performance**: Don't add hooks that significantly slow down command execution
6. **Handle errors gracefully**: Hooks should not throw errors that break the main command

## Integration with Existing Commands

The tap system is designed to be non-intrusive. Hooks are executed in the background and failures in hooks don't affect the main command execution. This makes it safe to add monitoring and logging hooks to production systems.