Add initial TriggerMind project skeleton (CLI, scheduler, storage, models, tests)

.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+.Python
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDEs and editors
+.vscode/
+.idea/
+
+# OS artifacts
+.DS_Store
+
+# TriggerMind local runtime data
+*.log
+*.pid
+triggers.json
+
+# Coverage
+.coverage
+htmlcov/

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to TriggerMind
+
+Thanks for your interest in improving TriggerMind.
+
+## Development setup
+
+```bash
+git clone https://github.com/example/triggermind.git
+cd triggermind
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install pytest
+```
+
+## Running checks
+
+```bash
+pytest
+```
+
+## Contribution guidelines
+
+- Keep changes local-first and privacy-preserving.
+- Prefer clear abstractions over framework-heavy design.
+- Add tests for any behavior change.
+- Keep CLI output concise and friendly.
+- Update documentation for user-facing changes.
+
+## Pull requests
+
+- Use descriptive commit messages.
+- Explain user impact and architectural impact.
+- Include command output for tests you ran.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TriggerMind Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,9 +1,132 @@
 # TriggerMind
 
-TriggerMind is a local-first conditional AI agent CLI designed for bounded autonomy.
+**A local-first, trigger-based AI agent CLI for bounded autonomy.**
 
-Unlike always-on agents that constantly consume tokens, monitor systems, or take actions without clear limits, TriggerMind stays dormant by default. It activates only when a user-defined trigger condition is met.
+TriggerMind stays dormant by default and only intervenes when a user-defined condition is met.
 
-The open-source MVP focuses on a simple but highly practical use case: timer-based intervention. Users can start a timer from the command line, let TriggerMind run quietly in the background, and receive a reminder or AI-driven prompt only when the condition is triggered.
+## One-line install (copy/paste)
 
