# mirage-hq/tesseract architecture

> Architecture diagram of the GitHub repository mirage-hq/tesseract, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mirage-hq/tesseract
- Repository: https://github.com/mirage-hq/tesseract

## Overview

Tesseract is a pair of agent-facing skills for operating a local creative CLI, rather than a conventional application server. The primary workflow is an agent following a skill to import footage, edit or create motion graphics, inspect sound and preview revisions, then render locally while retaining an editable project. The README and reference-directory names document broader editing and motion capabilities; sampled code confirms local sound, waveform, and FFmpeg helper behavior. The CLI and most project operations are not in the sampled source, so their internal wiring is not inferred.

Main entry points: [`skills/tesseract-video/scripts/tesseract_sound.py`](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_sound.py) (Sound tools), [`skills/tesseract-video/scripts/tesseract_waveform.py`](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_waveform.py) (Waveform review), [`skills/tesseract-video/SKILL.md`](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/SKILL.md) (Edit Video skill), [`skills/tesseract-motion/SKILL.md`](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-motion/SKILL.md) (Motion Graphics skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Agent guidance"]
  node_video_skill["Edit Video skill<br/>[SKILL.md]"]
  node_motion_skill["Motion Graphics skill<br/>[SKILL.md]"]
  node_video_refs["Video references"]
  node_motion_refs["Motion references"]
end

subgraph group_creation["Creative workflow"]
  node_cli["Tesseract CLI"]
  node_footage["Source media"]
  node_edit["Video editing"]
  node_motion["Motion graphics"]
  node_project["Editable project"]
  node_preview["Preview and revise"]
  node_render["Rendered video"]
end

subgraph group_audio["Sound review"]
  node_sound_tool["Sound tools<br/>[tesseract_sound.py]"]
  node_waveform["Waveform review"]
  node_sound_output["Sound reports and cues"]
end

subgraph group_local["Local processing"]
  node_media_helpers["Media helpers<br/>[tesseract_media.py]"]
  node_ffmpeg["FFmpeg tools"]
end

node_agent(("AI agent"))

node_agent -->|"follows"| node_video_skill
node_agent -->|"follows"| node_motion_skill
node_video_skill -->|"consults"| node_video_refs
node_motion_skill -->|"consults"| node_motion_refs
node_agent -->|"directs"| node_cli
node_footage -->|"provides media"| node_cli
node_cli -->|"performs edits"| node_edit
node_cli -->|"creates graphics"| node_motion
node_cli -->|"saves project"| node_project
node_cli -->|"previews"| node_preview
node_preview -->|"guides revision"| node_agent
node_cli -->|"renders locally"| node_render
node_agent -->|"invokes"| node_sound_tool
node_sound_tool -->|"dispatches waveform"| node_waveform
node_sound_tool -->|"uses"| node_media_helpers
node_waveform -->|"uses"| node_media_helpers
node_sound_tool -->|"runs"| node_ffmpeg
node_waveform -->|"runs"| node_ffmpeg
node_sound_tool -->|"writes cues or reports"| node_sound_output
node_waveform -->|"writes review files"| node_sound_output

click node_video_skill "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/SKILL.md"
click node_motion_skill "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-motion/SKILL.md"
click node_video_refs "https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-video/references"
click node_motion_refs "https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-motion/references"
click node_edit "https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-video/references"
click node_motion "https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-motion/references"
click node_preview "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/references/review-and-delivery.md"
click node_sound_tool "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_sound.py"
click node_waveform "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_waveform.py"
click node_media_helpers "https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_media.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_video_skill,node_motion_skill,node_video_refs,node_motion_refs toneBlue
class node_cli,node_footage,node_edit,node_motion,node_project,node_preview,node_render toneAmber
class node_sound_tool,node_waveform,node_sound_output toneMint
class node_media_helpers,node_ffmpeg toneRose
class node_agent toneIndigo
```

## Components

### Agent guidance

- [Edit Video skill](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/SKILL.md): `skills/tesseract-video/SKILL.md`
- [Motion Graphics skill](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-motion/SKILL.md): `skills/tesseract-motion/SKILL.md`
- [Video references](https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-video/references): `skills/tesseract-video/references`
- [Motion references](https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-motion/references): `skills/tesseract-motion/references`

### Creative workflow

- **Tesseract CLI**
- **Source media**
- [Video editing](https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-video/references): `skills/tesseract-video/references`
- [Motion graphics](https://github.com/mirage-hq/tesseract/tree/main/skills/tesseract-motion/references): `skills/tesseract-motion/references`
- **Editable project**
- [Preview and revise](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/references/review-and-delivery.md): `skills/tesseract-video/references/review-and-delivery.md`
- **Rendered video**

### Sound review

- [Sound tools](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_sound.py): `skills/tesseract-video/scripts/tesseract_sound.py`
- [Waveform review](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_waveform.py): `skills/tesseract-video/scripts/tesseract_waveform.py`
- **Sound reports and cues**

### Local processing

- [Media helpers](https://github.com/mirage-hq/tesseract/blob/main/skills/tesseract-video/scripts/tesseract_media.py): `skills/tesseract-video/scripts/tesseract_media.py`
- **FFmpeg tools**

### Other components

- **AI agent**

## Connections

- AI agent → Edit Video skill: follows
- AI agent → Motion Graphics skill: follows
- Edit Video skill → Video references: consults
- Motion Graphics skill → Motion references: consults
- AI agent → Tesseract CLI: directs
- Source media → Tesseract CLI: provides media
- Tesseract CLI → Video editing: performs edits
- Tesseract CLI → Motion graphics: creates graphics
- Tesseract CLI → Editable project: saves project
- Tesseract CLI → Preview and revise: previews
- Preview and revise → AI agent: guides revision
- Tesseract CLI → Rendered video: renders locally
- AI agent → Sound tools: invokes
- Sound tools → Waveform review: dispatches waveform
- Sound tools → Media helpers: uses
- Waveform review → Media helpers: uses
- Sound tools → FFmpeg tools: runs
- Waveform review → FFmpeg tools: runs
- Sound tools → Sound reports and cues: writes cues or reports
- Waveform review → Sound reports and cues: writes review files