# kalebe-silva/claude-assistir architecture

> Architecture diagram of the GitHub repository kalebe-silva/claude-assistir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kalebe-silva/claude-assistir
- Repository: https://github.com/kalebe-silva/claude-assistir

## Overview

assistir is a local video-to-briefing tool exposed as a Claude Code plugin and command-line shortcut. Its main workflow accepts a URL or local file, obtains video and captions when available, extracts distinct frames, uses captions or local Whisper transcription for speech, then writes a Markdown timeline and metadata. The script excerpt shows the processing stages and their calls; the README documents plugin and shortcut entry points. Unsampled source limits certainty about some dispatch details, so those links are omitted.

Main entry points: [`plugin/skills/assistir/assistir.py`](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py) (Workflow runner), [`bin/assistir`](https://github.com/kalebe-silva/claude-assistir/blob/main/bin/assistir) (CLI shortcut), [`plugin/skills/assistir/SKILL.md`](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/SKILL.md) (Assistir skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_claude["Claude Code"]
  node_skill["Assistir skill<br/>[SKILL.md]"]
  node_shortcut["CLI shortcut"]
end

subgraph group_processing["Video processing"]
  node_runner["Workflow runner<br/>[assistir.py]"]
  node_video["Video source"]
  node_downloader["URL download<br/>[assistir.py]"]
  node_yt_dlp["yt-dlp"]
  node_ffmpeg["FFmpeg"]
  node_frames["Distinct frames<br/>[assistir.py]"]
end

subgraph group_speech["Speech and captions"]
  node_captions["Caption parsing<br/>[assistir.py]"]
  node_whisper["Local transcription<br/>[assistir.py]"]
  node_faster_whisper["faster-whisper"]
end

subgraph group_results["Generated results"]
  node_timeline["Timeline assembly<br/>[assistir.py]"]
  node_artifacts["Briefing files"]
  node_metadata["Video metadata<br/>[assistir.py]"]
end

node_user(("User"))

node_user -->|"requests analysis"| node_claude
node_claude -->|"invokes skill"| node_skill
node_user -->|"runs command"| node_shortcut
node_shortcut -->|"launches"| node_runner
node_user -->|"provides input"| node_runner
node_runner -.->|"downloads URL"| node_downloader
node_downloader -->|"uses"| node_yt_dlp
node_runner -->|"uses local or fetched video"| node_video
node_runner -->|"extracts"| node_frames
node_frames -->|"decodes frames"| node_ffmpeg
node_runner -->|"parses available captions"| node_captions
node_runner -->|"transcribes without captions"| node_whisper
node_whisper -->|"extracts audio"| node_ffmpeg
node_whisper -->|"transcribes locally"| node_faster_whisper
node_runner -->|"assembles results"| node_timeline
node_timeline -->|"writes roteiro.md"| node_artifacts
node_runner -->|"writes metadata"| node_metadata
node_metadata -->|"saves meta.json"| node_artifacts

click node_skill "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/SKILL.md"
click node_shortcut "https://github.com/kalebe-silva/claude-assistir/blob/main/bin/assistir"
click node_runner "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_downloader "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_frames "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_captions "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_whisper "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_timeline "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"
click node_metadata "https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude,node_skill,node_shortcut,node_user toneBlue
class node_runner,node_video,node_downloader,node_yt_dlp,node_ffmpeg,node_frames toneAmber
class node_captions,node_whisper,node_faster_whisper toneMint
class node_timeline,node_artifacts,node_metadata toneRose
```

## Components

### User entry points

- **Claude Code**
- [Assistir skill](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/SKILL.md): `plugin/skills/assistir/SKILL.md`
- [CLI shortcut](https://github.com/kalebe-silva/claude-assistir/blob/main/bin/assistir): `bin/assistir`

### Video processing

- [Workflow runner](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`
- **Video source**
- [URL download](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`
- **yt-dlp**
- **FFmpeg**
- [Distinct frames](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`

### Speech and captions

- [Caption parsing](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`
- [Local transcription](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`
- **faster-whisper**

### Generated results

- [Timeline assembly](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`
- **Briefing files**
- [Video metadata](https://github.com/kalebe-silva/claude-assistir/blob/main/plugin/skills/assistir/assistir.py): `plugin/skills/assistir/assistir.py`

### Other components

- **User**

## Connections

- User → Claude Code: requests analysis (evidence: `README.md`)
- Claude Code → Assistir skill: invokes skill (evidence: `README.md`)
- User → CLI shortcut: runs command (evidence: `README.md`)
- CLI shortcut → Workflow runner: launches (evidence: `README.md`)
- User → Workflow runner: provides input (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → URL download: downloads URL (evidence: `plugin/skills/assistir/assistir.py`)
- URL download → yt-dlp: uses (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → Video source: uses local or fetched video (evidence: `README.md`)
- Workflow runner → Distinct frames: extracts (evidence: `plugin/skills/assistir/assistir.py`)
- Distinct frames → FFmpeg: decodes frames (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → Caption parsing: parses available captions (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → Local transcription: transcribes without captions (evidence: `plugin/skills/assistir/assistir.py`)
- Local transcription → FFmpeg: extracts audio (evidence: `plugin/skills/assistir/assistir.py`)
- Local transcription → faster-whisper: transcribes locally (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → Timeline assembly: assembles results (evidence: `plugin/skills/assistir/assistir.py`)
- Timeline assembly → Briefing files: writes roteiro.md (evidence: `plugin/skills/assistir/assistir.py`)
- Workflow runner → Video metadata: writes metadata (evidence: `plugin/skills/assistir/assistir.py`)
- Video metadata → Briefing files: saves meta.json (evidence: `plugin/skills/assistir/assistir.py`)
