Catime

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 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

pip install catime

After installation the catime CLI is available. Verify:

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:

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):

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):

{
  "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:

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:

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:

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:

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:

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

2. Run the command and capture stdout

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):

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:

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.
• If catime is not installed: Run pip install catime first, then retry.
• If network error: The CLI fetches catlist.json from GitHub. If offline, tell the user the cat gallery requires internet access.
• If the user wants multiple cats: Use catime today and parse all entries (each entry separated by a blank line). Send the first or let the user choose.

Output Format Reference

Every catime command outputs cat entries in this format:

Cat # <NUMBER>  <YYYY-MM-DD> <HH:MM> UTC  model: <MODEL_NAME>
  URL: <IMAGE_URL>
  Idea: <SHORT_CONCEPT_TEXT>
  Prompt: <FULL_GENERATION_PROMPT>
  Story: <NARRATIVE_TEXT>

Field-by-field guide:

Key notes for parsing:

• The URL line is always present and is the critical field for sending images.
• Idea, Prompt, and Story appear in detailed views (latest, today, specific number with detail) but may be absent in --list mode.
• All URLs point to GitHub Releases — they are publicly accessible, no auth needed.
• Image formats are .webp (most common) or .png (older cats).

Tips for AI Agents

1. Always use catime latest as the default when the user just wants "a cat."
2. The URL is on the line starting with URL: — this is all you need to send an image.
3. Stories are in Chinese — you can translate them for English-speaking users or include them as-is for bilingual charm.
4. Images are hosted on GitHub Releases — they load fast and don't require authentication.
5. New cats appear every hour — if the user wants a fresh one, latest always works.
6. For random selection, pick a random number between 1 and the latest cat number.
7. --list is efficient for browsing — it only shows 2 lines per cat (header + URL).
8. Do not use catime view — it opens a browser, which is not useful in agent/CLI context.
9. Include the story in your caption when available — it adds personality and delight.
10. The Prompt field is useful if the user is curious about how the image was generated.

About catime

• 🎨 AI-generated cat images every hour using Google Gemini
• 📚 103+ art styles in the style library
• 🐱 Each cat has a unique story and personality
• 🌐 Gallery: yazelin.github.io/catime
• 📦 PyPI: pip install catime
• ⭐ GitHub: github.com/yazelin/catime

Note: A helper script for automated cat-sending workflows can be written if needed, but the CLI commands above are sufficient for all agent operations.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.