npm package: @impulselab/directory
Description: Download and install Claude commands from Impulse Directory
Author: Impulse Lab
Latest version: 1.1.0

# Impulse Directory Command Installer

An NPX command by [Impulse Lab](https://impulselab.ai) that downloads prompts from Impulse Directory and installs them for Claude Desktop or Cursor.

## 🚀 Installation and Usage

### Direct usage with npx

```bash
npx @impulselab/directory <user-slug>/<command-slug> [--target <target>]
npx @impulselab/directory stack <stack-id> [--target <target>]
```

`--target` selects the installation target. When omitted the command defaults to `claude-slash`.

When using the `stack` command, all prompts in the stack are installed for the chosen tool. Stacks must be constrained to a specific tool to be installed via NPX.

### Targets

| Target | Description | Destination |
|--------|-------------|-------------|
| `claude-slash` | Claude slash command | `.claude/commands` (falls back to `~/.claude/commands`)
| `claude-sub-agent` | Claude sub agent | `.claude/agents` (falls back to `~/.claude/agents`)
| `cursor-command` | Cursor command | `.cursor/commands` (project only)
| `cursor-rule` | Cursor rule | `.cursor/rules` (project only)

> **Note**: Cursor targets require running the installer inside a Cursor project (a folder containing `.cursor/`). The command fails if no project folder is found.

### Examples

```bash
# Download a Claude slash command from impulse.directory
npx @impulselab/directory john/my-awesome-command

# Install as a Claude sub agent
npx @impulselab/directory john/my-awesome-command --target claude-sub-agent

# Install as a Cursor command (inside a Cursor project)
npx @impulselab/directory john/my-awesome-command --target cursor-command

# Install as a Cursor rule (inside a Cursor project)
npx @impulselab/directory john/my-awesome-command --target cursor-rule

# Install an Impulse stack (tool-specific stack ID)
npx @impulselab/directory stack 01JH0000000ABCDEF --target claude-slash

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

# Use another server
IMPULSE_BASE_URL=my-custom-domain.com npx @impulselab/directory author/custom-command
```

## 📁 Command Placement Logic

### Claude targets (`claude-slash`, `claude-sub-agent`)

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

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

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

### Cursor targets (`cursor-command`, `cursor-rule`)

- Must be executed inside a Cursor project (a directory containing `.cursor/`)
- Always installs into the project `.cursor` folder
- Fails with an explicit message if no Cursor project is detected

## 🔧 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 prompts are saved as `<command-slug>.md`. Stack installs will save each command in the stack using the prompt slug (with a stack-prefixed fallback when needed).

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

Stack installation payloads are fetched from:

```
https://impulse.directory/api/stacks/<stack-id>/npx
```

## 🛠️ Development

### Local Test

```bash
# From the npx/impulse-claude/ folder
node index.js --help
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 Prompts

- **Claude slash commands**: use `/command-name` inside Claude Desktop.
- **Claude sub agents**: open Claude Desktop and select the agent from the agents list.
- **Cursor commands**: trigger Cursor's command palette and run the command by name.
- **Cursor rules**: Cursor loads rules automatically from `.cursor/rules` for the project.

## 🔍 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
4. **Cursor project missing**: Ensure you're running the command inside a folder containing `.cursor/`

### Debug

To see download details:
```bash
# The command automatically displays the download path and destination folder
npx @impulselab/directory debug-user/debug-command
```

## 🏷️ Branding

Made by Impulse Lab — `https://impulselab.ai`