impulse-claude/README.md

Download and install Claude commands from Impulse Directory

# Impulse Claude Command Installer

An NPX command that allows you to download and install Claude commands from Impulse Directory.

## 🚀 Installation and Usage

### Direct usage with npx

```bash
npx impulse-claude <user-slug>/<command-slug>
npx impulse-claude <user-slug> <command-slug>
```

### Examples

```bash
# Download a command from impulse.directory
npx impulse-claude john/my-awesome-command

# Use a custom URL (local development)
IMPULSE_BASE_URL=localhost:3000 npx impulse-claude dev-user/dev-command

# Use another server
IMPULSE_BASE_URL=my-custom-domain.com npx impulse-claude author/custom-command
```

## 📁 Command Placement Logic

The command searches for the `.claude` folder in the following order:

1. **Current folder**: Looks for `.claude/commands/` in the current working directory
2. **Parent folders**: Goes up the tree to find a `.claude` folder
3. **Fallback home**: Uses `~/.claude/commands/` if no project folder is found

This allows:
- Installing commands at the project level (shared with the team)
- Installing personal commands (user only)

## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|--------|
| `IMPULSE_BASE_URL` | Base URL to download commands | `impulse.directory` |

### Automatic HTTPS/HTTP Handling

- **HTTPS by default**: All URLs use HTTPS
- **Fallback HTTP**: If HTTPS fails, the command automatically tries HTTP
- **Localhost auto-HTTP**: URLs containing `localhost` or `127.0.0.1` use HTTP directly

## 📝 Command Format

Downloaded commands are in Markdown format and are saved as `<command-slug>.md`.

Example download URL:
```
https://impulse.directory/raw/user-slug/command-slug
```

## 🛠️ Development

### Local Test

```bash
# From the npx/impulse-claude/ folder
node index.js --help
node index.js test-user test-command
node index.js test-user/test-command
```

### File Structure

```
npx/impulse-claude/
├── package.json    # NPM configuration
├── index.js        # Main script
└── README.md       # Documentation
```

## 📚 Using Downloaded Commands

Once installed, commands are available in Claude Code:

```bash
# In Claude Code
/my-awesome-command [arguments]
```

Project commands show "(project)" in the help, user commands show "(user)".

## 🔍 Troubleshooting

### Common Errors

1. **Command not found (404)**: Check the command slug
2. **Network error**: Check your connection and the base URL
3. **Permissions**: Make sure you have write permissions in the destination folder

### Debug

To see download details:
```bash
# The command automatically displays the download path and destination folder
npx impulse-claude debug-user debug-command
```