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. For implementation details and source-of-truth architecture notes, see 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

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

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

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.

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.

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:

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:

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

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

wildcard status
wildcard status --json

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

setup — Interactive first-time setup

wildcard setup

Walks through initial configuration interactively.

sync push — Upload pending local data

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.

wildcard launchd install --roots ~/code

Uninstall LaunchAgent

Removes the plist and stops the service.

wildcard launchd uninstall

Restart

Reload the running service after code or config changes.

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

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.

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.

wildcard prune --older-than 30

Archive old data

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

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)

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

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

OpenAI

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

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)

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

AI summaries not working

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

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

OpenAI: verify the API key:

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:

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

Only run one instance of wildcard watch.

LaunchAgent in a bad state

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