catime

Fetch and send AI-generated hourly cat images. Every hour a unique cat artwork is born via Google Gemini. Use when user asks for a cat picture, wants to browse the cat gallery, or requests the latest AI-generated cat image to be sent to them.

# catime — AI-Generated Hourly Cat Images 🐱

> **One-liner:** Fetch the latest (or any) AI-generated cat image and send it to the user with a caption and story.

Every hour, [catime](https://github.com/yazelin/catime) generates a unique cat artwork using Google Gemini. This skill allows an AI agent to retrieve cat images by number, date, or recency and **send them directly to the user** via the message tool.

---

## Installation

```bash
pip install catime
```

After installation the `catime` CLI is available. Verify:

```bash
catime --help
```

---

## Quick Start for AI Agents

### Step 1 — Retrieve a cat image with `catime`

Run the CLI to get image metadata. The most common command:

```bash
catime latest
```

**Exact output:**

```
Cat # 241  2026-02-11 04:57 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0457_UTC.webp
  Idea: 一隻以精緻黑絲線繡成的貓咪，正專注地在微縮的金色與黑色奢華香氛實驗室中，嗅聞試香紙上的氣味，整個場景以刺繡的微縮立體模型形式呈現。
  Prompt: An embroidered illustration of an elegant black cat, crafted from exquisite black silk threads with visible needlework, satin stitch, and French knots. The cat is presented as a handcrafted textile art miniature diorama...
  Story: 在一個宛如織品藝術品的微縮香室裡，環形燈的光線均勻地灑落，凸顯出所有織品與布料的精緻質感。這隻優雅的黑貓，其絲線繡成的毛髮閃爍著低調的光澤，牠全神貫注地分辨著香氣，周圍是數個鑲有金色瓶蓋的繡花香水瓶。牠正試圖從層疊的香氣中，捕捉那一縷最為珍貴的靈感。
```

### Step 2 — Parse the output and send the image to the user

Extract the **URL** from the line starting with `  URL:`. Then use the message tool (or equivalent) to send the image along with a caption.

**Example message tool payload (YAML):**

```yaml
action: send_message
media:
  type: image
  url: "https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0457_UTC.webp"
caption: "🐱 Cat #241 — AI-generated cat of the hour!"
text: |
  Here's your cat! Cat #241, created at 2026-02-11 04:57 UTC.
  Story: 在一個宛如織品藝術品的微縮香室裡，環形燈的光線均勻地灑落...
metadata:
  source: catime
  cat_number: 241
  model: gemini-3-pro-image-preview
  generated_at: "2026-02-11 04:57 UTC"
```

**Example message tool payload (JSON):**

```json
{
  "action": "send_message",
  "media": {
    "type": "image",
    "url": "https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0457_UTC.webp"
  },
  "caption": "🐱 Cat #241 — AI-generated cat of the hour!",
  "text": "Here's your cat! Cat #241, created at 2026-02-11 04:57 UTC.\nStory: 在一個宛如織品藝術品的微縮香室裡…",
  "metadata": {
    "source": "catime",
    "cat_number": 241,
    "model": "gemini-3-pro-image-preview",
    "generated_at": "2026-02-11 04:57 UTC"
  }
}
```

---

## Command Reference

### `catime latest`

Fetch the most recently generated cat.

**Input:**
```bash
catime latest
```

**Output:**
```
Cat # 241  2026-02-11 04:57 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0457_UTC.webp
  Idea: 一隻以精緻黑絲線繡成的貓咪…
  Prompt: An embroidered illustration of an elegant black cat…
  Story: 在一個宛如織品藝術品的微縮香室裡…
```

**Parse guidance:**
- **Line 1** — Header: `Cat # <NUMBER>  <DATE> <TIME> UTC  model: <MODEL>`
- **Line 2** (`  URL:`) — The image URL. **This is the most important line.**
- **Line 3** (`  Idea:`) — Short concept in Chinese.
- **Line 4** (`  Prompt:`) — Full image generation prompt in English.
- **Line 5** (`  Story:`) — Narrative story for the cat in Chinese.

### `catime today`

Fetch all cats generated today (UTC). Returns multiple cat entries.

**Input:**
```bash
catime today
```

**Output (excerpt):**
```
Found 2 cat(s) for 'today':

Cat # 240  2026-02-11 02:49 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0249_UTC.webp
  Idea: 一張以35mm底片攝影風格捕捉的畫面…
  Prompt: A candid 35mm film photograph…
  Story: 午後的自然漫射光，透過老舊窗戶溫柔地灑落在候車室地面…

Cat # 241  2026-02-11 04:57 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-02-11_0457_UTC.webp
  Idea: 一隻以精緻黑絲線繡成的貓咪…
  Prompt: An embroidered illustration of an elegant black cat…
  Story: 在一個宛如織品藝術品的微縮香室裡…
```

**Parse guidance:** The first line says `Found N cat(s) for 'today':`. Then each cat entry follows the same format as `catime latest`. To send the newest, pick the **last** entry.

### `catime <number>`

Fetch a specific cat by its sequential number.

**Input:**
```bash
catime 42
```

**Output:**
```
Cat #  42  2026-01-31 23:24 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-01-31_2324_UTC.webp
```

**Parse guidance:** Same format. Short entries (like numbered lookups) may only show the header and URL lines without Idea/Prompt/Story.

### `catime --list`

List all cats (number + URL, compact format).

**Input:**
```bash
catime --list
```

**Output (first 10 lines):**
```
Cat #   1  2026-01-30 05:46 UTC  model: gemini-2.5-flash-image
  URL: https://github.com/yazelin/ccat/releases/download/cats/cat_2026-01-30_0546_UTC.png
Cat #   2  2026-01-30 05:56 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-01-30_0556_UTC.webp
Cat #   3  2026-01-30 06:23 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-01-30_0623_UTC.webp
Cat #   4  2026-01-30 06:33 UTC  model: gemini-3-pro-image-preview
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-01-30_0633_UTC.webp
Cat #   5  2026-01-30 06:53 UTC  model: gemini-2.5-flash-image (fallback from gemini-3-pro-image-preview, reason: timeout after 180.0s)
  URL: https://github.com/yazelin/catime/releases/download/cats/cat_2026-01-30_0653_UTC.webp
```

**Parse guidance:** Each cat takes 2 lines. Odd lines are headers, even lines are URLs. Use `--list | tail -2` to get the latest, or `--list | wc -l` to count cats (divide by 2).

### `catime <date>`

Fetch cats from a specific date (YYYY-MM-DD format).

**Input:**
```bash
catime 2026-01-30
```

### `catime view`

Opens the web gallery in the default browser. Not useful for agents — use `latest` or a number instead.

---

## Agent Workflow: Send a Cat Image to User

Follow these steps exactly:

### 1. Decide which cat to fetch

| User request | Command to run |
|---|---|
| "Show me a cat" / "Send me a cat" | `catime latest` |
| "Show me today's cats" | `catime today` |
| "Show me cat number 42" | `catime 42` |
| "Show me cats from Jan 30" | `catime 2026-01-30` |
| "Show me a random cat" | `catime $(shuf -i 1-241 -n 1)` |

### 2. Run the command and capture stdout

```bash
output=$(catime latest 2>&1)
```

### 3. Parse the URL from stdout

Look for the line that starts with `  URL: `. Extract everything after `URL: `.

**Parsing rule (pseudocode):**
```
for each line in output:
    if line.strip().startswith("URL:"):
        image_url = line.strip().removeprefix("URL:").strip()
        break
```

**Parsing rule (bash):**
```bash
image_url=$(echo "$output" | grep '  URL: ' | head -1 | sed 's/.*URL: //')
```

### 4. Parse optional metadata

```
cat_number  → from header line: regex `Cat #\s*(\d+)`
datetime    → from header line: regex `(\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC)`
model       → from header line: regex `model: (.+)$`
story       → from line starting with `  Story: ` (everything after "Story: ")
prompt      → from line starting with `  Prompt: ` (everything after "Prompt: ")
```

### 5. Send the image to the user

Use the message tool with the extracted URL and metadata:

```yaml
action: send_message
media:
  type: image
  url: "<extracted image_url>"
caption: "🐱 Cat #<cat_number> — AI-generated cat of the hour!"
text: |
  Here's your cat! Cat #<cat_number>, created at <datetime>.
  Story: <story text>
metadata:
  source: catime
  cat_number: <cat_number>
  model: <model>
  generated_at: "<datetime>"
```

### 6. Fallback behavior

- **If URL is missing:** Tell the user the cat data was not available and suggest trying `catime latest` or a different number.
- *