AEO Track

Source: github.com/psyduckler/aeo-skills Part of: AEO Skills Suite

The scheduling layer for AEO visibility tracking. One command per workspace, one schedule, no infrastructure.

Requirements

• Python 3.9+ (stdlib only)
• macOS (launchd) OR Linux (cron)
• An aeo.config.json in the workspace directory (run aeo-init first)
• aeo-baseline installed somewhere this skill can find it

Usage

# Dry-run: see what would be installed
python3 scripts/track.py --install --schedule daily

# Actually install
python3 scripts/track.py --install --schedule daily --apply

# Custom schedule and time
python3 scripts/track.py --install --schedule weekly --hour 8 --apply

# Inspect current install
python3 scripts/track.py --status

# Remove
python3 scripts/track.py --remove --apply

Run from inside the workspace directory (the one containing aeo.config.json), or pass --workdir PATH.

How it works

1. Generates a wrapper script at ~/.aeo-track/<id>/run.sh that:
   • cds into the workspace directory
   • Sources .env from that directory if present (loads GEMINI_API_KEY)
   • Runs python3 /path/to/aeo-baseline/scripts/baseline.py --yes
   • Appends stdout/stderr to aeo-data/aeo-track.log
2. Installs a scheduled job that invokes the wrapper:
   • macOS → ~/Library/LaunchAgents/ai.skills.aeo-track.<id>.plist + launchctl load
   • Linux → crontab -l line with a unique marker for safe removal
3. Records state at ~/.aeo-track/<id>/state.json so --status and --remove know what to do.

<id> is sha1(absolute_workdir)[:12] — same workspace → same ID. Different workspaces don't collide.

Options

Schedule syntax

Setting up the API key

The wrapper script sources .env from the workspace dir if present. Put your API key there:

# In the workspace dir
cat > .env <<'EOF'
GEMINI_API_KEY=your_key_here
EOF
echo .env >> .gitignore

Both launchd and cron run with minimal shell environment by default, so the scheduled job won't see env vars from your interactive shell. The .env file is the bridge.

Inspect logs

After scheduled runs accumulate, check the log:

tail -f aeo-data/aeo-track.log

Each run produces a fresh evidence file in aeo-data/run_<timestamp>.json — same format as a manual aeo-baseline invocation.

Idempotency

• Re-installing (with --apply) on the same workspace replaces the previous schedule. On macOS this unloads + reloads the plist; on Linux it strips matching lines from crontab -l before appending the new one.
• --remove --apply is safe to run even if nothing is installed.
• State is per-workspace, so installing in multiple project directories doesn't collide.

Limitations (v0)

• Windows is not supported for --apply. The dry-run still prints the wrapper script so you can wire it into Task Scheduler manually.
• The wrapper runs with the user's environment, so cron-style limits on subprocess resource usage apply.
• No retry logic at the schedule layer — if a scheduled run fails, the next one tries fresh. aeo-baseline itself retries failed API calls internally.
• --status confirms launchd has the job loaded; for cron it only checks the recorded state file (run crontab -l | grep aeo-track for the live view).

Pairs With

• aeo-init — creates the aeo.config.json that this skill schedules
• aeo-baseline — the script that actually runs on each tick
• aeo-report (coming) — reads the accumulated baselines and generates trend reports