{
  "markdown": "# TinMan — Heartbeat for Claude Code\n\n[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/License-GPLv3-green.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-orange.svg)](https://claude.ai/code)\n\n> *\"If I only had a heart…\"*\n> The Tin Man wanted a heart. Now Claude Code has one.\n\n**TinMan** adds a proactive heartbeat to your [Claude Code](https://claude.ai/code) setup. Instead of waiting for you to ask, Claude runs a scheduled health check and tells you when something needs attention — disk space, uncommitted code, stale branches, failed tool calls, whatever you care about.\n\nZero external dependencies. Works on macOS and Linux. Takes 2 minutes to set up.\n\n<!-- TODO: Add demo GIF here showing tinman init + a heartbeat notification -->\n\n---\n\n## Why I Built This\n\nI'm a PM who spends all day in Claude Code. I kept forgetting to check things: uncommitted work piling up, tests I meant to run, branches I never cleaned up.\n\nOpenClaw has a built-in heartbeat feature where the agent proactively checks in. Claude Code doesn't — it waits for you to ask.\n\nSo I built TinMan. It's the simplest thing that could work: a scheduler that runs your checklist through Claude on a timer and tells you what needs attention. No servers, no Docker, no accounts to create. Just Claude plus a scheduler.\n\nThe philosophy is **notify, don't act**. Claude tells you what's wrong. You decide what to do about it. That's the \"sane\" default. If you trust Claude to fix things autonomously, there's a \"chaos\" mode — but you have to opt in.\n\n---\n\n## Install\n\n**One-liner:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/andyuninvited/tinman_for_claudecode/main/install.sh | bash\n```\n\n**Or pip:**\n```bash\npip install tinman-for-claudecode\n```\n\n**Requirements:**\n- Python 3.9+\n- [Claude Code](https://claude.ai/code) (`claude` CLI in your PATH)\n- macOS or Linux\n\n**Verify installation:**\n```bash\ntinman --version\nwhich tinman\nclaude --version  # Make sure Claude Code is also installed\n```\n\n---\n\n## Quick start\n\n```bash\ntinman init        # interactive setup (choose preset, set interval, install scheduler)\n```\n\nThat's it. TinMan will:\n- Create a `HEARTBEAT.md` checklist in your project (edit it to customize)\n- Install a background scheduler (launchd on macOS, cron on Linux)\n- Run the first heartbeat immediately\n\n**Test that it's working:**\n```bash\ntinman status      # See scheduler status and last heartbeat result\ntinman logs        # View recent heartbeat history\n```\n\n---\n\n## Commands\n\n```\ntinman init                   Interactive first-time setup\ntinman run --once             Run one heartbeat right now\ntinman run --loop             Run continuously (foreground)\ntinman install                Install as background scheduler\ntinman install --preset paranoid\ntinman uninstall              Remove scheduler\ntinman status                 Show scheduler + recent results\ntinman logs                   Print recent heartbeat log\ntinman logs --n 50            Print last 50 entries\n```\n\n---\n\n## Security presets\n\nTinMan ships with three modes. Pick the one that matches your comfort level.\n\n| Preset | Interval | Mode | Use when |\n|--------|----------|------|----------|\n| `sane` | 30 min | notify-only | **default** — Claude tells, never acts |\n| `paranoid` | 15 min | notify-only | Extra visibility, max logging |\n| `chaos` | 5 min | active | You trust Claude to take action |\n\n```bash\ntinman install --preset sane       # recommended for most people\ntinman install --preset paranoid   # tighter, more frequent\ntinman install --preset chaos      # Claude can act autonomously ⚠️\n```\n\n> **Note:** The default `sane` preset matches the OpenClaw pattern of `showOk: false, showAlerts: true`. TinMan is `notify-only` by default.\n\n---\n\n## Customize your HEARTBEAT.md\n\nTinMan creates a default `HEARTBEAT.md` when you run `tinman init`. Edit it to make the heartbeat yours:\n\n```markdown\n# My Project Heartbeat\n\nEvery heartbeat, check:\n1. Any failing tests? (run pytest --co -q and report)\n2. Uncommitted changes older than 24h?\n3. Any TODO comments I added recently?\n4. Disk space on my main volume?\n\nIf nothing needs attention: reply HEARTBEAT_OK\nIf something needs attention: 1-3 bullets + recommended action\nNever take irreversible steps without asking me first.\n```\n\n**Hard rules baked into every run (cannot be overridden from HEARTBEAT.md):**\n- No destructive commands (rm, drop, delete)\n- No secret exfiltration\n- No git commits/pushes without confirmation\n- No software installs without confirmation\n\nWant more templates? Check out [heartbeat-templates](https://github.com/andyuninvited/heartbeat-templates) for ready-to-use checklists.\n\n---\n\n## Configuration\n\nTinMan looks for config at `./tinman.json` then `~/.tinman/config.json`.\n\n```json\n{\n  \"preset\": \"sane\",\n  \"interval_minutes\": 30,\n  \"notify_only\": true,\n  \"heartbeat_md\": \"HEARTBEAT.md\",\n  \"log_file\": \"~/.tinman/heartbeat.log\",\n  \"notify_c3poh\": false,\n  \"c3poh_endpoint\": \"\"\n}\n```\n\n**Environment variable overrides** (useful for CI/containers):\n```bash\nTINMAN_INTERVAL_MINUTES=15\nTINMAN_NOTIFY_ONLY=true\nTINMAN_HEARTBEAT_MD=/path/to/HEARTBEAT.md\nTINMAN_C3POH_ENDPOINT=http://localhost:7734/notify\n```\n\n---\n\n## C3Poh integration\n\nWant TinMan to send heartbeat alerts to your **Telegram** (or Slack/Discord)? Pair it with [C3Poh](https://github.com/andyuninvited/c3poh_for_claudecode):\n\n```json\n{\n  \"notify_c3poh\": true,\n  \"c3poh_endpoint\": \"http://localhost:7734/notify\"\n}\n```\n\nTinMan → C3Poh → your phone. Done.\n\n**The full stack:**\n```\n[launchd/cron] → TinMan heartbeat\n                      ↓\n              Claude Code analysis\n                      ↓\n              C3Poh notification\n                      ↓\n              Your phone (Telegram)\n```\n\n---\n\n## How it works\n\n```\n[launchd/cron] every N minutes\n      ↓\n[tinman run --once]\n      ↓\nreads HEARTBEAT.md\n      ↓\nclaude --print \"[safety prefix]\\n\\n[checklist]\"\n      ↓\ncaptures output\n      ↓\nlogs result to ~/.tinman/heartbeat.log\n      ↓\nprints to stdout (+ C3Poh if configured)\n```\n\nNo daemons. No servers. No Docker. Just Claude + a scheduler.\n\n---\n\n## Why not just use a cron job with a raw prompt?\n\nYou could! TinMan adds:\n- **Safety rails** — enforced prefix that prevents risky actions in notify-only mode\n- **Preset system** — sane/paranoid/chaos in one flag, not manual config editing\n- **Log rotation** — keeps log files sane\n- **C3Poh integration** — forwards alerts to messaging\n- **Status command** — `tinman status` shows you exactly what's running and last N results\n- **Empty HEARTBEAT.md detection** — avoids wasted API calls\n\n---\n\n## Run tests\n\n```bash\npip install tinman-for-claudecode[dev]\npytest tests/ -v\n```\n\n---\n\n## Roadmap\n\n- [ ] v0.2: Web dashboard (local-only) to view heartbeat history\n- [ ] v0.2: Slack and Discord output (via C3Poh)\n- [ ] v0.3: Per-project heartbeat config (`.tinman.json` in project root)\n- [ ] v0.3: GitHub Actions heartbeat mode\n- [ ] v1.0: Windows support\n\n---\n\n## Related\n\n- [C3Poh](https://github.com/andyuninvited/c3poh_for_claudecode) — Telegram/Slack/Discord bridge for Claude Code (the comms to TinMan's heart)\n- [Heartbeat Templates](https://github.com/andyuninvited/heartbeat-templates) — Ready-to-use HEARTBEAT.md files for different workflows\n- [Agent Blueprints](https://github.com/andyuninvited/agent-blueprints) — Starter templates for building AI agents\n- [Claude Code](https://claude.ai/code) — the agentic CLI this is built for\n\n---\n\n## License\n\nGNU GPLv3 — copy-left, and let's evolve together.\n\nSee [LICENSE](LICENSE) for the full text.\n\n---\n\n*Built by [@andyuninvited](https://github.com/andyuninvited). Star the repo if TinMan saved you from a bad day.*\n",
  "bytes": 7756,
  "sha": "659d4aa28ef2a5aa108571fd97a04a1cda8dfc42fdeb90380cec835f364895a7",
  "repo_slug": "andyuninvited/tinman_for_claudecode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_andyuninvited_tinman_for_claudecode_tinm_3198fa92/readme"
}