{"slug": "hooke-run-agents-on-schedule-or-file-changes-with-just-one-file", "title": "Hooke – Run agents on schedule or file changes with just one file", "summary": "Hooke, a new agentic workflow automator from developer Aditya Azad, runs AI agent tasks on schedules or file changes through a single hooke.toml file, using a systemd daemon that hands each trigger to an agent session with the project's context and configured MCP servers. The tool requires Python 3.14+ and the pi agent (or supported alternatives such as claude and codex) on PATH, and supports per-automation fields including schedule intervals like \"6h\", file watch globs with a 2s debounce, an explicit mcp_servers allowlist, a 30m default timeout, and concurrency of 1 that drops overlapping triggers rather than queuing them. Deploying via `hooke deploy` is the only way the daemon's registry changes, and it validates the TOML, schema version and globs before accepting a configuration.", "body_md": "Agentic workflow automator: a systemd daemon that watches files and schedules periodic tasks, running each automation through your agent with its available MCP servers.\n\n## Table of contents\n\nEvery project accumulates chores that an agent could do if it just knew when to start: \"run the tests whenever `src/` changes\", \"summarize new notes every morning\", \"check dependencies daily\". Cron handles *when* but not *what* — it has no model, no tools, no context. Hooke gives you the cron half for free (systemd, already running) and hands each trigger to a real agent session with your project's context and your configured MCP servers.\n\nRequires Python 3.14+ and [pi](https://github.com/earendil-works/pi) or other supported agents on PATH.\n\n1. Install the CLI/daemon onto PATH\n\n```\nuv tool install /path/to/hooke        # or: uv tool install hooke (once published)\n```\n\n1. Install + start the systemd daemon (templated per user, starts at boot)\n\n```\nhooke install\nhooke install --user                  # user unit + loginctl enable-linger\n```\n\nCheck it's alive — you should see the version and a pid:\n\n``` bash\n$ systemctl status hooke@$USER\nbash\n$ hooke status\n```\n\nIn any project directory:\n\n```\ncd ~/code/my-webapp\nhooke init                # writes a commented hooke.toml\n```\n\nEdit `hooke.toml`:\n\n```\n[project]\nname = \"my-webapp\"                 # unique id, collisions rejected at deploy\nschema = 1\n\n[automation.deps-review]\nprompt = \"Check package manifests for outdated or vulnerable dependencies and summarize findings in DEPENDENCIES.md\"\nagent = \"pi\"                       # which agent runs this automation (default: pi)\nmodel = \"claude-opus-4-5\"          # optional per-automation model override\nmcp_servers = [\"papers\"]           # explicit allowlist — least privilege\nschedule = { every = \"6h\" }\nresume_on_restart = false\ncontinuity = true                  # reuse the persisted pi session between runs\n\n[automation.test-on-change]\nprompt = \"Source files changed. Run the test suite and fix any failures you introduced.\"\nwatch = { paths = [\"src/**\", \"tests/**\"], ignore = [\"**/.git/**\", \"**/node_modules/**\"], debounce = \"2s\" }\nresume_on_restart = true\n```\n\nPer-automation fields:\n\n| Field | Default | Meaning | \n|---|---|---|\n| `prompt` | required | The agent's task. Trigger context (changed files, resume note) is appended automatically. | \n| `agent` | `\"pi\"` | Which registered agent backend runs this automation (see `hooke.agents` ;`pi` ,`claude` ,`codex` ). | \n| `mcp_servers` | `[]` | MCP servers this automation may use; validated against the agent's own MCP config at deploy ( `~/.pi/agent/mcp.json` ,`~/.claude.json` , or`~/.codex/config.toml` ). | \n| `schedule` | — | `{ every = \"6h\" }` — durations like`90s` ,`5m` ,`6h` ,`1d` . | \n| `watch` | — | `{ paths = [...], ignore = [...], debounce = \"2s\" }` — globs relative to the project root. | \n| `resume_on_restart` | `false` | Re-run automatically after a daemon restart interrupted it. | \n| `continuity` | `false` | Persist the agent session and reuse it for later runs of this automation. | \n| `model` /`thinking` | agent defaults | Per-run overrides passed to the agent ( `thinking` : off…max). | \n| `timeout` | `30m` | Kill the agent process tree after this long. | \n| `concurrency` | `1` | Skip-if-running: overlapping triggers are dropped, never queued. | \n\nReady-made configurations live in [`examples/`](https://github.com/aditya-azad/hooke/blob/main/examples/README.md) — copy one in as `hooke.toml` and deploy.\n\n```\nhooke deploy              # in the project dir (or: hooke deploy ~/code/my-webapp)\nhooke status              # what's armed, next due times, recent runs\nhooke logs -n 20          # run history\nhooke logs --run <id>     # one run's full record + its pi event stream\nhooke disable my-webapp   # kept in the registry, inert\nhooke enable my-webapp\nhooke remove my-webapp    # gone from the registry\n```\n\n`deploy` is the only way the daemon's registry changes. It validates fully first — TOML, schema version, glob sanity, MCP server existence, project trust — so mistakes fail loudly now instead of silently at 3am. An identical redeploy is a no-op (\"up to date, nothing to do\"); a changed one swaps atomically without resetting unchanged automations' timers.\n\n```\njournalctl --user -u hooke -f              # --user install\nsudo journalctl -u hooke@$USER -f          # system install\n```\n\n- `hooke status` says \"cannot reach hooke daemon\" → the unit isn't running; check`systemctl status hooke@$USER` and the journal above.\n- A run shows `failed` → read its event stream:`hooke logs --run <id>` .\n- A run shows `timed_out` → raise`timeout` in`hooke.toml` and redeploy.\n- Config errors at deploy quote the exact `hooke.toml` problem; fix and redeploy.\n\n- **Bugs and questions:**[open an issue](https://github.com/aditya-azad/hooke/issues) — include your`hooke.toml` fragment, the daemon version, and the run's output from`hooke logs --run <id>` (redact anything private).\n\n-  Publish to PyPI (`uv tool install hooke` )\n- Boot-time catch-up scan of watched globs (currently fires only on the next change)\n-  `hooke run` — trigger an automation once, on demand\n-  Per-automation notification hooks (e.g. notify on `failed` /`timed_out` )\n\nPRs are welcome! See [CONTRIBUTING.md](https://github.com/aditya-azad/hooke/blob/main/CONTRIBUTING.md) for setup, the test/lint/type commands CI runs, and how to submit changes.\n\n```\nuv sync\nuv run pytest tests -q\nuv run ruff check src tests && uv run pyrefly check src tests\nuv run hooke daemon        # run the daemon in the foreground\n```\n\n", "url": "https://wpnews.pro/news/hooke-run-agents-on-schedule-or-file-changes-with-just-one-file", "canonical_source": "https://github.com/aditya-azad/hooke", "published_at": "2026-10-25 19:46:50+00:00", "updated_at": "2026-10-25 20:12:40.317490+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "agent-protocols", "developer-tools"], "entities": ["Hooke", "Aditya Azad", "pi", "systemd", "Claude", "Codex", "MCP"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/hooke-run-agents-on-schedule-or-file-changes-with-just-one-file", "markdown": "https://wpnews.pro/news/hooke-run-agents-on-schedule-or-file-changes-with-just-one-file.md", "text": "https://wpnews.pro/news/hooke-run-agents-on-schedule-or-file-changes-with-just-one-file.txt", "jsonld": "https://wpnews.pro/news/hooke-run-agents-on-schedule-or-file-changes-with-just-one-file.jsonld"}}