-This repository is designed to evolve from a minimal timer utility into a broader trigger-based agent framework, supporting future trigger types such as calendar events, focus-loss detection, behavioral signals, and physiological inputs.
+> `triggermind` is not published on PyPI yet. Use source install for now.
+
+### If you already cloned this repo
+
+#### macOS + Linux
+
+```bash
+python3 -m pip install --user -U .
+```
+
+#### Windows PowerShell
+
+```powershell
+py -m pip install --user -U .
+```
+
+If `py` is unavailable on Windows, use:
+
+```powershell
+python -m pip install --user -U .
+```
+
+### Fresh machine (clone + install)
+
+#### macOS + Linux
+
+```bash
+git clone https://github.com/<YOUR_ORG>/triggermind.git && cd triggermind && python3 -m pip install --user -U .
+```
+
+#### Windows PowerShell
+
+```powershell
+git clone https://github.com/<YOUR_ORG>/triggermind.git; cd triggermind; py -m pip install --user -U .
+```
+
+After install, run:
+
+```bash
+triggermind
+```
+
+No coding needed: TriggerMind launches an interactive guide and asks what reminder you want.
+
+---
+
+## Quick examples
+
+```bash
+triggermind start 25m --message "Go back to writing"
+triggermind at 15:00 --message "Review the grant draft"
+triggermind list
+triggermind cancel <id>
+triggermind doctor
+triggermind update
+```
+
+---
+
+## Why conditional AI agents matter
+
+Most agent tooling is always-on and noisy. TriggerMind is different:
+
+- **Dormant by default**
+- **Activated only by explicit conditions**
+- **Local-first** (no cloud required)
+- **Human-controlled bounded autonomy**
+
+This reduces unnecessary token usage, risk, and intrusion.
+
+---
+
+## Features (MVP)
+
+- Human-friendly time parsing (`25m`, `2h`, `1h30m`)
+- Absolute-time triggers (`HH:MM` local time)
+- Friendly interactive setup mode (`triggermind` with no args)
+- Local JSON state persistence
+- Lightweight background scheduler daemon
+- Desktop notifications (macOS/Linux) + terminal fallback
+- Clean extension points for future trigger types
+
+---
+
+## Architecture overview
+
+```text
+CLI (Typer)
+  ├─ triggers/      # trigger parsing + factory abstractions
+  ├─ storage/       # local persistence (JSON)
+  ├─ scheduler/     # background polling daemon
+  └─ notifications/ # OS notifications + terminal intervention
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.
+
+---
+
+## Roadmap
+
+1. SQLite backend + crash-safe scheduling
+2. Plugin trigger registry for calendar/focus/behavior signals
+3. Optional local LLM intervention templates
+
+---
+
+## Open-source metadata suggestions
+
+- **Short repo description:**
+  `Local-first CLI for bounded-autonomy AI agents that wake only on user-defined triggers.`
+- **GitHub topics/tags:**
+  - `ai-agents`
+  - `developer-tools`
+  - `productivity`
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

docs/ARCHITECTURE.md

@@ -0,0 +1,33 @@
+# TriggerMind Architecture
+
+TriggerMind is designed around one principle: **bounded autonomy**. The agent remains dormant and only acts when explicit trigger conditions are true.
+
+## High-level modules
+
+- `triggermind/main.py`: Typer CLI entrypoint and UX.
+- `triggermind/triggers/`: Trigger factories and future trigger stubs.
+- `triggermind/storage/`: Local persistence (JSON for MVP).
+- `triggermind/scheduler/`: Lightweight background daemon.
+- `triggermind/notifications/`: OS notification adapters and terminal intervention output.
+
+## Trigger lifecycle
+
+1. User creates a trigger with `start` or `at`.
+2. CLI parses/validates user input.
+3. Trigger is serialized to local state (`triggers.json`).
+4. Background daemon checks pending triggers every second.
+5. When due, trigger status changes to `fired` and notification is emitted.
+
+## Why this architecture scales
+
+- Trigger creation is abstracted behind `TriggerFactory`.
+- Storage backend is replaceable (JSON now, SQLite later).
+- Scheduler and notification concerns are separated.
+- Future trigger types can be added without changing core CLI behavior.
+
+## Cross-platform strategy
+
+- macOS: `osascript`
+- Linux: `notify-send` when available
+- Fallback: rich terminal intervention output
+- Windows support can be added by implementing a notification adapter and service runner.

pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "triggermind"
+version = "0.1.0"
+description = "Local-first, trigger-based AI agent CLI with bounded autonomy."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+  {name = "TriggerMind Contributors"}
+]
+keywords = ["ai-agent", "cli", "productivity", "local-first", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Environment :: Console",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS"
+]
+dependencies = [
+  "typer>=0.12.3"
+]
+
+[project.urls]
+Homepage = "https://github.com/example/triggermind"
+Repository = "https://github.com/example/triggermind"
+Issues = "https://github.com/example/triggermind/issues"
+
+[project.scripts]
+triggermind = "triggermind.main:run"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["triggermind"]

scripts/install.ps1

@@ -0,0 +1,24 @@
+$ErrorActionPreference = "Stop"
+
+if (Test-Path "pyproject.toml") {
+    $PkgSpec = "."
+} elseif ($env:TRIGGERMIND_GIT_URL) {
+    $PkgSpec = "git+" + $env:TRIGGERMIND_GIT_URL
+} else {
+    Write-Host "[TriggerMind] Not in repo root and TRIGGERMIND_GIT_URL is not set."
+    Write-Host "[TriggerMind] Clone the repo first, then run: py -m pip install --user -U ."
+    exit 1
+}
+
+if (Get-Command py -ErrorAction SilentlyContinue) {
+    Write-Host "[TriggerMind] Installing with pip (py launcher)..."
+    py -m pip install --user -U $PkgSpec
+} elseif (Get-Command python -ErrorAction SilentlyContinue) {
+    Write-Host "[TriggerMind] Installing with pip (python)..."
+    python -m pip install --user -U $PkgSpec
+} else {
+    Write-Host "[TriggerMind] Python 3.10+ is required."
+    exit 1
+}
+
+Write-Host "[TriggerMind] Installed. Run: triggermind"

scripts/install.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -f "pyproject.toml" ]]; then
+  PKG_SPEC="."
+elif [[ -n "${TRIGGERMIND_GIT_URL:-}" ]]; then
+  PKG_SPEC="git+${TRIGGERMIND_GIT_URL}"
+else
+  echo "[TriggerMind] Not in repo root and TRIGGERMIND_GIT_URL is not set."
+  echo "[TriggerMind] Clone the repo first, then run: python3 -m pip install --user -U ."
+  exit 1
+fi
+
+if command -v python3 >/dev/null 2>&1; then
+  echo "[TriggerMind] Installing with pip..."
+  python3 -m pip install --user -U "$PKG_SPEC"
+else
+  echo "[TriggerMind] Python 3 is required. Please install Python 3.10+ first."
+  exit 1
+fi
+
+echo "[TriggerMind] Installed. Run: triggermind"