ai-tools

# AI Tools

## Important: Use Scripts First

**ALWAYS prefer the scripts in `scripts/` over raw `curl` API calls.** Scripts
are located in the `scripts/` subdirectory of this skill's folder. They provide
features that raw commands do not:

- Proper image encoding (WebP conversion, alpha removal)
- Appropriate model selection for each task
- Structured output handling (boolean responses via exit codes)
- Meaningful exit codes for shell integration

**When to read the script source:** If a script doesn't do exactly what you
need, or fails due to missing dependencies, read the script source. The scripts
encode Gemini API best practices (image ordering, structured output schemas,
model selection) that may not be obvious—use them as reference when building
similar functionality.

## Quick Start

**Environment:** Set `GEMINI_API_KEY` before running any commands.

**Dependencies:** `curl`, `jq`, `uv` (all tools); `base64`, `magick` (image
tools only)

```bash
# Gather context and analyze
scripts/context gemini-api | scripts/emerson "Explain the key features"

# Describe an image (generate alt-text)
scripts/screenshot-describe screenshot.png

# Compare two images for visual differences
scripts/screenshot-compare before.png after.png

# Smart crop image around detected people
scripts/photo-smart-crop photo.jpg cropped.jpg

# Check if a photo prominently features people
scripts/photo-has-people photo.jpg

# Generate essay-length analysis from text
scripts/emerson "Summarize the key changes" < documentation.md

# Evaluate a boolean condition against text
echo "Hello world" | scripts/satisfies "is a greeting"

# Count tokens in text
cat document.md | scripts/token-count

# Interact with an Android UI via AI
scripts/popper "start an exercise"
```

## Script Overview

### context

Gathers authoritative, up-to-date context for deep research on various technical
topics (e.g., `gemini-api`, `mcp`, `home-assistant`). Run with `--list` to see
all available topics. This script should be your first tool for gathering
background knowledge or the latest documentation for an unfamiliar domain.

**Warning:** Output can be very large. **Do not** read output directly into your
conversation history. Pipe to `emerson` for analysis, or redirect to a file to
search/read locally.

```bash
scripts/context TOPIC
```

**Options:** `--list` (list available topics)

**Exit codes:** 0 success, 1 error, 127 missing dependency

**Examples:**

```bash
# List available topics
scripts/context --list

# Gather context for Gemini API
scripts/context gemini-api > gemini-context.xml

# Pipe context directly to analysis
scripts/context gemini-cli | scripts/emerson "How do commands work?"
```

### screenshot-describe

Generate concise alt-text for an image. Optimized for UI captures.

```bash
scripts/screenshot-describe IMAGE [PROMPT]
```

**Exit codes:** 0 success, 1 error, 127 missing dependency

### screenshot-compare

Compare two images for visual differences. Identifies layout shifts, color
changes, padding, and text updates.

```bash
scripts/screenshot-compare IMAGE1 IMAGE2 [PROMPT]
```

**Exit codes:** 0 differences found, 1 error, 2 images identical, 127 missing
dependency

### photo-smart-crop

Smart crop images around detected people with a specified aspect ratio.
Prioritizes faces, expands for headroom, enforces aspect ratio.

```bash
scripts/photo-smart-crop [--ratio W:H] INPUT OUTPUT
```

**Options:** `--ratio W:H` (default 5:3)

**Exit codes:** 0 success, 1 error (no people found, API error), 2 rate limited,
127 missing dependency

**Examples:**

```bash
# Default 5:3 aspect ratio
scripts/photo-smart-crop family.jpg family-cropped.jpg

# 16:9 for video thumbnails
scripts/photo-smart-crop --ratio 16:9 portrait.jpg thumbnail.jpg

# Square crop for profile pictures
scripts/photo-smart-crop --ratio 1:1 headshot.png avatar.png
```

### photo-has-people

Detect if people feature prominently in a photo. Returns boolean via exit code.

```bash
scripts/photo-has-people IMAGE
```

**Options:** `-q, --quiet` (suppress output)

**Exit codes:** 0 true (has people), 1 false (no people), 127 missing dependency

**Examples:**

```bash
# Check if photo has people
if scripts/photo-has-people photo.jpg; then
  echo "Found people"
fi
```

### emerson

Generate essay-length (~3000 words) analysis from text input. Produces
authoritative, footnoted Markdown. Can be combined with `context` to provide
rich background material.

```bash
scripts/emerson "PROMPT" < input.txt
```

**Exit codes:** 0 success, 1 error, 127 missing dependency

### pascal

Ask a question and get a short, paragraph-style response (wrapped to 80
columns). Optimized for quick answers.

```bash
scripts/pascal "QUESTION"
```

**Input:** Optional context via stdin

**Exit codes:** 0 success, 1 error, 127 missing dependency

**Examples:**

```bash
# Ask a quick question
scripts/pascal "What is the capital of Peru?"

# Summarize a file
cat article.md | scripts/pascal "Summarize this article"

# Explain code
scripts/pascal "Explain this code" < script.sh
```

### satisfies

Evaluate whether input text satisfies a condition. Returns boolean via exit
code.

```bash
echo "text" | scripts/satisfies [-v|--verbose] "CONDITION"
```

**Options:** `-v, --verbose` (output "true" or "false" to stderr)

**Exit codes:** 0 true (satisfies), 1 false (does not satisfy), 127 missing
dependency

**Examples:**

```bash
# Check if file mentions a topic
cat file.txt | scripts/satisfies "mentions Elvis" && echo "Found it"

# Validate content type
cat response.json | scripts/satisfies "is valid JSON with an 'id' field"

# Use in conditionals
if cat log.txt | scripts/satisfies "contains error messages"; then
  echo "Errors detected"
fi
```

### token-count

Count tokens in text using the Gemini API.

```bash
cat file.txt | scripts/token-count
```

**Exit codes:** 0 success, 1 error, 127 missing dependency

### popper

Interact with Android UIs using an AI agent powered by `uiautomator2` and
Gemini. This allows semantic control of the device by providing a goal in
natural language.

```bash
scripts/popper "GOAL"
```

**Options:** `--launch PACKAGE` (launch a package before starting),
`--stay-in-app` (restrict the run to a single application package),
`--dump-layout` (print the current simplified UI layout as JSON and exit)

**Environment:** `ANDROID_SERIAL` (optional, target specific device)

**Exit codes:** 0 success (task completed), 1 error (task failed), 2 timeout

**Examples:**

```bash
# General UI task
scripts/popper "accept all permissions"

# Launch an app and keep the run inside it
scripts/popper --launch com.example.fitness --stay-in-app "start a running exercise"

# Target specific device
env ANDROID_SERIAL=12345 scripts/popper "open settings"
```

## Image Encoding Notes

- Images converted to lossless WebP for consistent encoding
- Alpha channel removed (`-alpha off`) so transparency-only differences are
  ignored
- Base64: use `-w 0` (Linux) or `-b 0` (macOS) for single-line output
- Single-image prompts: image before text (Gemini best practice)
- Multi-image comparison: text before images (Gemini best practice)

## Safety Notes

- Scripts require network access to the Gemini API
- `GEMINI_API_KEY` must be set in the environment
- API calls may incur usage costs
- Large images increase request size and latency
- Scripts do not store or log input data

## Reference Material

- **Command Reference**: Detailed documentation for each script. See
  [references/command-index.md](references/command-index.md).
- **Troubleshooting**: Common issues and solutions. See
  [references/troubleshooting.md](references/troubleshooting.md).