README.md

Cold Turkey Automation Toolkit

Unified helper scripts for running Cold Turkey Blocker from Windows Subsystem for Linux (WSL). The toolkit combines the original scheduled automation and manual control scripts into a single entry point, centralises config/state/logs, and keeps everything inside this repo.

Features

• Single CLI (scripts/ct.sh) for automated schedules and manual control.
• Shared log file at logs/cold-turkey.log plus lightweight state tracking.
• Missed-action recovery to catch up after downtime, with optional --dry-run.
• Multiple block profiles via --block, with per-block state files and wrappers.
• Config validation (validate) and upcoming schedule preview (next).
• Built-in alias helper for quickly wiring ct (or any name) into your shell.

Requirements

• Windows 10/11 with Cold Turkey Blocker installed (tested with WSL).
• WSL distro with Bash 5+, jq, and the Windows filesystem mounted at /mnt/c.
• Cron (or Task Scheduler calling WSL) if you plan to run scheduled automation.

Install jq on Ubuntu/Debian-based distros:

sudo apt-get update && sudo apt-get install -y jq

Repository Layout

• scripts/ct.sh – main entry point for automation and manual commands.
• config/blocks.example.json – index template; copy to config/blocks.json and point it at your block files.
• config/blocks/*.example.json – per-block templates you can clone into config/blocks/<name>.json.
• logs/ – runtime logs (logs/cold-turkey.log).
• state/ – last-run timestamp and block status tracking (auto-created).
• .gitignore – excludes logs, state, and your real config.

Setup

1. Copy the index template and customise it:

   cp config/blocks.example.json config/blocks.json

   Update the default key to whichever block you want to run when --block isn’t provided, and make sure the blocks mapping points at the files you create in the next step.

2. Copy the per-block templates you need:

   cp config/blocks/focus-mode.example.json config/blocks/focus-mode.json
   cp config/blocks/deep-work.example.json config/blocks/deep-work.json

   For each block file you create:

   • block_name must match the block name inside the Cold Turkey app.

• ct_path is optional; include it when a block needs a custom Cold Turkey executable (e.g. separate installs, portable copies, or a non-standard location) and omit it to use the script’s built-in Windows path detection.
• schedules holds your time/action/day entries (times use 24h HH:MM, actions are start or stop, days use short names e.g. "Mon").

3. (Optional) Symlink scripts/ct.sh into your $PATH for shorter commands.

Usage

# Run scheduled automation (intended for cron)
./scripts/ct.sh auto

# Manual overrides
./scripts/ct.sh start "Deep work sprint"
./scripts/ct.sh --block deep-work stop "Break time"
./scripts/ct.sh toggle "Context switch"
./scripts/ct.sh status
./scripts/ct.sh next 3
./scripts/ct.sh validate
./scripts/ct.sh --dry-run auto
./scripts/ct.sh alias --install
./scripts/ct.sh help

You can point to an alternate config file with --config /path/to/config.json or by exporting CT_CONFIG=/path/to/config.json.

• --block NAME picks a profile registered in config/blocks.json (defaults to the default entry).
• --dry-run simulates automation without invoking Cold Turkey or writing state.
• next prints the next scheduled actions (pass a number for how many entries).
• validate checks JSON structure, times, actions, and configured paths.
• status reports the last recorded action from state/status*.txt; if you changed the block inside Cold Turkey itself, run start/stop once to resync.

Optional alias

Print or install an alias (defaults to ct) for quicker access:

# Just print the alias line
./scripts/ct.sh alias

# Install into your shell profile
./scripts/ct.sh alias --install --rc ~/.bashrc
# Or choose a different alias name and shell
./scripts/ct.sh alias --install --name ctlite --rc ~/.zshrc

Reload your shell (or run source on the profile) after installation.

Multiple blocks

• Create one JSON file per profile under config/blocks/ (use the *.example.json files as a starting point).
• Register each block in config/blocks.json with a simple mapping from block id to file path.
• Invoke them with ./scripts/ct.sh --block <id-or-block_name> .... You can pass either the key from config/blocks.json or the block_name stored in the block file.
• State and log entries include the block name, and status/last-run files are stored per block.

Example files:

• config/blocks.json

  {
    "default": "focus-mode",
    "blocks": {
      "focus-mode": "blocks/focus-mode.json",
      "deep-work": "blocks/deep-work.json",
      "weekend-lite": "blocks/weekend-lite.json"
    }
  }

• config/blocks/focus-mode.json

  {
    "block_name": "Focus Mode",
    "ct_path": "/mnt/c/Program Files/Cold Turkey/Cold Turkey Blocker.exe",
    "schedules": [
      { "description": "Weekday deep work start", "action": "start", "time": "09:00", "days": ["Mon", "Tue", "Wed", "Thu", "Fri"] },
      { "description": "Lunch break", "action": "stop", "time": "12:30", "days": ["Mon", "Tue", "Wed", "Thu", "Fri"] },
      { "description": "Afternoon focus", "action": "start", "time": "13:30", "days": ["Mon", "Tue", "Wed", "Thu", "Fri"] },
      { "description": "Wrap up for the day", "action": "stop", "time": "18:00", "days": ["Mon", "Tue", "Wed", "Thu", "Fri"] }
    ]
  }

• config/blocks/deep-work.json

  {
    "block_name": "Deep Work",
    "schedules": [
      { "description": "Deep focus kickoff", "action": "start", "time": "06:30", "days": ["Tue", "Thu"] },
      { "description": "Deep focus pause", "action": "stop", "time": "11:00", "days": ["Tue", "Thu"] },
      { "description": "Deep focus reprise", "action": "start", "time": "14:00", "days": ["Tue", "Thu"] },
      { "description": "Deep focus close", "action": "stop", "time": "20:00", "days": ["Tue", "Thu"] }
    ]
  }

Add or modify block files as needed, then register them in config/blocks.json. The validate command checks every referenced block file.

Advanced Configuration

• Use CT_CONFIG=/path/to/config.json (or --config) to point at alternate configs without copying them into the repo.
• Point CT_LOG_FILE=/path/to/file.log to relocate logs. Directories are created automatically.
• Set CT_EXEC_PATH or COLD_TURKEY_PATH to override the detected Windows executable for all blocks; per-block ct_path entries can either be absolute Windows paths or WSL paths using ~/ or environment variables.
• ct_path values are resolved when the script runs, so snippets like "~/bin/Cold Turkey Blocker.exe" or "$HOME/apps/ct.exe" work once the path exists.
• --block always accepts the block id from config/blocks.json, but it also matches the block_name inside each block file for friendlier manual commands.

Scheduling Automation

Add a cron job inside WSL (runs every minute):

* * * * * /bin/bash /home/youruser/ct-script/scripts/ct.sh auto >/dev/null 2>&1

If you prefer Windows Task Scheduler, call wsl.exe with the same command. The script stores the last run timestamp in state/last-run.txt to replay missed actions after downtime.

Logs & Diagnostics

• Main log: logs/cold-turkey.log
• Last automation run: state/last-run.txt
• Last known block status: state/status.txt

Use tail -f logs/cold-turkey.log to monitor actions live. All log entries include timestamps, action types, and descriptions.

Troubleshooting

• Missing config error: copy config/blocks.example.json to config/blocks.json and add block files under config/blocks/.
• Executable not found: verify the ct_path setting in the config matches your installation.
• jq missing: install it via sudo apt-get install jq.
• Validation failures: run ./scripts/ct.sh validate to see which block or schedule needs attention.
• Status command says "unknown": no actions have been recorded yet; run start or auto (or use --dry-run to preview without changes).

Happy focus time!

License

Licensed under the MIT License.