Wildcard

Between your own coding sessions, AI agents running tasks, and work spread across multiple machines, there's a lot happening in a day. Too much to keep in your head. Wildcard captures all of it — file edits, app focus, agent activity — into a local timeline that your AI can use to help you prioritize, write daily briefs, and keep track of what actually got done.

Tools like ActivityWatch and screenpipe are impressive projects, but this data is deeply personal. I wanted something with no telemetry, a low memory footprint, and a codebase simple enough to fork and own completely. Wildcard is MIT-licensed and will always be free of any tracking. As local models get better, the goal is to drop third-party AI providers entirely.

How it works

Wildcard runs as a background daemon that watches your project directories. File changes become timestamped events in a local SQLite database. Those events get grouped into sessions, then summarized into project-level reports — optionally enriched by a coding agent that reads your git history and explains what changed in plain language.

The real payoff is multi-device: run wildcard on your laptop, your dev server, wherever your agents operate. Each device syncs to a central archive, giving you (or your AI agent — openclaw, Claude, ChatGPT, whatever you use) a single feed of everything that happened.

Status: early alpha. Expect breaking changes while the data model and UX settle.

For implementation details, see docs/ARCHITECTURE.md. For the operator-focused reporting workflow used by AI agents, see SKILL.md.

Requirements

• Bun 1.3.8
• macOS or Linux (Windows is not supported; use WSL2 if needed)
• Optional: Ollama, OpenAI, or Gemini for AI summaries

Install

bun add -g @andypai/wildcard
wildcard setup

Or install from source:

git clone git@github.com:abpai/wildcard.git
cd wildcard
bun install
ln -sf "$(pwd)/src/wildcard.ts" ~/.bun/bin/wildcard

Usage

Commands are intended to run via the wildcard bin.

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

# Start watching as a daemon
wildcard watch --roots ~/code --daemon

# Show today's sessions
wildcard show today

# Show chronological activity log (today by default)
wildcard log
wildcard log week

# Generate a weekly report
wildcard report week

# Enrich projects with AI-powered change analysis (requires Codex CLI)
wildcard enrich
wildcard enrich --period week
wildcard enrich --dry-run

# Push pending local data to a central ingest server
wildcard sync push

# Start the central archive ingest endpoint
wildcard server start

# Start the archive server as a managed daemon
wildcard server start --daemon

# Inspect, stop, restart, or validate the managed archive server
wildcard server status
wildcard server stop
wildcard server restart
wildcard server doctor

# Search the timeline
wildcard search "config" --from 2025-01-01 --to 2025-01-31 --types edit,ocr

# Check daemon status
wildcard status
wildcard status --json

# macOS: install/uninstall launchd service
wildcard launchd install --roots ~/code
wildcard launchd uninstall
wildcard launchd restart

# Linux: install/uninstall systemd user service
wildcard systemd install --roots ~/code
wildcard systemd uninstall
wildcard systemd restart

# Prune old local data
wildcard prune --older-than 30

For one release, bun run server remains as a compatibility alias to wildcard server start.

Archive Host Workflow

Use wildcard server start on the central archive host and point it at timeline.db so the regular CLI and the ingest endpoint read and write the same archive directly.

wildcard server start --db-path ~/.wildcard/timeline.db
wildcard server status --db-path ~/.wildcard/timeline.db

Remote devices should set:

• sync.server_url to the archive host URL
• identity.device_id to a unique per-device value

Update launchd service (macOS)

• Reload the running service after code/config updates: wildcard launchd restart
• Rebuild service definition (for changed roots or plist args): wildcard launchd install --roots ~/code
• Full clean reinstall if launchd gets into a bad state: wildcard launchd uninstall wildcard launchd install --roots ~/code

Update systemd service (Linux)

• Reload the running service after code/config updates: wildcard systemd restart
• Rebuild service definition (for changed roots): wildcard systemd install --roots ~/code
• Full clean reinstall: wildcard systemd uninstall wildcard systemd install --roots ~/code

Event types:

• edit: emitted by wildcard watch (filesystem activity)
• ocr, audio, ui: supported by the timeline schema and ingest APIs for non-filesystem sources

