Skip to main content

Agent Install Monitor

MIT License Python 3.9+ Hermes Plugin Local First

Track everything your AI agent installs on your machine.

Agent Install Monitor records package installs, Docker images, Git repositories, services, and other environment changes made by Hermes Agent.

  • Works with Hermes
  • Planned: Claude Code, OpenClaw, and more
  • Local-first: nothing leaves your machine
$ agent-monitor history

Session sess-8f3a21 [hermes]
Packages
  1. pip      playwright
  2. pip      openai

Time: 2m 13s   Commands: 2

Why?

AI coding agents frequently install packages, pull Docker images, clone repositories, and start services on your behalf. A few weeks later it's easy to lose track:

  • Why is Playwright installed?
  • Where did this Docker image come from?
  • Which repository did the agent clone?
  • What changed during that task?

Agent Install Monitor keeps a local history of everything your AI agent installed, so you can always answer those questions.

It's an observability tool, not a control layer It does not modify execution, uninstall packages, or perform rollback.

Installation

Run the installer. It finds Hermes's own venv, installs into it (not your shell's Python, which wouldn't be discoverable as a plugin), enables the plugin, and offers to put agent-monitor on your $PATH. Safe to re-run.

It installs from PyPI, and falls back to the same version from the GitHub release if PyPI isn't available. To pick one, add --source pypi or --source github (for example ... | python3 - --source github).

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/swytchcodehq/agent-install-monitor/main/install.py | python3

Windows (PowerShell)

irm https://raw.githubusercontent.com/swytchcodehq/agent-install-monitor/main/install.py | python -
Manual install (if you'd rather not pipe a script into your shell)

Install into the same Python environment hermes runs in, not your system/shell Python - that's what makes it discoverable as a plugin.

# find hermes's project root - the venv lives at <that path>/venv
hermes --version        # look for the "Project:" or "Install directory:" line
                         # (the label has changed across Hermes versions)

# install into that venv's pip (not your shell's pip), from PyPI:
/path/from/above/venv/bin/pip install agent-install-monitor

# or from GitHub (replace 0.1.2 with the latest release):
/path/from/above/venv/bin/pip install https://github.com/swytchcodehq/agent-install-monitor/archive/refs/tags/v0.1.2.tar.gz

which hermes usually points at a wrapper script (from the standard installer), not a symlink - readlink -f won't resolve it to the venv, so use hermes --version's output instead.

Enable the plugin:

hermes plugins enable agent-monitor

If your Hermes CLI is older and hermes plugins enable doesn't recognize agent-monitor ("plugin not found"), add it to ~/.hermes/config.yaml by hand:

plugins:
  enabled:
    - agent-monitor

Optional - put the CLI on your $PATH:

export PATH="/path/from/above/venv/bin:$PATH"

Usage

Just use Hermes normally. Afterwards, in a regular terminal:

agent-monitor history          # most recent session
agent-monitor sessions         # list all recorded sessions
agent-monitor session <id>     # a specific session
agent-monitor export [--session ID] [--format json|csv]

Data lives in $HERMES_HOME/agent-monitor/monitor.db (default ~/.hermes/agent-monitor/monitor.db). Nothing leaves your machine. On macOS and Linux the folder and database can only be opened by your own account. Tokens in a command (an install URL with credentials, TOKEN=..., --password ...) are replaced with *** before it's saved.

Supported Installations

Category Commands
Package managers npm, pnpm, yarn, pip, uv, poetry, cargo, go, brew, apt, dnf, apk, gem, composer, dotnet, nuget, choco, winget, scoop
Containers docker/podman pull, docker/podman run, docker compose up
Git git clone, git submodule add/update
Runtimes npx, uvx, cargo run, go run
Services systemctl start, brew services start, service start
Databases createdb, CREATE DATABASE (creation only)
Installer downloads curl/wget fetching .sh/.exe/.pkg/.dmg/.deb/.rpm/.appimage/.msi

Detection is a best-effort command-string match, not a security boundary.

Development

pip install -e ".[dev]"
pytest

Releasing

Bump the version in your PR:

python3 scripts/bump_version.py patch   # or minor, major

This updates pyproject.toml, __version__ and the installer's VERSION together. When the PR is merged, release-on-merge.yml tags the new version and starts release.yml, which runs the tests, publishes to PyPI and creates the GitHub release with the built files. A merge that doesn't change the version releases nothing. To retry a release, run release.yml by hand on the tag.

Metadata

Release files for agent-install-monitor 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-install-monitor 0.1.2
File Size Uploaded Provenance Actions
agent_install_monitor-0.1.2.tar.gz 22.4 kB With provenance Details for agent_install_monitor-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-install-monitor 0.1.2
File Interpreter ABI Platform Actions
agent_install_monitor-0.1.2-py3-none-any.whl Python 3 none any Details for agent_install_monitor-0.1.2-py3-none-any.whl

Total release size: 38.7 kB

Release files / agent_install_monitor-0.1.2.tar.gz

Download URL agent_install_monitor-0.1.2.tar.gz
Size 22.4 kB
Tags Source
SHA-256 checksum
How to use checksums
37d4b60527388869c00099c4804691069c3c34b0119fc6b3a019e21aa6f5cb70
BLAKE2b-256 checksum
How to use checksums
1775cb43eb7ce484094f9812f5c39c9236c20160a19a2ba21fcce466773fb5f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / agent_install_monitor-0.1.2-py3-none-any.whl

Download URL agent_install_monitor-0.1.2-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
523e0ce854355c6107d76c1f9b50a0103bc35ed5739e937a3621356b76475dbd
BLAKE2b-256 checksum
How to use checksums
7d1b086b2615c1e81c55ef4347737715f1ac43bb7b8c65d9114a3b29547188f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for agent-install-monitor 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_install_monitor-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page