# Using Remux CLI with Claude Code

Guide to using the remux command-line binary with Claude Code for system administration, debugging, and analysis.

## Installation

```bash
# Install remux as a system binary
pip install -e .

# Verify installation
remux --version
remux --help
```

## Quick Examples

### 1. **Understand the System Architecture**

```bash
# Show system information
remux status info | claude-code --task "explain what each component does"

# Show configuration
remux config show | claude-code --task "explain the remux configuration structure"

# List policies
remux policy list | claude-code --task "explain what each policy is for"
```

### 2. **Daemon Management with Claude Code**

```bash
# Check daemon status and ask Claude for analysis
remux daemon status | claude-code --task "is the daemon running? what should I do?"

# Check health and troubleshoot
remux status health | claude-code --task "diagnose this health check output"

# View logs and analyze issues
remux daemon logs --level ERROR | claude-code --task "analyze these error logs and suggest fixes"
```

### 3. **Policy Configuration with Claude Code**

```bash
# Ask Claude to validate a policy
remux policy validate policies.yaml | claude-code --task "is my policy configuration correct?"

# Ask Claude to explain a policy
remux policy show read_only | claude-code --task "explain what this policy allows and blocks"

# Ask Claude to create a custom policy
claude-code . --task "create a policy that allows database administration but blocks writes outside /var/lib/postgresql"

# Apply Claude's suggestion
remux policy create database_admin --template read_only
# (then manually edit the generated policy.yaml)
```

### 4. **Client Operations with Guidance**

```bash
# Ask Claude how to execute a command
remux policy list | claude-code --task "which policy should I use to safely read web server logs?"

# Execute with Claude's recommended policy
remux client run web.example.com cat /var/log/nginx/access.log --policy read_only

# Batch operations with Claude's guidance
claude-code . --task "create a commands file for health checking a web server"
remux client batch web.example.com --commands-file commands.txt
```

### 5. **Troubleshooting with Claude Code**

```bash
# Something broke - ask Claude
remux daemon status | claude-code --task "the daemon is not running, help me debug"

# Health check failed - analyze with Claude
remux status health | claude-code --task "what's wrong with this health check?"

# Policy error - understand with Claude
remux policy validate bad_policy.yaml | claude-code --task "explain this validation error and how to fix it"

# Audit logs - investigate with Claude
remux daemon logs --level DENY | claude-code --task "why are commands being denied? is the policy too restrictive?"
```

## Advanced Workflows

### Workflow 1: Setting Up Remux for a New Environment

```bash
# 1. Initialize configuration
remux config init

# 2. Ask Claude for best practices
remux config show | claude-code --task "
I'm setting up remux in production.
Based on this configuration, what security best practices should I follow?
"

# 3. Create policies with Claude's help
claude-code . --task "create a security policy for production web servers"

# 4. Create the policy
remux policy create production_web --template read_only

# 5. Validate with Claude
remux policy validate policies.yaml | claude-code --task "is this production-ready?"

# 6. Start daemon
remux daemon start --known-hosts ~/.ssh/known_hosts --audit-log-dir /var/log/remux

# 7. Verify everything works
remux daemon status && remux status health
```

### Workflow 2: Analyzing Security Events

```bash
# 1. View recent denials
remux daemon logs --level DENY

# 2. Ask Claude what happened
remux daemon logs --level DENY | claude-code --task "
analyze these denied commands. Are they:
- Legitimate user mistakes?
- Actual security threats?
- Policy too restrictive?
Suggest how to fix if needed.
"

# 3. Implement Claude's recommendations
# (adjust policy based on feedback)
```

### Workflow 3: Debugging Connection Issues

```bash
# 1. Check if daemon is running
remux daemon status

# 2. Run health check
remux status health | claude-code --task "diagnose this health check failure"

# 3. Check logs for errors
remux daemon logs --level ERROR | claude-code --task "analyze these error messages"

# 4. Based on Claude's analysis, either:
#    - Restart daemon: remux daemon stop && remux daemon start
#    - Fix configuration: remux config init
#    - Adjust policies: remux policy validate policies.yaml
```

## Claude Code Commands with Remux

### Command Pattern

```bash
remux [command] [options] | claude-code --task "your question"
```

### Common Questions to Ask Claude

#### About Configuration
```bash
remux config show | claude-code --task "is this configuration secure and correct?"
```

#### About Policies
```bash
remux policy list | claude-code --task "which policy should I use for [scenario]?"
remux policy show my_policy | claude-code --task "what does this policy allow and block?"
remux policy validate policies.yaml | claude-code --task "are these policies correct for production?"
```

#### About Daemon Health
```bash
remux daemon status | claude-code --task "why is the daemon not running? how do I fix it?"
remux status health | claude-code --task "diagnose this health check failure"
```

#### About Audit Logs
```bash
remux daemon logs --level DENY | claude-code --task "why are these commands denied?"
remux daemon logs --level ERROR | claude-code --task "what are these error messages telling me?"
```

