md4ai 0.10.3 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +98 -76
  2. package/dist/index.bundled.js +738 -383
  3. package/package.json +5 -2
package/README.md CHANGED
@@ -1,100 +1,136 @@
1
- # md4ai
1
+ <p align="center">
2
+ <strong><span style="color:#38bdf8">MD4</span>AI</strong><br/>
3
+ <em>See what Claude actually reads</em>
4
+ </p>
2
5
 
3
- CLI for [MD4AI](https://www.md4ai.com) — scan your Claude Code projects and sync results to a web dashboard.
6
+ <p align="center">
7
+ <a href="https://www.npmjs.com/package/md4ai"><img src="https://img.shields.io/npm/v/md4ai?color=38bdf8&label=npm" alt="npm version"></a>
8
+ <a href="https://www.npmjs.com/package/md4ai"><img src="https://img.shields.io/npm/dm/md4ai?color=10b981" alt="monthly downloads"></a>
9
+ <a href="https://github.com/Media-HQ-2-Ltd/MD4AI/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Media-HQ-2-Ltd/MD4AI" alt="licence"></a>
10
+ <a href="https://www.md4ai.com"><img src="https://img.shields.io/badge/dashboard-md4ai.com-38bdf8" alt="web dashboard"></a>
11
+ </p>
4
12
 
5
- Discovers Claude configuration files, builds dependency graphs, detects orphans and broken references, catalogues skills and marketplace plugins, and pushes everything to a shared dashboard for team visibility.
13
+ ---
6
14
 
7
- ## Installation
15
+ Scan your Claude Code configuration, visualise the dependency graph, catch orphan files, and track software versions — across every device and every project.
16
+
17
+ **Free for individual developers.** Teams get shared dashboards and invite-based collaboration.
18
+
19
+ <p align="center">
20
+ <img src="https://www.md4ai.com/screenshots/project-overview.png" alt="MD4AI project dashboard" width="700"/>
21
+ </p>
22
+
23
+ ## Why MD4AI?
24
+
25
+ As your Claude Code setup grows — CLAUDE.md, skills, hooks, MCP servers, memory files, plan docs — it becomes hard to see the full picture. MD4AI scans everything and shows you:
26
+
27
+ - **Dependency graph** — which files reference which, interactively
28
+ - **Orphan detection** — config files nothing points to
29
+ - **Broken references** — links to files that don't exist
30
+ - **Skills catalogue** — project-specific, machine-wide, and marketplace plugins
31
+ - **Stale files** — anything untouched for 90+ days
32
+ - **Environment drift** — compare `.env`, Vercel, and GitHub Secrets
33
+ - **Software versions** — frameworks and tools detected vs latest releases
34
+
35
+ ## Quick Start
8
36
 
9
37
  ```bash
10
38
  npm install -g md4ai
11
39
  ```
12
40
 
13
- Requires **Node.js 22** or later.
41
+ > Requires **Node.js 22** or later. Works on **Windows (WSL2)**, **Linux**, and **macOS**.
14
42
 
15
- ## Setup
43
+ ```bash
44
+ # 1. Create an account at md4ai.com and set your API key
45
+ export MD4AI_SUPABASE_ANON_KEY="your-anon-key"
16
46
 
17
- 1. **Create an account** at [md4ai.com](https://www.md4ai.com) and create a project.
47
+ # 2. Log in
48
+ md4ai login
18
49
 
19
- 2. **Set the Supabase key** in your shell profile:
50
+ # 3. Link a project (get the ID from the dashboard URL)
51
+ cd /path/to/your-claude-project
52
+ md4ai link <project-id>
20
53
 
21
- ```bash
22
- export MD4AI_SUPABASE_ANON_KEY="your-anon-key"
23
- ```
54
+ # 4. That's it — your scan results are live at md4ai.com
55
+ ```
24
56
 
25
- 3. **Log in:**
57
+ Or scan without an account:
26
58
 
27
- ```bash
28
- md4ai login
29
- ```
59
+ ```bash
60
+ md4ai scan --offline # generates output/index.html
61
+ ```
30
62
 
31
- 4. **Link your project:**
63
+ ## What You Get
32
64
 
33
- ```bash
34
- cd /path/to/your-claude-project
35
- md4ai link <project-id>
36
- ```
65
+ ### Dependency Graph
37
66
 
38
- The project ID is in the URL when viewing your project on the dashboard.
67
+ See how your CLAUDE.md, skills, hooks, and config files connect. Search, zoom, and print wall sheets.
39
68
 
40
- ## Commands
69
+ <p align="center">
70
+ <img src="https://www.md4ai.com/screenshots/dependency-graph.png" alt="Dependency graph" width="600"/>
71
+ </p>
41
72
 
42
- ### Scanning & Syncing
73
+ ### Orphan Detection
43
74
 
44
- | Command | Description |
45
- |---------|-------------|
46
- | `md4ai scan [path]` | Scan a Claude project and push results to the dashboard. Defaults to current directory. |
47
- | `md4ai scan --offline` | Scan locally only — generates `output/index.html` without pushing to Supabase. |
48
- | `md4ai sync` | Re-push the most recent scan data for the current project. |
49
- | `md4ai sync --all` | Re-scan and sync all linked projects on this device. |
50
- | `md4ai link <project-id>` | Link the current directory to a dashboard project and run an initial scan. |
75
+ Find configuration files not reachable from any root. Grouped by folder with modification dates.
51
76
 
52
- ### Analysis
77
+ <p align="center">
78
+ <img src="https://www.md4ai.com/screenshots/orphan-files.png" alt="Orphan files" width="600"/>
79
+ </p>
53
80
 
54
- | Command | Description |
55
- |---------|-------------|
56
- | `md4ai simulate <prompt>` | Show which files Claude Code would load for a given prompt. |
57
- | `md4ai print <title>` | Generate a printable A3 wall-chart HTML with the dependency graph and skills table. |
58
- | `md4ai init-manifest` | Scaffold an `env-manifest.md` from detected `.env` files in the project. |
81
+ ### Skills Comparison
59
82
 
60
- ### Account & Device Management
83
+ Every skill and plugin at a glance — machine-wide vs project-specific, with current status.
84
+
85
+ <p align="center">
86
+ <img src="https://www.md4ai.com/screenshots/skills-table.png" alt="Skills comparison" width="600"/>
87
+ </p>
88
+
89
+ ### Software Versions
90
+
91
+ Track detected tool versions compared against latest stable and beta releases.
92
+
93
+ <p align="center">
94
+ <img src="https://www.md4ai.com/screenshots/software-versions.png" alt="Software versions" width="600"/>
95
+ </p>
96
+
97
+ ## Commands
98
+
99
+ ### Scanning & Syncing
61
100
 
62
101
  | Command | Description |
63
102
  |---------|-------------|
64
- | `md4ai login` | Authenticate with email and password. |
65
- | `md4ai logout` | Clear stored credentials. |
66
- | `md4ai status` | Show login status, linked folders, and last sync time. |
67
- | `md4ai add-folder` | Create a new project folder on the dashboard. |
68
- | `md4ai add-device` | Add a device path to an existing project. |
69
- | `md4ai list-devices` | List all devices and their linked projects. |
103
+ | `md4ai scan [path]` | Scan a Claude project and push results to the dashboard |
104
+ | `md4ai scan --offline` | Scan locally — generates `output/index.html` without pushing |
105
+ | `md4ai sync --all` | Re-scan and sync all linked projects on this device |
106
+ | `md4ai link <project-id>` | Link cwd to a dashboard project and run initial scan |
70
107
 
71
- ### Monitoring
108
+ ### Analysis
72
109
 
73
110
  | Command | Description |
74
111
  |---------|-------------|
75
- | `md4ai mcp-watch` | Monitor MCP server status on this device (runs until Ctrl+C, polls every 30s). |
112
+ | `md4ai simulate <prompt>` | Show which files Claude would load for a given prompt |
113
+ | `md4ai print <title>` | Generate a printable A3 wall-chart HTML |
114
+ | `md4ai init-manifest` | Scaffold an `env-manifest.md` from detected `.env` files |
76
115
 
77
- ### Other
116
+ ### Account & Devices
78
117
 
79
118
  | Command | Description |
80
119
  |---------|-------------|
81
- | `md4ai import <zipfile>` | Import an exported team bundle. |
82
- | `md4ai update` | Check for updates and install if available. |
83
- | `md4ai config set <key> <value>` | Set a configuration value (e.g. `vercel-token`). |
120
+ | `md4ai login` | Authenticate with email and password |
121
+ | `md4ai status` | Show login status, linked folders, and last sync |
122
+ | `md4ai list-devices` | List all devices and their linked projects |
123
+ | `md4ai mcp-watch` | Monitor MCP server status (runs until Ctrl+C) |
84
124
 
85
- ## What Gets Scanned
125
+ ### One Command to Rule Them All
86
126
 
87
- Running `md4ai scan` discovers files in `.claude/`, `CLAUDE.md`, `skills.md`, and `docs/plans/`. It then:
127
+ ```bash
128
+ md4ai start # or just: md4ai
129
+ ```
88
130
 
89
- - **Builds a dependency graph** by parsing markdown links, bare file paths, `$CLAUDE_PROJECT_DIR` references, and JSON hook configurations.
90
- - **Detects orphans** — files not reachable from any root configuration.
91
- - **Finds broken references** — links pointing to files that don't exist on disk.
92
- - **Catalogues skills** — both project-specific and machine-wide, including marketplace plugins.
93
- - **Flags stale files** — anything not modified in over 90 days.
94
- - **Scans environment variables** — if an `env-manifest.md` is present, checks local `.env` files, Vercel, and GitHub Secrets for drift.
95
- - **Detects tooling** — frameworks, runtimes, and packages from `package.json` and MCP settings.
131
+ Checks for updates, scans the current project, and starts MCP monitoring — all in one go.
96
132
 
97
- Scan output:
133
+ ## Scan Output
98
134
 
99
135
  ```
100
136
  Files found: 41
@@ -109,15 +145,6 @@ Plugins: 17 (17 skills)
109
145
  Data hash: 9868c4a8b50f...
110
146
  ```
111
147
 
112
- ## File Locations
113
-
114
- | Item | Path |
115
- |------|------|
116
- | Credentials | `~/.md4ai/credentials.json` |
117
- | State | `~/.md4ai/state.json` |
118
- | Local scan preview | `output/index.html` (in scanned project) |
119
- | Print exports | `output/print-<timestamp>.html` |
120
-
121
148
  ## Web Dashboard
122
149
 
123
150
  All scan data syncs to [md4ai.com](https://www.md4ai.com) where you can:
@@ -129,16 +156,11 @@ All scan data syncs to [md4ai.com](https://www.md4ai.com) where you can:
129
156
  - Share projects with team members
130
157
  - Compare skills across machines
131
158
 
132
- ## Tech Stack
133
-
134
- - **TypeScript** (strict, ESM)
135
- - **Commander** for CLI parsing
136
- - **Supabase** for auth and data storage
137
- - **esbuild** for bundling
138
-
139
159
  ## Support
140
160
 
141
- For questions, feedback, or bug reports: [richard@mediahq2.com](mailto:richard@mediahq2.com)
161
+ Questions, feedback, or bugs: [richard@mediahq2.com](mailto:richard@mediahq2.com)
162
+
163
+ Built by [Testate Technologies Ltd](https://www.md4ai.com) · [Changelog](https://www.md4ai.com/changelog)
142
164
 
143
165
  ## Licence
144
166