{"id":49504331,"url":"https://github.com/samahn0601/hermes-doctor","last_synced_at":"2026-05-01T14:02:17.867Z","repository":{"id":354897040,"uuid":"1225866640","full_name":"samahn0601/hermes-doctor","owner":"samahn0601","description":"Read-only health-check CLI for long-running personal AI agents","archived":false,"fork":false,"pushed_at":"2026-04-30T19:29:43.000Z","size":2117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T20:18:56.947Z","etag":null,"topics":["ai-agent","cli","health-check","hermes","observability","personal-agent","python","read-only"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samahn0601.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T18:15:54.000Z","updated_at":"2026-04-30T19:29:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samahn0601/hermes-doctor","commit_stats":null,"previous_names":["samahn0601/hermes-doctor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/samahn0601/hermes-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samahn0601%2Fhermes-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samahn0601%2Fhermes-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samahn0601%2Fhermes-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samahn0601%2Fhermes-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samahn0601","download_url":"https://codeload.github.com/samahn0601/hermes-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samahn0601%2Fhermes-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32499691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","cli","health-check","hermes","observability","personal-agent","python","read-only"],"created_at":"2026-05-01T14:02:16.476Z","updated_at":"2026-05-01T14:02:17.855Z","avatar_url":"https://github.com/samahn0601.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes Doctor\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"banner.jpg\" alt=\"Hermes Doctor — Health Check CLI for Personal AI Agents\" width=\"880\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/hermes-doctor/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/hermes-doctor.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/hermes-doctor/\"\u003e\u003cimg alt=\"Python versions\" src=\"https://img.shields.io/pypi/pyversions/hermes-doctor.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samahn0601/hermes-doctor/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/pypi/l/hermes-doctor.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samahn0601/hermes-doctor/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/samahn0601/hermes-doctor/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **Linters check your code. Hermes Doctor checks your agent's mind.**\n\nA local, read-only annual physical for a long-lived personal [Hermes Agent](https://hermes-agent.nousresearch.com/) installation.\n\nHermes Doctor scans bloated memories, stale skills, reminder/cron drift, oversized sessions, broken local Markdown links, and runtime warnings — **without modifying anything**.\n\nHermes gets better as it remembers. But long-lived personal agents also accumulate entropy.\n\nIt started as a family physician's tool for treating a different kind of patient: my personal AI agent. Designed by someone who thinks in preventive checkups, not emergency surgery.\n\n\u003e Early public preview. Useful, small, and intentionally conservative.\n\n## Non-goals\n\nHermes Doctor is deliberately small. The following are **not** going to happen:\n\n- ❌ No `--fix` mode, ever. The doctor writes the prescription; you go to the pharmacy.\n- ❌ No cloud service, dashboard, or telemetry. Reports are local-only.\n- ❌ No automatic memory deduplication, skill rewriting, or cron reconciliation.\n- ❌ No support for other agent frameworks (AutoGPT, LangChain, etc.) until Hermes itself is stable.\n- ❌ No generic Markdown linting — there are better tools for that.\n- ❌ No runtime dependencies in the core scanner. Stdlib only.\n\n## Who is this for?\n\nHermes Doctor is for people who run Hermes Agent as a long-lived personal agent and want to know when local state is getting messy:\n\n- people using Hermes memories and skills heavily\n- people relying on reminder / cron automation\n- people keeping Markdown-based personal state around an agent\n- people who want safe diagnosis before cleanup\n- people interested in personal agent observability and hygiene\n\n## What it checks\n\n- Markdown bloat and broken local links\n- Memory / skill size, duplication, and mutable project-fact candidates\n- `REMINDERS.md` vs `hermes cron list` consistency\n- Session file size\n- Recent runtime / gateway warning and error event counts\n- Domain scores and overall health score\n\n## Safety model\n\nHermes Doctor v1 is observational and read-only.\n\nIt does **not**:\n\n- edit files\n- delete files\n- deduplicate memories or skills\n- reconcile reminders\n- modify cron jobs\n- scan external project folders unless explicitly requested\n- send your local data anywhere\n\nReports redact paths, secret-like strings, and identifier-like strings on a best-effort basis. Do not publish reports from real personal deployments without reviewing them first.\n\n## Privacy\n\n- No telemetry.\n- No network calls, except local execution of installed `hermes` CLI commands.\n- Reports are generated locally.\n- Raw Hermes command output is excluded by default.\n- `--debug-raw` is for local debugging only and should not be used for public reports.\n- Redaction is best-effort, not a formal secret-scanning guarantee.\n\n## Install\n\nRecommended (zero-install, ephemeral):\n\n```bash\npipx run hermes-doctor --summary\n```\n\nPersistent install:\n\n```bash\npipx install hermes-doctor\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/samahn0601/hermes-doctor.git\ncd hermes-doctor\npython -m pip install -e .\n```\n\n\n## Usage\n\n```bash\n# Full Markdown report\nhermes-doctor\n\n# Compact output for cron/watchdogs\nhermes-doctor --summary\n\n# Safe JSON output\nhermes-doctor --json\n\n# Write timestamped report and refresh \u003cHERMES_HOME\u003e/reports/health/latest.md\nhermes-doctor --write-report\n\n# Automation gate: exit 2 on critical findings\nhermes-doctor --summary --fail-on critical\n```\n\nBy default, Hermes Doctor scans only the Hermes home directory:\n\n```bash\nhermes-doctor --hermes-home ~/.hermes\n```\n\nExternal Markdown paths are opt-in:\n\n```bash\nhermes-doctor --include ./my-notes\nhermes-doctor --include-project-hub\n```\n\nRaw Hermes command output is excluded by default. For local debugging only:\n\n```bash\nhermes-doctor --json --debug-raw\n```\n\n## Example summary\n\n```text\nHermes Health: 100/100 (healthy)\nFindings: critical=0 warning=0 info=3\nDomains: markdown=100, memory_skills=100, reminder_cron=100, session_context=100, runtime_gateway=100\nReminder/Cron: ids=['r_0001']\nRuntime: errors=0 warnings=0\nActionable: none\n```\n\n## Example finding\n\n```text\nActionable:\n- [HD-MEM-002 warning] Memory/skill size warning: \u003cHERMES_HOME\u003e/memories/notes.md size=84KB\n- [HD-RMD-005 critical] Active reminder missing cron job: r_0007\n```\n\nEach finding carries a **stable ID** (`HD-MD-…`, `HD-MEM-…`, `HD-RMD-…`,\n`HD-SES-…`, `HD-RT-…`) — safe to grep for, pin in CI, and reference in\nissues. The complete list lives in `FINDING_IDS` in\n[`src/hermes_doctor/cli.py`](src/hermes_doctor/cli.py).\n\nHermes Doctor does not fix these automatically. It tells you what to inspect before you change state.\n\n## Scoring model\n\nHermes Doctor uses heuristic domain scores, not a formal proof of system health.\n\n- warning findings apply a small penalty\n- critical findings apply a larger penalty\n- the weakest domain is weighted heavily so one bad subsystem is not hidden by a good average\n- info findings do not reduce the score\n\nTreat the score as a screening result, not a diagnosis carved in stone.\n\n## Limitations\n\n- Hermes Doctor is heuristic and may produce false positives or false negatives.\n- Hermes CLI output formats may change over time.\n- Redaction is best-effort; review real reports manually before sharing.\n- v1 is intentionally conservative and does not repair state.\n- This is not an official Hermes Agent project.\n\n## Development\n\n```bash\npython -m pip install -e .[dev]\npython -m pytest\npython -m ruff check .\n```\n\n## Roadmap\n\n- **v0.1** — read-only scanner *(current)*\n- **v0.2** — golden fixture corpus + adversarial redaction tests + stable finding IDs (`HD-MEM-001`, `HD-CRON-002`) + analyzer status reporting + PyPI publication\n- **v0.3** — dry-run \"review candidates\" suggestions, conditional on v0.2 trust. Never executable scripts. Still no silent mutation.\n- **v1.0+** — boring, trusted, intentionally feature-frozen. Wins by credibility and restraint, not feature volume.\n\n## Reporting issues safely\n\nBefore opening an issue, please read **[SECURITY.md](SECURITY.md)** — it\nexplains what redaction is and is not guaranteed, and how to share a\nreport without leaking secrets.\n\nFor private vulnerability reports (e.g. suspected redaction leak), open a\n[GitHub security advisory](https://github.com/samahn0601/hermes-doctor/security/advisories/new) instead of a public issue.\n\n## Contributing\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)**. The project is intentionally\nnarrow — please skim the [Non-goals](#non-goals) section first.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamahn0601%2Fhermes-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamahn0601%2Fhermes-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamahn0601%2Fhermes-doctor/lists"}