AgentGuard

AgentGuard is a local, read-only monitoring wrapper for AI coding agents. This first MVP launches Claude Code or Codex in the current terminal, observes the process tree while it runs, and stores session metadata and events in a local SQLite database.

It does not block activity, inject into the agent, send data to a server, or manufacture events that were not observed.

Build and install

Requirements: macOS, Go 1.21 or newer, and the agent executable (claude or codex) on PATH. macOS supplies the ps and lsof tools used by the collector.

go build -o agentguard ./cmd/agentguard
./agentguard --help

To install on your Go binary path:

go install ./cmd/agentguard

Usage

Run an agent in the foreground, with its normal terminal input and output:

agentguard run claude
agentguard run codex

Arguments after the agent name are passed through unchanged:

agentguard run claude --model sonnet

Review captured sessions:

agentguard sessions
agentguard inspect <session-id>

The database defaults to ~/Library/Application Support/AgentGuard/agentguard.db. Set AGENTGUARD_DB to use a different path. Logs go to stderr; the wrapped agent retains stdin/stdout/stderr.

What the macOS MVP captures

AgentGuard polls the operating system every 500 ms. For the launched root PID and descendants it records:

• Newly observed processes, parent PIDs, executable names, and command lines from ps.
• Open regular files and their observed read/write access mode from lsof.
• Open IPv4/IPv6 sockets and numeric endpoints from lsof.
• Files created, changed, or deleted under the launch working directory, by comparing filesystem metadata before and after the session.
• Session start/end timestamps, working directory, status, and exit code.

Process, file, and socket events are de-duplicated within a session. The SQLite schema keeps events separate from sessions so future policy, risk, streaming, and UI layers can consume the same event model. Platform code is behind monitor.Monitor; a future Linux or Windows collector can implement that interface.

Important macOS limitations

This build is honest best-effort monitoring, not a complete audit trail:

• Polling can miss processes, files, and connections that open and close between samples.
• lsof reports resources that are open at sample time. Its file access mode is not a record of individual read/write system calls, byte ranges, or contents.
• Workspace snapshot changes prove that a path changed during the session, but cannot reliably attribute that change to a particular PID. Changes made concurrently by another program can appear too.
• Snapshot change detection covers the current working directory only and intentionally skips .git and .agentguard directories. Open files observed by lsof can be anywhere the user may inspect.
• Network endpoints are numeric IP/port values when name resolution is unavailable or deliberately disabled. AgentGuard does not decrypt traffic or recover HTTP hostnames/SNI.
• macOS privacy controls and Unix permissions may hide resources. AgentGuard runs with the same privileges as the user and does not request root access.
• Shell built-ins do not create a child process, and command lines can be truncated or changed by a process. Secrets passed on command lines will be stored as observed.
• Descendants that daemonize and re-parent before a poll may be lost.

A substantially stronger macOS implementation would use Apple's Endpoint Security framework for exec, fork, open, and related authorization/notification events, plus Network Extension or other privileged facilities for network control. Endpoint Security clients require restricted Apple entitlements, code signing, user approval, and typically system-extension deployment; ordinary local Go binaries cannot legitimately obtain that visibility. DTrace/OpenBSM approaches likewise require elevated permissions and still have deployment or fidelity tradeoffs. This MVP therefore uses unprivileged system interfaces and clearly labels the result as sampled.

Development

go test ./...
go vet ./...

Main packages:

• internal/app: CLI orchestration and child lifecycle.
• internal/model: platform-neutral sessions and events.
• internal/store: SQLite persistence.
• internal/monitor: collector interface and macOS implementation.

Likely next steps are a richer event schema/versioning, Endpoint Security helper support, policies and blocking decisions, secret detection, risk scoring, MCP proxying, event streaming, and additional platform collectors.