# Agent Owl

[![CI](https://github.com/arnwaldn/agent-owl/actions/workflows/ci.yml/badge.svg)](https://github.com/arnwaldn/agent-owl/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)

**Agent Owl** — Cryptographic file integrity monitoring with OWL/RDF ontology and EU AI Act compliance for Claude Code.

> Every file Claude touches gets a cryptographic fingerprint. Every change becomes an immutable RDF triple. Every AI system gets EU regulation tracking. Zero configuration required.

> **Legal notice** — Agent Owl helps you *document* compliance efforts (audit trails, EU AI Act artifacts, retention checks). It does not *guarantee* compliance with the EU AI Act or any other regulation, and nothing it produces constitutes legal advice. Assess your obligations with a qualified professional.

---

## Features

### File Integrity
- **Cryptographic hashing**: SHA-256, SHA-512, BLAKE2b (single or dual-hash mode)
- **Real-time monitoring**: Watchdog-based file system events
- **Integrity verification**: Compare stored hashes against current files
- **Full audit trail**: Every version, every change, timestamped and immutable

### Semantic Knowledge Graph
- **OWL 2 DL ontology**: Formal class hierarchy with property restrictions
- **RDF triple store**: rdflib-based with thread-safe operations
- **SPARQL queries**: Read-only SELECT against the full graph (TBox + ABox)
- **W3C PROV-O alignment**: Standards-compliant provenance tracking
- **Turtle serialization**: Human-readable, compact format

### EU AI Act Compliance (Reg. 2024/1689)
- **AI system registration** (Art. 3): Risk levels, lifecycle phases, compliance status
- **Risk management** (Art. 9): Risk assessments with severity and likelihood
- **Log retention** (Art. 19): Automated retention compliance monitoring (minimum six months)
- **Quality management** (Art. 17): Comprehensive compliance reports
- **Incident reporting** (Art. 73): Incident tracking with affected systems and the three statutory deadlines (15 / 10 / 2 days)
- **Annex IV documentation**: 9 mandatory points completeness checker
- **SHACL validation**: Core tier + high-risk tier constraint checking

### Claude Code Integration
- **15 MCP tools**: File integrity, compliance, SPARQL, project management
- **3 automatic hooks**: SessionStart, PostWrite, PostBash (git commit) — zero configuration
- **Skill command**: `/owl-audit` with 15 operations
- **Multi-project**: Autonomous detection and tracking across all your projects
- **Plugin format**: One-command installation

---

## Architecture

```
agent-owl/
├── agent_owl/                 # Core Python library
│   ├── ontology.ttl            # OWL 2 DL ontology (TBox) — 709 triples
│   ├── ontology-shacl.ttl      # SHACL shapes — 194 triples
│   ├── store.py                # Thread-safe RDF graph store
│   ├── hasher.py               # Streaming hash computation
│   ├── agent.py                # Core agent (watchdog, scan, events)
│   ├── discovery.py            # Multi-project discovery + AgentCache
│   ├── compliance.py           # EU AI Act compliance engine
│   ├── validator.py            # SHACL validation
│   ├── annexe_iv.py            # Annex IV completeness checker
│   ├── report.py               # HTML/Markdown report generator
│   └── templates/              # Jinja2 report templates
├── agent_owl_mcp_server.py          # FastMCP server (15 tools)
├── hooks/                      # Claude Code hooks
│   ├── owl-session-start.py   # Auto-detect project at startup
│   ├── owl-post-write.py      # Hash files on Write/Edit
│   └── owl-compliance-check.py # Compliance summary on git commit
├── commands/
│   └── owl-audit.md           # /owl-audit skill command
└── tests/                      # 175 tests
```

### How it works

```
Claude writes a file
        │
        ▼
  PostWrite hook ──────► auto-detect project (walk-up)
        │                       │
        │               auto-init if needed
        │                       │
        ▼                       ▼
  SHA-256 hash ◄──── AuditAgent instance (cached)
        │
        ▼
  RDF triple store ──► audit_store/audit.ttl
        │
        ▼
  OWL ontology ──────► SPARQL queryable
```

---

## Installation

### Claude Code Plugin (recommended)

```bash
claude plugin marketplace add arnwaldn/agent-owl
claude plugin install agent-owl@agent-owl
```

### Manual Installation

```bash
git clone https://github.com/arnwaldn/agent-owl.git
cd agent-owl
bash setup.sh
```

### Python Dependencies

```bash
pip install -e .                    # Core (rdflib, watchdog)
pip install -e ".[shacl]"          # + SHACL validation (pyshacl)
pip install -e ".[report]"         # + Report generation (jinja2)
pip install -e ".[all]"            # Everything
pip install -e ".[dev]"            # Development (pytest, ruff, mypy)
```

The MCP server requires FastMCP:
```bash
pip install -e ".[server]"         # MCP server (FastMCP)
pip install -e ".[all]"            # Everything including MCP server
```

---

## Quick Start

After installation, Agent Owl works automatically:

1. **Start Claude Code** in any project directory
2. The SessionStart hook auto-detects and initializes Agent Owl
3. Every file Write/Edit gets hashed and tracked
4. Every git commit shows a compliance summary

### Verify installation

```
/owl-audit stats
```

### Register an AI system for EU AI Act tracking

```
/owl-audit register MyChatbot high_risk
```

### Check compliance

```
/owl-audit status MyChatbot
/owl-audit validate MyChatbot
/owl-audit annex-iv MyChatbot
```

---

## MCP Tools Reference

### File Integrity (5 tools)

| Tool | Description |
|------|-------------|
| `audit_verify_file` | Verify cryptographic integrity of a single file |
| `audit_file_history` | Get full audit trail for a file |
| `audit_full_scan` | Scan all watched paths, detect changes |
| `audit_stats` | Store statistics (files, versions, events, triples) |
| `audit_violations` | List all integrity violations |

### EU AI Act Compliance (6 tools)

| Tool | Description |
|------|-------------|
| `compliance_register_system` | Register an AI system (Art. 3) |
| `compliance_status` | Comprehensive compliance overview (Art. 17) |
| `compliance_validate` | SHACL validation against ontology constraints |
| `compliance_annex_iv` | Annex IV documentation completeness |
| `compliance_incidents` | List incidents (Art. 73) |
| `compliance_export_report` | Export HTML/Markdown compliance report |

### Query (2 tools)

| Tool | Description |
|------|-------------|
| `audit_sparql` | Execute read-only SPARQL query |
| `compliance_retention_check` | Check Art. 19 log retention compliance |

### Project Management (2 tools)

| Tool | Description |
|------|-------------|
| `audit_init` | Initialize Agent Owl in a directory |
| `audit_list_projects` | List all active Agent Owl projects |

---

## Hooks

Agent Owl installs 3 automatic hooks in Claude Code:

| Hook | Trigger | Action |
|------|---------|--------|
| **SessionStart** | Claude Code starts | Auto-detect project, auto-init if needed |
| **PostToolUse Write\|Edit** | Any file write | Hash file and record in audit store |
| **PostToolUse Bash** | git commit | Show compliance summary |

All hooks exit 0 unconditionally — they never block Claude Code.

### Manual Hook Registration

If you installed manually (not via `claude plugin install`), add this to `~/.claude/settings.local.json`:

```json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "python \"$HOME/.claude/hooks/owl-session-start.py\"",
        "timeout": 15
      }]
    }],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "python \"$HOME/.claude/hooks/owl-post-write.py\"",
          "timeout": 10
        }]
      },
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "python \"$HOME/.claude/hooks/owl-compliance-check.py\"",
          "timeout": 15
        }]
      }
    ]
  }
}
```

---

## Configuration

Each project gets an `owl-audit.config.json`:

```json
{
  "watch_paths": [
    "./"
  ],
  "exclude_patterns": [
    "**/.git/**",
    "**/__pycache__/**",
    "**/node_modules/**",
    "**/.venv/**",
    "**/venv/**",
    "**/.DS_Store",
    "**/Thumbs.db",
    "**/*.pyc",
    "**/audit_store/**",
    "**/*.backup.*",
    "*.backup.*"
  ],
  "hash_algorithm": "sha256",
  "dual_hash": false,
  "store_path": "./audit_store",
  "ontology_file": "audit.ttl",
  "scan_interval_seconds": 300,
  "max_file_size_bytes": 524288000,
  "file_categories": {
    "code": [
      ".py",
      ".js",
      ".ts",
      ".jsx",
      ".tsx",
      ".rs",
      ".go",
      ".java",
      ".cs",
      ".dart",
      ".rb",
      ".php"
    ],
    "config": [
      ".json",
      ".yaml",
      ".yml",
      ".toml",
      ".env",
      ".xml"
    ],
    "spec": [
      ".md",
      ".txt",
      ".rst"
    ],
    "media": [
      ".png",
      ".jpg",
      ".jpeg",
      ".svg",
      ".webp"
    ]
  },
  "log_level": "INFO",
  "enable_watchdog": true,
  "compact_after_events": 10000
}
```

### Environment variables

| Variable | Read by | Purpose |
|----------|---------|---------|
| `OWL_AUDIT_CONFIG_PATH` | MCP server | Absolute path to an `owl-audit.config.json`; pins the default project used when a tool call provides no `project_path`. |
| `OWL_AUDIT_PROJECT_DIR` | Hooks and MCP server | Root of the Agent Owl installation, so the hooks can import the `agent_owl` package. Set automatically by the plugin (`.mcp.json`) and by `setup.sh` — you only need it for manual setups. |

---

## SPARQL Examples

**All files modified in last 24h:**
```sparql
PREFIX ao: <https://arnwaldn.github.io/agent-owl/ontology/audit#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
SELECT ?path ?ts WHERE {
    ?evt ao:hasEventType ao:FileModified ;
         ao:concernsFile ?f ;
         ao:timestamp ?ts .
    ?f ao:filePath ?path .
    FILTER(?ts > "2026-02-19T00:00:00Z"^^xsd:dateTime)
}
```

**Full provenance chain for a file:**
```sparql
PREFIX ao: <https://arnwaldn.github.io/agent-owl/ontology/audit#>
SELECT ?vnum ?hash ?ts WHERE {
    ?f ao:filePath "/path/to/file" ;
       ao:hasVersion ?v .
    ?v ao:versionNumber ?vnum ;
       ao:versionTimestamp ?ts ;
       ao:hasHash ?h .
    ?h ao:hashValue ?hash .
}
ORDER BY ?vnum
```

**All registered AI systems:**
```sparql
PREFIX ao: <https://arnwaldn.github.io/agent-owl/ontology/audit#>
SELECT ?name ?risk ?status WHERE {
    ?sys a ao:AISystem ;
         ao:systemName ?name ;
         ao:hasRiskLevel ?risk ;
         ao:hasComplianceStatus ?status .
}
```

---

## Development

### Run tests

```bash
pip install -e ".[dev]"
pytest tests/ -v --tb=short
```

### Lint

```bash
ruff check .
mypy agent_owl agent_owl_mcp_server.py
```

### Test coverage

```bash
pytest tests/ --cov=agent_owl --cov-report=term-missing
```

---

## How Multi-Project Works

Agent Owl handles multiple projects simultaneously:

1. **Walk-up discovery**: From any file path, walks up directories to find `owl-audit.config.json`
2. **Project root detection**: Recognizes 15 project markers (`.git`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pubspec.yaml`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `composer.json`, `Gemfile`, `CMakeLists.txt`, `Makefile`, `setup.py`, `requirements.txt`)
3. **Auto-initialization**: Creates config + audit_store + .gitignore entry automatically
4. **AgentCache**: Thread-safe LRU cache (max 16 projects) with OrderedDict for O(1) operations
5. **Isolation**: Each project has its own audit store, config, and RDF graph

---

## Tech Stack

- **Python** >= 3.11
- **rdflib** >= 7.0 — RDF/OWL graph engine
- **watchdog** >= 4.0 — File system monitoring
- **pyshacl** >= 0.26 — SHACL constraint validation (optional)
- **jinja2** >= 3.1 — Report template rendering (optional)
- **FastMCP** — Model Context Protocol server

---

## License

MIT License — see [LICENSE](LICENSE)

---

*Agent Owl watches over your code. Every byte accounted for.*