#### About Operations
```bash
remux client run host.com "command" | claude-code --task "is this command safe to execute?"
```

## Integration with Automation

### Bash Scripts with Claude Code Integration

```bash
#!/bin/bash
# check_remux_health.sh

# Check daemon
if ! remux daemon status >/dev/null; then
    echo "Daemon not running!"
    remux daemon status | claude-code --task "why might this happen?"
    exit 1
fi

# Check health
if ! remux status health >/dev/null; then
    echo "Health check failed!"
    remux status health | claude-code --task "diagnose this health check failure"
    exit 1
fi

# Check for denials
denials=$(remux daemon logs --level DENY | wc -l)
if [ "$denials" -gt 10 ]; then
    echo "Many denied commands! Investigating..."
    remux daemon logs --level DENY | claude-code --task "are these denials expected?"
fi

echo "✓ Remux is healthy"
```

### Git Hooks with Claude Code

```bash
#!/bin/bash
# .git/hooks/pre-commit

# Verify policy configuration before commit
if [ -f "policies.yaml" ]; then
    if ! remux policy validate policies.yaml >/dev/null 2>&1; then
        echo "Policy validation failed!"
        remux policy validate policies.yaml | claude-code --task "fix this policy validation error"
        exit 1
    fi
fi

exit 0
```

## Benefits of Using with Claude Code

| Benefit | Example |
|---------|---------|
| **Expert Analysis** | Claude explains complex security policies |
| **Troubleshooting** | Get guided solutions for errors |
| **Best Practices** | Receive security recommendations |
| **Policy Design** | Create optimal policies for your use case |
| **Root Cause Analysis** | Understand why things are failing |
| **Automation Help** | Create scripts that integrate with remux |

## Claude Code Integration Examples

### Example 1: Policy Design

```bash
# Without Claude:
remux policy list  # Lists policies but no context

# With Claude:
remux policy list | claude-code --task "
I need to create a policy that:
- Allows reading log files
- Allows running monitoring tools
- Blocks everything else

Based on available policies, what template should I use?
"
# Claude provides guidance on best template and explains why
```

### Example 2: Error Diagnosis

```bash
# Without Claude:
remux daemon logs --level ERROR | head -10
# Shows errors but unclear why

# With Claude:
remux daemon logs --level ERROR | claude-code --task "
Explain what these error messages mean and suggest fixes.
Also, should I restart the daemon or change configuration?
"
# Claude explains errors and recommends specific actions
```

### Example 3: Production Deployment

```bash
# Without Claude:
remux config init
# Just creates default config, no guidance

# With Claude:
remux config init && remux config show | claude-code --task "
I'm deploying remux to production. Based on this configuration:
- What changes should I make?
- What security settings should I adjust?
- What monitoring should I set up?
- What are common pitfalls to avoid?
"
# Claude provides comprehensive deployment guidance
```

## Tips for Best Results

1. **Be Specific**: Ask Claude about your specific scenario
   ```bash
   remux policy list | claude-code --task "
   I'm running a [type] server with [requirements].
   Which policy is most appropriate?
   "
   ```

2. **Include Context**: Provide relevant output
   ```bash
   remux daemon logs | claude-code --task "
   Here are my audit logs. Are there security issues?
   "
   ```

3. **Ask for Recommendations**: Get guidance on improvements
   ```bash
   remux config show | claude-code --task "
   What improvements would you suggest for production?
   "
   ```

4. **Verify Solutions**: Have Claude review your fixes
   ```bash
   remux policy validate policies.yaml | claude-code --task "
   I made changes based on your suggestions. Are they correct?
   "
   ```

## Troubleshooting

### Claude Code not finding remux

```bash
# Ensure remux is installed and in PATH
which remux

# If not found, install it
pip install -e .

# Verify installation
remux --version
```

### Permission Errors

```bash
# Remux needs socket access
chmod 600 ~/.rpipe/daemon.sock

# Audit log directory
mkdir -p ~/.rpipe/logs
chmod 755 ~/.rpipe
```

### SSH Issues

```bash
# Verify SSH configuration
ls -la ~/.ssh/known_hosts

# Have Claude help diagnose
remux daemon status | claude-code --task "
I'm getting SSH errors.
How do I configure host key verification?
"
```

## Next Steps

1. **Install remux**: `pip install -e .`
2. **Initialize**: `remux config init`
3. **Start daemon**: `remux daemon start --audit-log-dir ~/.rpipe/logs`
4. **Ask Claude**: `remux policy list | claude-code --task "which policy should I use?"`
5. **Execute commands**: `remux client run host.example.com cat /var/log/syslog`
6. **Monitor**: `remux daemon logs --follow`

## Resources

- **CLI Reference**: See `CLI_REFERENCE.md` for complete command documentation
- **Getting Started**: See `GETTING_STARTED.md` for quick start
- **Claude Code Examples**: See `CLAUDE_CODE_EXAMPLES.md` for more usage patterns
- **Architecture**: See `IMPLEMENTATION_SUMMARY.md` for system design
