Your First Episode

This tutorial walks you through generating a podcast episode from a real codebase, end to end. By the end, you'll have an MP3 file you can listen to.

Prerequisites

• Node.js 22+
• A git repository with some commit history
• An ElevenLabs API key (for voice synthesis)

For script generation, code2cast uses a hosted Claude proxy by default — no API key needed to get started. You can also use your own Anthropic or OpenAI key (see step 4).

1. Install the CLI

npm install -g code2cast

Verify it's working:

code2cast --version

2. Initialise your project

Navigate to the repository you want to turn into a podcast and run:

cd ~/my-project
code2cast init

The interactive wizard asks for a project name, description, theme, and target duration. For your first episode, the defaults are fine — just press enter through each step.

This creates .code2cast/config.json in your project root:

{
  "name": "my-project",
  "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
  "exclude": ["node_modules", "dist", ".git"],
  "theme": "casual",
  "durationMinutes": 5
}

Non-interactive alternative

code2cast init --yes --name "My Project" --theme casual --duration 3m

Duration accepts human-friendly formats: 30s, 2m 30s, 5, etc.

3. Check your status

Before generating, verify everything looks right:

code2cast status

This shows your project config and authentication state. You don't need to be authenticated with the platform to generate episodes locally.

4. Configure script generation

The generate command needs an AI provider to write the podcast script. By default, code2cast uses a hosted Claude proxy — no setup required.

Default: Claude proxy (no API key needed)

Just run code2cast generate — it works out of the box.

Option B: Anthropic API key

If you prefer to use your own Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-api03-...
code2cast generate --provider claude

Option C: OpenAI Codex

export OPENAI_API_KEY=sk-...
code2cast generate --provider codex

Option D: Self-hosted Claude proxy

If you run your own remote-claude instance:

code2cast generate --provider claude-proxy --base-url http://localhost:4009

Per-command API key

Any provider that needs a key accepts --api-key inline:

code2cast generate --provider claude --api-key sk-ant-api03-...
code2cast voice --api-key xi-...

5. Generate a script

Now the fun part. This command analyzes your codebase and recent git history, then generates a podcast script:

code2cast generate

You'll see progress as it works through three steps:

1. Analyzing codebase — reads your source files (up to 200 files, respecting include/exclude patterns)
2. Analyzing git history — scans the last 30 days of commits and PRs
3. Generating script — streams the script from the AI provider

The output is saved to .code2cast/output/episode-1/script.json.

Customising generation

Analyse a different time range:

code2cast generate --days 7
code2cast generate --from 2025-01-01 --to 2025-02-01

Preview what would be analysed without generating:

code2cast generate --dry-run

6. Synthesize audio

Convert the script into spoken audio using ElevenLabs:

export ELEVENLABS_API_KEY=xi-...
code2cast voice

This reads the script from step 5, sends each dialogue segment to ElevenLabs for text-to-speech, and concatenates the results into a single MP3 file.

Output: .code2cast/output/episode-1/audio.mp3

Specifying an episode

If you've generated multiple episodes:

code2cast voice --episode 2

7. Listen to it

Play the generated episode locally:

code2cast preview

This uses your system's audio player (afplay on macOS, paplay on Linux). Press Ctrl+C to stop playback.

What's in the output directory

After completing these steps, your .code2cast/ directory looks like this:

.code2cast/
  config.json              # Project config (from step 2)
  output/
    episode-1/
      script.json          # Generated dialogue
      metadata.json        # Generation stats (provider, timestamps, file/commit counts)
      audio.mp3            # Synthesized audio (from step 6)

Next steps

Authenticate with the platform

To publish episodes to CodeCast, authenticate with the browser flow:

code2cast auth login

This opens your browser, you pick an org, and the CLI receives an API key automatically. For CI/CD, use --api-key instead:

code2cast auth login --api-key c2c_xxx

Plan a series

Instead of one-off episodes, plan a multi-episode series covering your project's architecture:

code2cast plan --episodes 5 --strategy architecture

This creates .code2cast/plan.json with episode outlines you can then generate one at a time.

Publish to the platform

code2cast publish --episode 1 --podcast my-podcast

See the CLI Reference for the full publish workflow.

Automate with CI

Every command supports --json for machine-readable output and --yes for non-interactive mode:

code2cast generate --json --yes | jq '.title'

See For AI Agents in the CLI reference.