What is agent-process-guard?

This repository is a small utility designed for AI coding agents, specifically Codex and Claude Code. Its purpose is to prevent a common problem that arises when an AI agent runs terminal commands during coding tasks: some commands run for a long time or never finish on their own (like starting a local development server), and if the agent does not handle these correctly, it can get stuck waiting forever or leave stray processes running in the background after the task ends. The tool works by classifying every command before running it. Commands that finish quickly are run through a wrapper that enforces a time limit, so the agent is never left waiting indefinitely. Commands that are meant to run continuously, like a web server or a file watcher, are started as managed background processes. The tool tracks each process with a file recording its process ID, writes logs, and stores metadata in a folder called .agent-run. When the agent is done, it can stop these background processes cleanly, including any child processes they spawned. For long-running processes like servers, the tool can check whether the process is actually ready by testing a web address, probing a network port, running a custom check command, or looking for a specific message in the log. This avoids the agent proceeding before the server is up. Installation is handled by a shell script or a PowerShell script on Windows. You can install it at the user level so it is available across all projects, or at the repository level so it only applies to one project. The tool works the same way with both Codex and Claude Code. The README is available in Traditional Chinese, Simplified Chinese, Japanese, and Korean in addition to English. The project is released under the MIT license.