Pocket Casts Integration

This skill provides read-only access to Pocket Casts data through their API. View starred episodes, listening history, show notes, and podcast metadata.

Script Location

The CLI script is located at:

${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts

Run commands using:

npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts <command> [options]

First-Time Setup

Using 1Password (Recommended)

No setup required if you have a "pocketcasts.com" item in 1Password with username/email and password fields.

Using a Credentials File

Create .claude/pocketcast-skill.local.json in your project directory:

{
  "email": "[email protected]",
  "password": "your-pocket-casts-password"
}

Or create a global credentials file at ~/.config/pocketcast-skill/credentials.json with the same format.

Project-local credentials are automatically added to .gitignore.

Available Commands

Starred Episodes

# List all starred episodes
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts starred

Response fields:

• count: Total number of starred episodes
• episodes: Array of episode objects

Recent Listening History

# Get recent episodes (default: 50)
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts recent

# Get last 10 episodes
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts recent --limit=10

Response fields:

• count: Number of episodes returned
• limit: Requested limit
• episodes: Array of episode objects

Show Notes

# Get show notes for a specific episode
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts shownotes <episode-uuid>

Response fields:

• episodeId: The episode UUID
• showNotes: HTML content of the show notes

Podcast Info

# Get podcast metadata
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts podcast <podcast-uuid>

Returns full podcast metadata including title, author, description, and episode list.

Episode Metadata

# Get detailed episode metadata
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts episode <episode-uuid>

Returns detailed episode metadata including download URL.

Search

# Search starred and recent episodes by title or podcast name
npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/pocketcast.ts search "search terms"

Searches across both starred and recent episodes. Matches against episode title and podcast name.

Response fields:

• query: The search query
• count: Number of matching episodes
• episodes: Array of matching episode objects

Episode Object Fields

All episode lists return objects with these fields:

• id: Episode UUID (use with shownotes, episode commands)
• title: Episode title
• podcastTitle: Name of the podcast
• podcastUuid: Podcast UUID (use with podcast command)
• publishedAt: ISO 8601 publish date
• duration: Human-readable duration (e.g., "1h 23m")
• durationSeconds: Duration in seconds
• starred: Whether the episode is starred
• played: Whether the episode has been fully played
• playedUpTo: How far the user has listened (if partially played)

Response Format

All commands output JSON with a consistent structure:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error responses:

{
  "success": false,
  "error": "Error message here"
}

Common Workflows

See What's Starred

1. Run: starred
2. Present the list of starred episodes to the user

Check Recent Listening

1. Run: recent --limit=10
2. Summarize what the user has been listening to recently

Get Episode Details

1. Start with starred or recent to find episodes
2. Use shownotes <uuid> to get full show notes
3. Use episode <uuid> for detailed metadata

Find a Specific Episode

1. Run: search "topic or podcast name"
2. Present matching episodes

Explore a Podcast

1. Get podcast UUID from any episode listing
2. Run: podcast <podcast-uuid>
3. Present podcast details and episode list

Credential Lookup Order

1. Project-local: .claude/pocketcast-skill.local.json
2. Global: ~/.config/pocketcast-skill/credentials.json
3. 1Password: Item named "pocketcasts.com"

Troubleshooting

"Login failed" error

• Verify your Pocket Casts email and password are correct
• Check that your credentials file has the right format

"No credentials found" error

• Create a credentials file (see First-Time Setup) or ensure 1Password CLI is installed and authenticated

Empty results

• Ensure you have starred episodes or recent listening history in Pocket Casts