# Pocketcast

> This skill should be used when the user asks to "list starred episodes", "check my podcasts", "what am I listening to", "podcast history", "show notes", "podcast info", "search podcasts", "pocketcasts", "pocket casts", or mentions Pocket Casts integration. Provides read-only access to starred episodes, listening history, show notes, and podcast metadata.

- Skill: `the-focus-ai/pocketcast` (Agent Skill)
- Install (CLI): `npx skillmds@latest add the-focus-ai/pocketcast`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-focus-ai/pocketcast/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: The-Focus-AI (https://skillmd.com/u/the-focus-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-focus-ai/pocketcast

---


# 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:

```bash
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:

```json
{
  "email": "you@example.com",
  "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

Returns detailed episode metadata including download URL.

### Search

```bash
# 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:

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

Error responses:

```json
{
  "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