# Wildcard

> Help users interact with wildcard — a Bun-first CLI that captures file activity into a local timeline for search and summary. Covers running commands, configuring the tool, managing the macOS daemon, and troubleshooting.

- Skill: `abpai/wildcard` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add abpai/wildcard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abpai/wildcard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: abpai (https://skillmd.com/u/abpai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/abpai/wildcard

---


# Wildcard

Wildcard is a local-first CLI that captures file activity into a SQLite timeline you can search and summarize. It watches directories for filesystem changes, groups events into sessions, and generates heuristic or AI-powered summaries. Everything stays on your machine by default.

The tool is designed for personal developer workflows: start a watcher, work normally, then review what you did with `show`, `report`, or `search`.

For general installation and operator-facing usage, see [README.md](README.md). For implementation details and source-of-truth architecture notes, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## When to Use This Skill

Use this skill when the user wants to:

- **Start watching** file activity (`watch`)
- **Check daemon status** (`status`)
- **View sessions** for a time period (`show`, `log`)
- **Generate reports** with optional AI summaries (`report`)
- **Search the timeline** for past activity (`search`)
- **Configure** wildcard (config.yaml, env vars)
- **Push local data upstream** (`sync push`)
- **Manage the macOS daemon** (install/uninstall launchd, restart)
- **Enrich reports** with AI-powered git change analysis (`enrich`)
- **Maintain data** (prune old data, archive to another DB)
- **Troubleshoot** issues (daemon not running, stale PID, AI not working)
- **Set up** wildcard for the first time (`setup`)

## Quick Start

```bash
# Install from source
git clone git@github.com:abpai/wildcard.git
cd wildcard
bun install

# Symlink the binary
ln -sf "$(pwd)/src/wildcard.ts" ~/.bun/bin/wildcard

# Verify
wildcard --help

# Start watching (foreground)
wildcard watch --roots ~/code

# View today's sessions
wildcard show today
```

## Core Commands

### watch — Capture file activity

Start the file watcher in foreground or as a background daemon.

```bash
# Foreground (Ctrl+C to stop)
wildcard watch --roots ~/code

# Background daemon
wildcard watch --roots ~/code --daemon

# With memory logging and guards
wildcard watch --daemon --memlog --mem-warn-mb 512 --mem-limit-mb 1024
```

**Flags:**

| Flag                  | Description                         |
| --------------------- | ----------------------------------- |
| `--roots <paths...>`  | Watch roots (comma/space separated) |
| `--daemon`            | Run as a detached background daemon |
| `--memlog`            | Log memory usage every minute       |
| `--mem-warn-mb <mb>`  | Warn when RSS exceeds this value    |
| `--mem-limit-mb <mb>` | Exit when RSS exceeds this value    |

### show — View session timeline

Display sessions grouped by project for a time period.

```bash
wildcard show today
wildcard show yesterday
wildcard show week
```

The period can also be passed as a flag: `wildcard show --today`, `--yesterday`, or `--week`.

### log — View chronological activity log

Display activity broken down by time slot — hourly for today/yesterday, daily for week.

```bash
wildcard log
wildcard log today
wildcard log yesterday
wildcard log week
```

The period can also be passed as a flag: `wildcard log --today`, `--yesterday`, or `--week`.

**Difference from `show`**: `log` is time-first (each time slot lists the projects active in it), while `show` is project-first (each project shows its total time). Use `log` to answer "what was I doing at 2pm?"; use `show` to answer "how much time did I spend on each project?"

**Flags:**

| Flag             | Description                             |
| ---------------- | --------------------------------------- |
| `--device <ids>` | Filter by device ID(s), comma-separated |
| `--json`         | Output machine-readable JSON            |

### report — Generate summary reports

Generate heuristic or AI-powered reports for a time period.

```bash
wildcard report today
wildcard report week

# Force heuristic summaries (skip AI even if enabled)
wildcard report today --no-ai

# Regenerate summaries, bypassing the cache
wildcard report week --force-refresh

# Enriched report workflow (project-aware summary)
wildcard show yesterday
wildcard report yesterday --no-progress
# Then inspect top projects locally (read-only):
# - README*
# - package.json / pyproject.toml / go.mod / Cargo.toml
```

**Flags:**

| Flag              | Description                             |
| ----------------- | --------------------------------------- |
| `--no-ai`         | Force heuristic summaries               |
| `--no-enrich`     | Skip automatic code enrichment          |
| `--force-refresh` | Bypass summary cache and regenerate     |
| `--device <ids>`  | Filter by device ID(s), comma-separated |
| `--no-progress`   | Disable progress output on stderr       |

## Context-Enriched Reporting Workflow

For summary/report requests:

1. If enrichment data is available, run `wildcard enrich` first to analyze git changes. This pre-gathers redacted git diffs and sends them to Codex CLI for structured summaries that feed into the report.
2. Run `wildcard show <period>` and `wildcard report <period> --no-progress`.
3. If `wildcard report ... --no-progress` stalls for ~60 seconds, rerun with `--no-ai --no-progress`.
4. Rank projects by active time.
5. Enrich the top 3 projects, plus any project with at least 20 minutes active time.
6. For each enriched project:
   - Detect repo path from project name, window titles, and key file paths.
   - Read local project metadata (`README*`, `package.json`, `pyproject.toml`, `go.mod`, or `Cargo.toml` as available).
   - Use changed-file evidence from wildcard output to identify meaningful edits.
7. Produce per-project impact analysis with explicit confidence and unknowns.

### Automated Enrichment via `wildcard enrich`

The `enrich` command automates git change analysis for qualifying projects:

```bash
wildcard enrich                  # Enrich today's projects
wildcard enrich --period week    # Enrich this week's projects
wildcard enrich --dry-run        # Preview what would be enriched
```

Enrichment pre-gathers redacted git context (commits, diffs, working tree status) and sends it to Codex CLI for synthesis. Results are stored in the database and automatically injected into `wildcard report` summaries. Projects below activity thresholds (< 5 edits, < 2 source files, < 1 min duration) are skipped. Requires the Codex CLI to be installed (`npm install -g @openai/codex`).

## Project Enrichment Heuristics

Use these signals in priority order to infer what each project does:

1. Local `README*` one-liner and opening overview.
2. Package manifest name/description (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`).
3. Dominant directories and file naming patterns.
4. Active window titles from app usage context.

Prioritize high-signal files when describing changes:

- Entrypoints: `src/index*`, `main*`, CLI entry files.
- Config/build surfaces: `package.json`, `tsconfig*`, eslint/prettier config, CI files.
- Core modules under `src/` and other primary source directories.
- Tests tied to changed implementation modules.

De-emphasize low-signal files unless they materially change behavior:

- Temp files, download artifacts, `.crdownload`, editor swap files.
- Lockfile-only churn unless dependency impact is clear.

## Impact Mapping Rubric

Map changed files to likely project impact:

- `config/build` changes: tooling behavior, build/runtime risk, and environment implications.
- `core logic` changes: feature behavior, bug fixes, or refactors.
- `tests` changes: confidence level and regression coverage direction.
- `docs/content` changes: communication, onboarding, and knowledge transfer impact.

Use explicit, evidence-linked language:

- "Likely changed X because files A/B changed."
- "Unknown: couldn't confirm runtime path from available evidence."

Do not fabricate project purpose. Mark inferred conclusions explicitly when evidence is partial.

## Standard Output Template for Reports

Use this structure for each major project in enriched reports:

```md
### <project> - <time> - <edits/files>

- What this project is: ...
- What changed (key files only): ...
- Likely impact: ...
- Confidence: High|Medium|Low
- Unknowns / follow-ups: ...
```

Global summary expectations:

- Include total active time for the period.
- Identify top workstreams by time and edit density.
- Describe cross-project pattern (for example, refactor-heavy vs feature-heavy).
- Mention context switching only when it materially changes interpretation.

## Operational Safeguards

- If `wildcard report ... --no-progress` hangs for about 60 seconds, fallback to `wildcard report ... --no-ai --no-progress`.
- If report generation fails with lock contention, use `wildcard show` plus targeted `wildcard search` queries and state that limitation clearly.
- Keep enrichment read-only when exploring tracked projects.

### search — Query the timeline

Full-text search across file paths, OCR text, audio transcripts, and UI snippets.

```bash
wildcard search "authentication"

# Filter by time range
wildcard search "config" --from 2025-01-01 --to 2025-01-31

# Filter by event type
wildcard search "refactor" --types edit
wildcard search "meeting" --types audio,ocr
```

**Flags:**

| Flag              | Description                                   |
| ----------------- | --------------------------------------------- |
| `--from <iso>`    | Start time (ISO format)                       |
| `--to <iso>`      | End time (ISO format)                         |
| `--types <types>` | Comma-separated: `edit`, `ocr`, `audio`, `ui` |

### status — Check daemon state

```bash
wildcard status
wildcard status --json
```

Shows whether the daemon is running, its PID, and the last event timestamp.

### setup — Interactive first-time setup

```bash
wildcard setup
```

Walks through initial configuration interactively.

### sync push — Upload pending local data

```bash
wildcard sync push
```

Use this when `sync.server_url` is configured and you want to push local `events` plus `app_usage` rows to a central ingest server. For reliable multi-device sync, set `identity.device_id` explicitly.

## macOS Daemon Management

### Install LaunchAgent

Creates a launchd plist for automatic startup on login.

```bash
wildcard launchd install --roots ~/code
```

### Uninstall LaunchAgent

Removes the plist and stops the service.

```bash
wildcard launchd uninstall
```

### Restart

Reload the running service after code or config changes.

```bash
wildcard launchd restart
```

### Update workflow

- **Config/code changed:** `wildcard launchd restart`
- **Watch roots changed:** `wildcard launchd install --roots ~/code` (rebuilds the plist)
- **Launchd in a bad state:** `wildcard launchd uninstall && wildcard launchd install --roots ~/code`

### View logs

```bash
tail -f ~/.wildcard/launchd.out.log   # stdout
tail -f ~/.wildcard/launchd.err.log   # stderr
```

## Configuration

Default config path: `~/.wildcard/config.yaml`. Defaults come from `src/config/config-store.ts`; the example below focuses on the fields users most commonly change.

```yaml
store_dir: ~/.wildcard

watch:
  roots:
    - ~/code
  ignore:
    - .git/**
    - node_modules/**
    - dist/**
    - '**/*.lock'
  debounce_ms: 300
  non_git_grouping: top_level_dir
  app_usage_capture: true
  app_usage_poll_ms: 5000
  backfill_on_start: false
  checkpoint_interval_s: 60

session:
  idle_threshold_s: 300
  activity_window_s: 120

ai:
  enabled: false
  provider: ollama
  model: qwen3.5:latest
  base_url: http://localhost:11434

identity:
  device_id: laptop

sync:
  enabled: false
  server_url: http://localhost:3000
  batch_size: 500
  max_payload_bytes: 2097152
  interval_s: 300
  max_retries: 8
  batch_delay_ms: 0
```

### Environment variable overrides

| Variable                          | Description                                               |
| --------------------------------- | --------------------------------------------------------- |
| `WILDCARD_STORE_DIR`              | Override data directory                                   |
| `WILDCARD_CONFIG_PATH`            | Override config file path                                 |
| `WILDCARD_WATCH_ROOTS`            | Comma-separated watch roots                               |
| `WILDCARD_AI_ENABLED`             | Enable/disable AI (`true`/`false`)                        |
| `WILDCARD_AI_PROVIDER`            | `ollama`, `openai`, or `gemini`                           |
| `WILDCARD_AI_MODEL`               | Model name                                                |
| `WILDCARD_AI_BASE_URL`            | Provider base URL                                         |
| `WILDCARD_AI_API_KEY`             | API key (also reads `OPENAI_API_KEY` or `GEMINI_API_KEY`) |
| `WILDCARD_DEVICE_ID`              | Override `identity.device_id`                             |
| `WILDCARD_SYNC_ENABLED`           | Enable/disable sync                                       |
| `WILDCARD_SYNC_SERVER_URL`        | Sync server base URL                                      |
| `WILDCARD_SYNC_API_KEY`           | Sync bearer token                                         |
| `WILDCARD_SYNC_BATCH_SIZE`        | Max rows per sync batch                                   |
| `WILDCARD_SYNC_MAX_PAYLOAD_BYTES` | Max sync payload size in bytes                            |
| `WILDCARD_SYNC_INTERVAL_S`        | Periodic sync interval in seconds                         |
| `WILDCARD_SYNC_MAX_RETRIES`       | Max upload retries                                        |
| `WILDCARD_SYNC_BATCH_DELAY_MS`    | Delay between sync batches in ms                          |
| `WILDCARD_DEBUG_OSASCRIPT`        | `1` to log frontmost-app debug details                    |

## Data Management

### Prune old data

Delete events, FTS rows, app usage, and summary cache older than N days.

```bash
wildcard prune --older-than 30
```

### Archive old data

Copy old rows to a separate SQLite file (preserves local data).

```bash
wildcard archive --older-than 90 --to ~/backups/wildcard-archive.db
```

### Data locations

| Path                                                 | Contents                                            |
| ---------------------------------------------------- | --------------------------------------------------- |
| `~/.wildcard/timeline.db`                            | SQLite timeline (events, FTS, summaries, app_usage) |
| `~/.wildcard/blobs/`                                 | Content-addressable blob store                      |
| `~/.wildcard/wildcard.pid`                           | Daemon PID file                                     |
| `~/.wildcard/config.yaml`                            | Configuration                                       |
| `~/.wildcard/launchd.out.log`                        | Daemon stdout log (macOS)                           |
| `~/.wildcard/launchd.err.log`                        | Daemon stderr log (macOS)                           |
| `~/Library/LaunchAgents/com.wildcard.wildcard.plist` | macOS LaunchAgent                                   |

## AI Summaries

Wildcard supports heuristic summaries by default. For AI-powered summaries, enable a provider:

### Ollama (local, free)

```yaml
ai:
  enabled: true
  provider: ollama
  model: qwen3.5:latest
```

Requires Ollama running locally: `ollama pull qwen3.5:latest`

### OpenAI

```yaml
ai:
  enabled: true
  provider: openai
  model: gpt-5.4-mini
  api_key: sk-your-key-here
```

Or via environment: `export OPENAI_API_KEY=sk-...`

### Gemini

```yaml
ai:
  enabled: true
  provider: gemini
  model: gemini-3.1-flash-lite-preview
  api_key: AI...
```

Or via environment: `export GEMINI_API_KEY=AI...`

## Troubleshooting

### "No sessions" when running show/report

1. Check daemon is running: `wildcard status`
2. Verify watch roots in `~/.wildcard/config.yaml`
3. Make edits in watched directories, then check again

### Daemon won't start (stale PID)

```bash
rm ~/.wildcard/wildcard.pid
wildcard watch --daemon
```

### AI summaries not working

**Ollama:** verify it's running and the model exists:

```bash
curl http://localhost:11434/api/tags
ollama list
```

**OpenAI:** verify the API key:

```bash
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### Database locked errors

Multiple processes accessing the database. Stop the daemon first:

```bash
kill $(cat ~/.wildcard/wildcard.pid)
```

Only run one instance of `wildcard watch`.

### LaunchAgent in a bad state

```bash
wildcard launchd uninstall
wildcard launchd install --roots ~/code
```

## Quick Reference

| Command                                            | Description                              |
| -------------------------------------------------- | ---------------------------------------- |
| `wildcard watch --roots <paths>`                   | Start file watcher (foreground)          |
| `wildcard watch --daemon`                          | Start as background daemon               |
| `wildcard status`                                  | Show daemon status                       |
| `wildcard status --json`                           | Show machine-readable status             |
| `wildcard show today\|yesterday\|week`             | List sessions for a period               |
| `wildcard log today\|yesterday\|week`              | Show chronological activity log          |
| `wildcard report today\|yesterday\|week`           | Generate summary report                  |
| `wildcard report --no-ai`                          | Report with heuristic summaries only     |
| `wildcard report --no-enrich`                      | Skip automatic code enrichment           |
| `wildcard report --force-refresh`                  | Regenerate summaries (bypass cache)      |
| `wildcard report --no-progress`                    | Suppress progress output on stderr       |
| `wildcard search "query"`                          | Full-text search                         |
| `wildcard search "q" --from <iso> --to <iso>`      | Search with time range                   |
| `wildcard search "q" --types edit,ocr`             | Search by event type                     |
| `wildcard enrich`                                  | Enrich projects with git change analysis |
| `wildcard enrich --period week`                    | Enrich this week's projects              |
| `wildcard enrich --dry-run`                        | Preview what would be enriched           |
| `wildcard setup`                                   | Interactive first-time setup             |
| `wildcard sync push`                               | Push pending local data upstream         |
| `wildcard launchd install --roots <paths>`         | Install macOS LaunchAgent                |
| `wildcard launchd uninstall`                       | Remove macOS LaunchAgent                 |
| `wildcard launchd restart`                         | Restart LaunchAgent service              |
| `wildcard prune --older-than <days>`               | Delete old data                          |
| `wildcard archive --older-than <days> --to <path>` | Copy old data to archive                 |