ai-dev-harness 0.2.1

Multi-harness AI coding tool config inspector — scan, visualize, and audit AI assistant ecosystems.

ai-dev-harness

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

# Install from PyPI
pip install ai-dev-harness

Or install from source in development mode:

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

# 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

# Full JSON scan data
liteharness scan

# Filter to one harness
liteharness scan --harness cursor

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

Web Dashboard

# Launch interactive browser UI on localhost:8500
liteharness web

# Custom port
liteharness web --port 9000

Other Commands

# 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

# 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