Metadata-Version: 2.4
Name: loopguardian
Version: 0.1.1
Summary: Real-time AI coding agent loop detector for Claude Code
Home-page: https://github.com/loopguard/loopguard
Author: LoopGuard Team
Author-email: LoopGuard Team <team@loopguard.dev>
Maintainer: LoopGuard Team
Maintainer-email: LoopGuard Team <team@loopguard.dev>
License: MIT License
        
        Copyright (c) 2026 LoopGuard Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense,
        and/or sell copies of the Software, and to permit persons to whom the
        Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/loopguard/loopguard
Project-URL: Documentation, https://loopguard.readthedocs.io/
Project-URL: Repository, https://github.com/loopguard/loopguard
Project-URL: Bug Tracker, https://github.com/loopguard/loopguard/issues
Project-URL: Changelog, https://github.com/loopguard/loopguard/blob/main/CHANGELOG.md
Keywords: claude,code,monitoring,loop,detection,debugging,ai,assistant
Platform: MacOS X
Platform: Linux
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog<4.0.0,>=3.0.0
Requires-Dist: psutil<6.0.0,>=5.9.0
Requires-Dist: click<9.0.0,>=8.0.0
Requires-Dist: jsonschema<5.0.0,>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings>=0.23.0; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: platform
Dynamic: requires-python

# LoopGuard

Real-time AI coding agent loop detector for Claude Code that prevents wasted tokens and costs by alerting you when agents get stuck in repetitive loops.

## The Problem

AI coding agents get stuck in repetitive loops — editing the same file over and over, hitting the same error repeatedly, hallucinating tool calls — burning your token quota and costing real money before you even notice.

LoopGuard monitors your Claude Code sessions in real-time and sends desktop notifications when it detects the agent is looping.

## Features

- **Real-time Monitoring**: Background service that auto-detects Claude Code sessions
- **Loop Detection**: Identifies three types of loops:
  - Repeated identical tool calls (same tool + parameters)
  - Repeated identical error messages  
  - No meaningful file changes during activity
- **Desktop Alerts**: Native macOS notifications with actionable information
- **Configurable Thresholds**: Customize detection sensitivity per project
- **Zero Friction**: Install once, runs automatically on login

## Quick Start

### Installation

```bash
pip install loopguardian
```

### Dependencies

```bash
# Install terminal-notifier for desktop notifications
brew install terminal-notifier
```

### Usage

```bash
# Start LoopGuard service
loopguardian start

# Check status
loopguardian status

# Test notifications
loopguardian test
```

## Configuration

Create a `loopguardian.config.json` file in your project root or `~/.loopguardian/config.json`:

```json
{
  "detection": {
    "tool_call_repeats": 3,
    "error_repeats": 2,
    "stagnation_minutes": 5
  },
  "notifications": {
    "enabled": true,
    "throttle_seconds": 30
  }
}
```

### Detection Settings

- **tool_call_repeats**: Number of identical tool calls before alerting (default: 3)
- **error_repeats**: Number of identical errors before alerting (default: 2)  
- **stagnation_minutes**: Minutes of activity without file changes before alerting (default: 5)

### Notification Settings

- **enabled**: Enable/disable desktop notifications (default: true)
- **throttle_seconds**: Minimum seconds between identical alerts (default: 30)

## How It Works

1. **Process Detection**: LoopGuard monitors for Claude Code processes starting up
2. **Log Monitoring**: When Claude Code is detected, LoopGuard starts watching the session log files
3. **Pattern Analysis**: Real-time analysis detects loop patterns using configurable thresholds
4. **Desktop Alerts**: Immediate notifications when loops are detected with suggested actions

## Example Alerts

```
🚨 LOOP DETECTED: Tool 'str_replace' repeated 3 times on auth.py.
   Session: a1b2c3d4e5f6...
   Severity: medium  
   Suggested: Interrupt the session and provide more specific context
```

## Architecture

- **Process Monitor**: Detects Claude Code startup via process monitoring
- **Log Monitor**: File watching service for Claude Code session logs
- **Loop Detector**: Pattern recognition engine with configurable thresholds
- **Notification Service**: macOS desktop notification system
- **Configuration Manager**: Handles settings and user preferences

## Development

```bash
# Install development dependencies
pip install -r requirements.txt

# Run in development mode
python -m loopguard.cli start
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests to the GitHub repository.
