Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

feat: add Codex CLI fallback, update README for deep PodStack integration

Nika Siradze6173a25da620
diff --git a/README.md b/README.md
index 4e1706c..70ad51a 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ Publish with optimization checklist ← PodStac
Review performance ← PodStack
```
-The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/podstack), a set of Claude Code slash commands that ship with podcli.
+The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/podstack), a set of Claude Code slash commands that ship with podcli. Both halves are deeply integrated: the clip suggestion engine reads from your PodStack knowledge base, uses your title formulas and voice rules, checks the episode database for duplicates, and outputs MCP-aligned fields that flow through to export.
---
@@ -80,7 +80,7 @@ Run `/publish-checklist` when uploading. A week later, run `/retro-episode` with
| | Video Engine (podcli core) | Content Workflow (PodStack) |
|---|---|---|
| **What** | Transcription, clip detection, rendering | Titles, descriptions, thumbnails, publishing |
-| **How** | Python + FFmpeg + Whisper + OpenCV + Claude | Claude Code slash commands |
+| **How** | Python + FFmpeg + Whisper + OpenCV + Claude/Codex | Claude Code slash commands |
| **Interface** | Web UI, CLI, MCP tools | `/slash-commands` in Claude Code |
| **Output** | `.mp4` files ready to upload | Content packages ready to paste into YouTube |
@@ -91,7 +91,7 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh
## Features
### Video Processing
-- **AI clip suggestion** — Claude-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring
+- **AI clip suggestion** — Claude/Codex-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring
- **Face tracking** — YuNet face detection, exponential-smoothing camera, split-screen support, speaker-aware tracking with snap cooldown
- **Burned-in captions** — 4 styles: branded, hormozi, karaoke, subtle
- **Hardware-accelerated encoding** — VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, CPU fallback
@@ -129,6 +129,7 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh
| **Python** >= 3.10 | [python.org](https://python.org) |
| **FFmpeg** | `brew install ffmpeg` / `sudo apt install ffmpeg` |
| **Claude Code** (optional) | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) — needed for PodStack slash commands |
+| **Codex** (optional) | [openai.com/codex](https://openai.com/index/introducing-codex/) — alternative AI engine for clip suggestion (auto-detected if Claude is unavailable) |
## Quick Start
@@ -225,7 +226,7 @@ Or just paste a transcript — Claude auto-detects the input and runs the right
## Knowledge Base
-The knowledge base is what makes podcli understand *your* show. Drop `.md` files into `.podcli/knowledge/` and both the video engine and content workflow use them.
+The knowledge base is what makes podcli understand *your* show. Drop `.md` files into `.podcli/knowledge/` and both the video engine and content workflow use them. The clip suggestion engine reads 8 of these files (prioritized by relevance), checks the episode database for duplicate avoidance, and applies your voice rules and title formulas when generating suggestions.
PodStack ships with **13 starter templates** that you fill in with your show's details:
diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.py
index 3a13516..a66dcac 100644
--- a/backend/services/claude_suggest.py
+++ b/backend/services/claude_suggest.py
@@ -1,10 +1,10 @@
"""
-Clip suggestion via Claude Code.
+Clip suggestion via AI CLI (Claude Code or Codex).
-Delegates moment selection to Claude, which uses the PodStack knowledge base
+Delegates moment selection to an AI CLI, which uses the PodStack knowledge base
(.podcli/knowledge/) and CLAUDE.md for context-aware clip extraction.
-Falls back to heuristic scoring if Claude is unavailable.
+Priority: Claude Code → Codex → heuristic fallback.
"""
import json
@@ -15,28 +15,47 @@ import tempfile
from typing import Optional, Callable
-def _find_claude() -> Optional[str]:
- """Find the claude CLI binary."""
- # Check common locations
- for path in [
- os.path.expanduser("~/.local/bin/claude"),
- "/usr/local/bin/claude",
- "/opt/homebrew/bin/claude",
- ]:
+def _find_cli(name: str, extra_paths: list[str] = None) -> Optional[str]:
+ """Find a CLI binary by name. Checks extra_paths first, then PATH."""
+ for path in (extra_paths or []):
if os.path.exists(path):
return path
-
- # Check PATH
try:
- result = subprocess.run(["which", "claude"], capture_output=True, text=True, timeout=5)
+ result = subprocess.run(["which", name], capture_output=True, text=True, timeout=5)
if result.returncode == 0 and result.stdout.strip():
return result.stdout.strip()
except Exception:
pass
-
return None
+def _find_ai_cli() -> tuple[Optional[str], str]:
+ """
+ Find the best available AI CLI.
+
+ Returns (path, engine) where engine is "claude" or "codex".
+ Returns (None, "") if neither is available.
+ """
+ # Prefer Claude Code
+ claude = _find_cli("claude", [
+ os.path.expanduser("~/.local/bin/claude"),
+ "/usr/local/bin/claude",
+ "/opt/homebrew/bin/claude",
+ ])
+ if claude:
+ return claude, "claude"
+
+ # Fall back to Codex
+ codex = _find_cli("codex", [
+ "/usr/local/bin/codex",
+ "/opt/homebrew/bin/codex",
+ ])
+ if codex:
+ return codex, "codex"
+
+ return None, ""
+
+
def _load_existing_shorts(episodes_path: str) -> list[str]:
"""Extract existing short titles from episode database to avoid duplicates."""
if not os.path.exists(episodes_path):
@@ -195,16 +214,18 @@ def suggest_with_claude(
progress_callback: Optional[Callable[[int, str], None]] = None,
) -> Optional[list[dict]]:
"""
- Use Claude Code to extract the best clip moments from transcript segments.
+ Use an AI CLI (Claude Code or Codex) to extract the best clip moments.
- Returns list of clip dicts or None if Claude is unavailable.
+ Tries Claude Code first, falls back to Codex. Returns None if neither
+ is available.
"""
- claude_path = _find_claude()
- if not claude_path:
+ cli_path, engine = _find_ai_cli()
+ if not cli_path:
return None
if progress_callback:
- progress_callback(0, "Preparing transcript for Claude...")
+ label = "Claude" if engine == "claude" else "Codex"
+ progress_callback(0, f"Preparing transcript for {label}...")
# Build transcript text from segments
lines = []
@@ -234,27 +255,57 @@ def suggest_with_claude(
prompt_file = f.name
if progress_callback:
- progress_callback(20, "Asking Claude to analyze transcript...")
+ label = "Claude" if engine == "claude" else "Codex"
+ progress_callback(20, f"Asking {label} to analyze transcript...")
try:
- # Pipe prompt via stdin — avoids shell escaping and arg size limits
- # Run from the podcli project dir so it picks up CLAUDE.md + knowledge base
- result = subprocess.run(
- f'cat "{prompt_file}" | "{claude_path}" --print -p -',
- capture_output=True,
- text=True,
- cwd=project_dir,
- timeout=300, # 5 min max
- shell=True,
- )
+ # Run the AI CLI to analyze the transcript
+ if engine == "codex":
+ # Codex: use `codex exec` with --output-last-message to capture response
+ output_file = prompt_file + ".out"
+ result = subprocess.run(
+ [
+ cli_path, "exec",
+ "--full-auto",
+ "-o", output_file,
+ prompt,
+ ],
+ capture_output=True,
+ text=True,
+ cwd=project_dir,
+ timeout=300,
+ )
+ # Read response from output file
+ if os.path.exists(output_file):
+ with open(output_file) as f:
+ result = subprocess.CompletedProcess(
+ args=result.args,
+ returncode=result.returncode,
+ stdout=f.read(),
+ stderr=result.stderr,
+ )
+ try:
+ os.unlink(output_file)
+ except Exception:
+ pass
+ else:
+ # Claude: pipe prompt via stdin with --print mode
+ result = subprocess.run(
+ f'cat "{prompt_file}" | "{cli_path}" --print -p -',
+ capture_output=True,
+ text=True,
+ cwd=project_dir,
+ timeout=300,
+ shell=True,
+ )
if result.returncode != 0:
if progress_callback:
- progress_callback(0, f"Claude returned error: {result.stderr[:200]}")
+ progress_callback(0, f"{label} returned error: {result.stderr[:200]}")
return None
if progress_callback:
- progress_callback(80, "Parsing Claude's suggestions...")
+ progress_callback(80, f"Parsing {label}'s suggestions...")
# Parse JSON from Claude's response
response = result.stdout.strip()
@@ -348,21 +399,21 @@ def suggest_with_claude(
normalized.sort(key=lambda x: x["start_second"])
if progress_callback:
- progress_callback(100, f"Claude suggested {len(normalized)} clips")
+ progress_callback(100, f"{label} suggested {len(normalized)} clips")
return normalized
except json.JSONDecodeError as e:
if progress_callback:
- progress_callback(0, f"Could not parse Claude's response as JSON: {e}")
+ progress_callback(0, f"Could not parse {label}'s response as JSON: {e}")
return None
except subprocess.TimeoutExpired:
if progress_callback:
- progress_callback(0, "Claude timed out (5 min limit)")
+ progress_callback(0, f"{label} timed out (5 min limit)")
return None
except Exception as e:
if progress_callback:
- progress_callback(0, f"Claude error: {e}")
+ progress_callback(0, f"{label} error: {e}")
return None
finally:
# Clean up temp file
diff --git a/src/ui/web-server.ts b/src/ui/web-server.ts
index 5b9219b..39bb136 100644
--- a/src/ui/web-server.ts
+++ b/src/ui/web-server.ts
@@ -1203,24 +1203,31 @@ app.post("/api/generate-prompt", (req, res) => {
res.json({ prompt, action, context: ctx });
});
-// --- Claude-powered clip suggestion (same as CLI) ---
+// --- AI-powered clip suggestion (Claude Code or Codex) ---
app.post("/api/claude-suggest", async (req, res) => {
const { top_n = 5 } = req.body;
- // Find claude binary
+ // Find AI CLI: prefer Claude, fall back to Codex
const homedir = require("os").homedir();
const claudeCandidates = [
join(homedir, ".local", "bin", "claude"),
"/usr/local/bin/claude",
"/opt/homebrew/bin/claude",
];
+ const codexCandidates = [
+ "/usr/local/bin/codex",
+ "/opt/homebrew/bin/codex",
+ ];
const claudePath = claudeCandidates.find((p) => existsSync(p));
+ const codexPath = !claudePath ? codexCandidates.find((p) => existsSync(p)) : undefined;
+ const aiPath = claudePath || codexPath;
+ const engine: "claude" | "codex" = claudePath ? "claude" : "codex";
- if (!claudePath) {
+ if (!aiPath) {
res.json({
- error: "Claude Code not found",
- message: "Install Claude Code: https://docs.anthropic.com/en/docs/claude-code",
+ error: "No AI CLI found (Claude Code or Codex)",
+ message: "Install Claude Code (https://docs.anthropic.com/en/docs/claude-code) or Codex (https://openai.com/index/introducing-codex/)",
fallback: "clipboard",
clips: [],
});
@@ -1340,21 +1347,28 @@ ${transcriptText}`;
try {
const { execSync } = require("child_process");
- const result = execSync(
- `cat "${tmpFile}" | "${claudePath}" --print -p -`,
- {
- cwd: process.cwd(),
- timeout: 300_000,
- maxBuffer: 10 * 1024 * 1024,
- encoding: "utf-8",
- }
- );
+ let result: string;
+
+ if (engine === "codex") {
+ const outFile = tmpFile + ".out";
+ execSync(
+ `"${aiPath}" exec --full-auto -o "${outFile}" "$(cat "${tmpFile}")"`,
+ { cwd: process.cwd(), timeout: 300_000, maxBuffer: 10 * 1024 * 1024, encoding: "utf-8" }
+ );
+ result = existsSync(outFile) ? readFileSync(outFile, "utf-8") : "";
+ try { require("fs").unlinkSync(outFile); } catch {}
+ } else {
+ result = execSync(
+ `cat "${tmpFile}" | "${aiPath}" --print -p -`,
+ { cwd: process.cwd(), timeout: 300_000, maxBuffer: 10 * 1024 * 1024, encoding: "utf-8" }
+ );
+ }
// Parse JSON from response
const jsonStart = result.indexOf("{");
const jsonEnd = result.lastIndexOf("}") + 1;
if (jsonStart < 0 || jsonEnd <= jsonStart) {
- res.status(500).json({ error: "Claude did not return valid JSON" });
+ res.status(500).json({ error: `${engine === "claude" ? "Claude" : "Codex"} did not return valid JSON` });
return;
}
@@ -1402,9 +1416,10 @@ ${transcriptText}`;
broadcastSSE("state-sync", uiState);
}
- res.json({ clips, source: "claude" });
+ res.json({ clips, source: engine });
} catch (err: any) {
- res.status(500).json({ error: `Claude failed: ${err.message?.substring(0, 200)}` });
+ const label = engine === "claude" ? "Claude" : "Codex";
+ res.status(500).json({ error: `${label} failed: ${err.message?.substring(0, 200)}` });
} finally {
try { require("fs").unlinkSync(tmpFile); } catch {}
}