agentic-ai-shadowing

<div align="center">

<img src="https://raw.githubusercontent.com/datasynx/agentic-ai-shadowing/main/docs/assets/datasynx-logo.png" alt="Datasynx" width="220" />

# Datasynx Shadowing · `shadowing`

### The SOPs your team never has time to write.

**Local-first. MCP-native. Claude-powered.**
Shadowing observes daily workflows like a silent shadow — shell commands, active windows, git commits, file changes — and automatically generates anonymized Standard Operating Procedures (SOPs) via Claude. Fully local, fully anonymized.

<p>
<a href="#-quick-start"><strong>Quickstart</strong></a> · <a href="https://datasynx.github.io/agentic-ai-shadowing/"><strong>Docs</strong></a> · <a href="https://www.npmjs.com/package/@datasynx/agentic-ai-shadowing"><strong>npm</strong></a> · <a href="https://github.com/datasynx/agentic-ai-shadowing"><strong>GitHub</strong></a> · <a href="https://www.linkedin.com/company/datasynx-ai/"><strong>LinkedIn</strong></a>
</p>

[![npm version](https://img.shields.io/npm/v/@datasynx/agentic-ai-shadowing.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/@datasynx/agentic-ai-shadowing)
[![downloads/week](https://img.shields.io/npm/dw/@datasynx/agentic-ai-shadowing.svg?color=cb3837&label=downloads%2Fweek)](https://www.npmjs.com/package/@datasynx/agentic-ai-shadowing)
[![CI](https://github.com/datasynx/agentic-ai-shadowing/actions/workflows/ci.yml/badge.svg)](https://github.com/datasynx/agentic-ai-shadowing/actions/workflows/ci.yml)
[![Docs](https://github.com/datasynx/agentic-ai-shadowing/actions/workflows/pages.yml/badge.svg)](https://datasynx.github.io/agentic-ai-shadowing/)
[![stars](https://img.shields.io/github/stars/datasynx/agentic-ai-shadowing?style=flat&color=ffd33d)](https://github.com/datasynx/agentic-ai-shadowing/stargazers)
[![license](https://img.shields.io/github/license/datasynx/agentic-ai-shadowing.svg?color=3fb950)](./LICENSE)
[![node](https://img.shields.io/node/v/@datasynx/agentic-ai-shadowing.svg)](https://nodejs.org)
[![Built with Claude](https://img.shields.io/badge/Built_with-Claude_API-d4a017?logo=anthropic&logoColor=white)](https://docs.anthropic.com)
[![Tests](https://img.shields.io/badge/tests-1112%20passing-3fb950?logo=vitest&logoColor=white)](https://github.com/datasynx/agentic-ai-shadowing/actions/workflows/ci.yml)

</div>

---

| Without                                                                       | With                                                                                                |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| ❌ SOPs are written from memory weeks later — if they're written at all.       | ✅ The procedure is captured *as the work happens*. Claude turns it into a structured SOP on demand. |
| ❌ Tribal knowledge walks out the door when someone leaves.                    | ✅ Every recurring task becomes a versioned, reviewable, exportable SOP.                             |
| ❌ A monitoring SaaS ships your screen activity to someone else's cloud.        | ✅ 100% local — SQLite on the employee's machine. No cloud, no daemon, no telemetry.                |
| ❌ Exports leak emails, IPs, IBANs, and file paths into shared docs.           | ✅ Every export is automatically PII-scrubbed — and you can preview the redaction first.            |
| ❌ "Is this SOP still accurate?" — nobody knows.                               | ✅ Consistency, maturity, and freshness scores flag which SOPs have gone stale.                     |
| ❌ Switch to a separate tool to update a procedure.                            | ✅ Your agent drives it in place via MCP, from inside Claude Code / Codex / Cursor.                 |

---

## What it does

```
$ shadowing start

  Agentic AI Shadowing — Active

? Start a new task? Yes
? Task title: Monthly SAP Closing
? Short description: Monthly closing tasks in SAP FI

  Task started: "Monthly SAP Closing" (ID: a3f8c210)

? What would you like to do?
  > Complete task → Generate SOP
    Pause task
    Add note to current step
    End shadowing

? How complex was this task? 3 - Medium

  Task completed. Duration: 1h 23min 45s
  Generating SOP...

  SOP generated!
  +-------------------------------------------------+
  |  Monthly SAP Closing — Standard Operating       |
  |  Procedure                                      |
  |  Tags: #accounting #sap #monthly                |
  |  Steps: 8                                       |
  +-------------------------------------------------+
```

```
$ shadowing observe --auto-sop

  Observation started (Session: b7e2f4a1)
  Sources: Windows · Shell History · Git
  Auto-SOP: enabled

  [14:23:01] Window  VS Code — src/api/routes.ts
  [14:23:45] Shell   git diff src/api/routes.ts
  [14:24:12] Shell   npm run test
  [14:31:00] Window  Chrome — Jira Board
  [14:35:22] Shell   git commit -m "fix: validate input"
  [14:35:30] Shell   git push origin feature/validation

  Observation ended. 2 tasks detected → 2 SOPs generated.
```

---

## Why it's different

- **Local-first by default** — a SQLite database on the employee's machine. No cloud sync, no background daemon, no telemetry. The only outbound call is to the Claude API for SOP generation.
- **Employee-driven** — the person doing the work starts, pauses, and completes tasks. Nothing is captured without consent and exclusion rules.
- **Anonymized at the boundary** — exports run through a PII redactor (emails, IPs, URLs, phones, file paths — plus always-on IBAN / credit-card / tax-ID / SSN scrubbing).
- **MCP-native, not bolted-on** — a 17-tool MCP server lets Claude Code, Codex, and Cursor drive Shadowing directly.
- **Quality you can measure** — consistency, maturity, and freshness scores tell you which SOPs are trustworthy and which have gone stale.
- **MIT-licensed TypeScript** — strict, ESM-only, fully typed, and extensible.

---

## Architecture

```mermaid
flowchart LR
    You["🧑 Employee"] --> CLI
    Agent["🤖 Claude Code · Codex · Cursor"] <-->|Model Context Protocol| MCP

    subgraph local["🔒 Your machine"]
        CLI["⚙️ shadowing CLI<br/>27 commands"]
        MCP["🔌 MCP server<br/>17 typed tools"]
        DB["📁 SQLite WAL<br/>tasks · SOPs · sessions"]
        CLI <--> DB
        MCP <--> DB
        Anon["🛡️ Anonymizer<br/>PII redaction"]
        DB --> Anon --> Exports["📤 exports/*.md + manifest.json"]
    end

    CLI <-->|SOP generation| Claude["✨ Claude API"]
    Carto["🗺️ Cartography graph"] -. optional context .-> CLI
```

---

## Features

| Feature | Details |
|---------|---------|
| **Automatic Observation** | Shell history, active windows, git commits, and file changes — cross-platform |
| **AI SOP Generation** | Claude generates structured SOPs with goal, prerequisites, steps, expected results |
| **Enterprise Dashboard** | Dark-theme web dashboard with SOP editor, metrics, diff viewer, export workflow |
| **Quality Metrics** | Consistency, maturity, freshness, and overall score per SOP |
| **PII Anonymization** | Email, IP, URL, phone, file paths, IBAN, credit cards, tax ID, social security number |
| **Version History** | Every SOP change is versioned with diff view |
| **Claude Code Integration** | MCP server (18 tools) + hook handler for seamless IDE integration |
| **Cartography Context** | System landscape from [@datasynx/agentic-ai-cartography](https://github.com/datasynx/agentic-ai-cartography) feeds into SOP generation |
| **Privacy First** | Consent management, exclusion rules, configurable anonymization |
| **100% Local** | SQLite DB, no cloud sync, no daemon — the employee controls everything |

---

## Cross-Platform Support

Shadowing detects windows and shell history natively on **Linux**, **macOS**, and **Windows**.

| Capability | Linux | macOS | Windows |
|---|---|---|---|
| **Window Detection** | `xdotool` (X11) | `osascript` (AppleScript) | PowerShell P/Invoke (`user32.dll`) |
| **Shell History** | Zsh extended, Bash timestamps | Zsh extended, Bash timestamps | PSReadLine ConsoleHost_history |
| **Git Tracking** | `git log` | `git log` | `git log` |
| **File Watching** | `fs.stat` | `fs.stat` | `fs.stat` |
| **Shell Detection** | `$SHELL` | `$SHELL` | `$MSYSTEM` / PowerShell fallback |

### Shell History Parser

| Shell | Format | Timestamps |
|-------|--------|-----------|
| **Zsh** | Extended (`: timestamp:duration;command`) | Exact |
| **Bash** | `#timestamp` + command lines | Exact |
| **Fish** | YAML-like (`- cmd:` / `when:`) | Exact |
| **PowerShell** | PSReadLine `ConsoleHost_history.txt` | Read time |

---

## Requirements

- **Node.js >= 22.12** (Linux, macOS, or Windows)
- **`ANTHROPIC_API_KEY`** environment variable — required **only for SOP generation**. Task tracking, observation, export, the dashboard, and metrics all work without it; you only need a key when you ask Claude to turn a task into an SOP.
- **[@datasynx/agentic-ai-cartography](https://github.com/datasynx/agentic-ai-cartography)** (optional, for infrastructure context)

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

### Environment variables

| Variable | Effect |
|----------|--------|
| `ANTHROPIC_API_KEY` | Claude API key, used for SOP generation and session analysis |
| `SHADOWING_UI_TOKEN` | Fixed Bearer token for the dashboard/REST API (otherwise a random one is generated per run) |
| `LOG_LEVEL` | `debug` / `info` / `warn` / `error`. The CLI defaults to `warn`; set `info` or `debug` to see diagnostic logs |
| `LOG_FORMAT` | Set to `json` for structured NDJSON logs |

---

## Install

```bash
npm install -g @datasynx/agentic-ai-shadowing
```

[![npm](https://img.shields.io/badge/npm-@datasynx%2Fagentic--ai--shadowing-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@datasynx/agentic-ai-shadowing)

---

## 🚀 Quick Start

```bash
# 1. Setup (create DB + config)
shadowing init

# 2. Manual mode: start task → generate