Metadata-Version: 2.4
Name: ai-dev-harness
Version: 0.2.1
Summary: Multi-harness AI coding tool config inspector — scan, visualize, and audit AI assistant ecosystems.
Author: Boris Villazon-Terrazas
License-Expression: MIT
Project-URL: Homepage, https://github.com/boricles/claude-lens
Project-URL: Repository, https://github.com/boricles/claude-lens
Project-URL: Bug Tracker, https://github.com/boricles/claude-lens/issues
Project-URL: Changelog, https://github.com/boricles/claude-lens/blob/main/CHANGELOG.md
Keywords: liteharness,claude-code,cursor,codex,copilot,windsurf,devtools,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: color
Requires-Dist: rich; extra == "color"
Dynamic: license-file

# ai-dev-harness

[![PyPI version](https://img.shields.io/pypi/v/ai-dev-harness.svg)](https://pypi.org/project/ai-dev-harness/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/ai-dev-harness.svg)](https://pypi.org/project/ai-dev-harness/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Multi-harness AI coding tool config inspector.**

Scan, visualize, and audit every AI coding assistant installed on your machine — from one place.

---

## Supported Tools

| Tool | Harness | Config Paths | Instruction File |
|------|---------|-------------|-----------------|
| **Claude Code** | `claude_code` | `~/.claude/`, `.claude/` | `CLAUDE.md` |
| **Cursor** | `cursor` | `~/.cursor/`, `.cursor/` | `.cursorrules`, `.cursor/rules/*.md` |
| **Codex CLI** | `codex` | `~/.codex/` | `AGENTS.md`, `codex.json` |
| **Windsurf** | `windsurf` | `~/.windsurf/`, `.windsurf/` | `.windsurfrules`, `.windsurf/rules/*.md` |
| **GitHub Copilot** | `copilot` | `~/.config/github-copilot/`, `.github/` | `.github/copilot-instructions.md` |

Each tool has its own **harness** — a self-contained module that knows how to detect the tool, discover its config files, parse them, and run health checks.

## Installation

```bash
# Install from PyPI
pip install ai-dev-harness
```

Or install from source in development mode:

```bash
git clone https://github.com/boricles/ai-dev-harness.git
cd ai-dev-harness
pip install -e .
```

The package provides two CLI commands: `liteharness` (primary) and `claude-lens` (alias, kept for backwards compatibility).

## Usage

### CLI Report

```bash
# Scan all detected AI tools and print a report
liteharness report

# Scan a specific harness only
liteharness report --harness claude_code

# List all supported harnesses and detection status
liteharness harnesses
```

### JSON Output

```bash
# Full JSON scan data
liteharness scan

# Filter to one harness
liteharness scan --harness cursor

# Pretty-printed
liteharness scan | python3 -m json.tool
```

### Web Dashboard

```bash
# Launch interactive browser UI on localhost:8500
liteharness web

# Custom port
liteharness web --port 9000
```

### Other Commands

```bash
# Compare two scan snapshots
liteharness diff snapshot-a.json snapshot-b.json

# Export a project's config as a portable bundle
liteharness export myproject

# Clean up stale sessions and orphaned data (interactive)
liteharness clean

# Print version
liteharness version
```

## What It Detects

For each tool, ai-dev-harness discovers:

- **Global settings** — permissions, preferences, API config
- **Instruction files** — system prompts and rules (CLAUDE.md, .cursorrules, etc.)
- **Rules/agents** — custom agent definitions, rule files
- **Sessions** — session metadata (count, size, age — never reads content)
- **Plugins/extensions** — installed plugins with capabilities
- **Memory** — memory files and index integrity
- **Health issues** — orphaned state, stale sessions, missing instructions, config drift

## Health Checks

Each harness runs its own health checks:

| Check | Harnesses | Severity |
|-------|-----------|----------|
| Missing instruction file | All | info |
| Orphaned project state | Claude Code | warning |
| Stale sessions (>30 days) | Claude Code | info |
| Memory index drift | Claude Code | warning |
| Disk usage >100-200 MB | Claude Code, Cursor, Windsurf | warning |
| Outdated config (>180 days) | Copilot | info |

## Architecture

```
liteharness/
  harnesses/
    __init__.py        # BaseHarness ABC, schema dataclasses, registry
    claude_code.py     # Claude Code harness
    cursor.py          # Cursor harness
    codex.py           # Codex CLI harness
    windsurf.py        # Windsurf harness
    copilot.py         # GitHub Copilot harness
  scanner.py           # Orchestrator — runs all harnesses, merges results
  parser.py            # Shared parsers (frontmatter, JSON, etc.)
  report.py            # CLI text report renderer
  server.py            # HTTP server + web dashboard
  web/index.html       # Single-file web dashboard (Tailwind + vanilla JS)
  export.py            # Project config export
  diff.py              # Scan snapshot comparison
  clean.py             # Cleanup stale data
  style.py             # Shared ANSI color helpers
```

### Adding a New Harness

1. Create `liteharness/harnesses/newtool.py`
2. Subclass `BaseHarness` and implement `detect()`, `scan()`, `health_checks()`
3. Decorate with `@register_harness`
4. Add the module name to `_ensure_harnesses_loaded()` in `harnesses/__init__.py`

## Design Principles

- **Zero mandatory dependencies** — stdlib only for core scanner and CLI
- **Local-first** — web server binds to `127.0.0.1` only
- **Privacy-safe** — never reads conversation content from session files
- **Non-destructive** — never modifies user files unless in explicit `clean` mode
- **Self-contained harnesses** — each harness module is independent

## Development

```bash
# Run all tests
python3 -m unittest discover tests/ -v

# Run a specific test file
python3 -m unittest tests.test_windsurf_harness -v

# Run as module
python3 -m liteharness version
```

## License

MIT