Useful flags:

• show, log, report, search: --device <ids> to filter multi-device data
• report: --force-refresh to bypass summary cache
• report: --no-ai to force heuristic summaries
• report: --no-enrich to skip automatic code enrichment
• report: --no-progress to keep stdout clean for piping or file capture
• log: --json for machine-readable output
• status: --json for machine-readable output
• watch: --memlog, --mem-warn-mb, --mem-limit-mb for memory logging/guards

Configuration

Default config path: ~/.wildcard/config.yaml. Data lives under ~/.wildcard/ by default. Defaults come from src/config/config-store.ts; the example below shows the most relevant fields rather than every compatibility knob.

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:7070
  batch_size: 500
  max_payload_bytes: 2097152
  interval_s: 300
  max_retries: 8
  batch_delay_ms: 0

server:
  host: 0.0.0.0
  port: 7070
  db_path: ~/.wildcard/timeline.db
  api_key:
  allowed_devices: []
  max_body_size_bytes: 10485760
  pid_file: ~/.wildcard/wildcard-server.pid

Environment variables:

• WILDCARD_STORE_DIR
• WILDCARD_CONFIG_PATH
• WILDCARD_WATCH_ROOTS
• WILDCARD_AI_ENABLED
• WILDCARD_AI_PROVIDER
• WILDCARD_AI_MODEL
• WILDCARD_AI_BASE_URL
• WILDCARD_AI_API_KEY (fallbacks: OPENAI_API_KEY for OpenAI, GEMINI_API_KEY for Gemini)
• WILDCARD_DEVICE_ID
• WILDCARD_SYNC_ENABLED
• WILDCARD_SYNC_SERVER_URL
• WILDCARD_SYNC_API_KEY
• WILDCARD_SYNC_BATCH_SIZE
• WILDCARD_SYNC_MAX_PAYLOAD_BYTES
• WILDCARD_SYNC_INTERVAL_S
• WILDCARD_SYNC_MAX_RETRIES
• WILDCARD_SYNC_BATCH_DELAY_MS
• WILDCARD_SERVER_HOST
• WILDCARD_SERVER_PORT
• WILDCARD_SERVER_DB_PATH
• WILDCARD_SERVER_API_KEY
• WILDCARD_SERVER_ALLOWED_DEVICES
• WILDCARD_SERVER_MAX_BODY_SIZE_BYTES
• WILDCARD_SERVER_PID_FILE
• WILDCARD_DEBUG_OSASCRIPT (1 to log frontmost-app AppleScript stderr/debug details)

Legacy server env fallbacks kept for one release:

• PORT
• MAX_BODY_SIZE
• WILDCARD_API_KEY
• WILDCARD_ALLOWED_DEVICES
• WILDCARD_DB_PATH

AI summary prompt templates live in src/summary/prompts/*.md. The markdown files hold the stable system instructions, while runtime session/project data is still assembled in code.

Data Locations

• ~/.wildcard/timeline.db (SQLite timeline)
  • includes events, events_fts, summary cache tables, and app_usage focus segments
• ~/.wildcard/blobs/ (content-addressable blobs)
• ~/.wildcard/wildcard.pid (daemon PID)
• ~/.wildcard/wildcard-server.pid (archive server daemon PID)
• ~/Library/LaunchAgents/com.wildcard.wildcard.plist (macOS launchd)
• ~/.wildcard/launchd.out.log and ~/.wildcard/launchd.err.log (macOS logs)

Development

git clone git@github.com:abpai/wildcard.git
cd wildcard
bun install
ln -sf "$(pwd)/src/wildcard.ts" ~/.bun/bin/wildcard
bun run check
wildcard --help

Introspection Scripts

# Inspect schema + event/app usage + sync cursor health
bun scripts/explore-db.ts

# Generate ad-hoc AI summary output from local timeline
bun scripts/ai-summary.ts

Security and Privacy

Wildcard stores activity data locally by default. If you enable AI providers or remote sync, data may be sent to those services depending on your config. Review SECURITY.md for reporting vulnerabilities.

License

MIT. See LICENSE.