# @fmatar/archlens-skill > Cross-platform CLI and installer for Archlens Clean Architecture governance policies and AI assistant skills Latest version **0.0.1-Alpha-09** (published 2026-09-25) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @fmatar/archlens-skill pnpm add @fmatar/archlens-skill yarn add @fmatar/archlens-skill bun add @fmatar/archlens-skill ``` Provides the commands `archlens-init`, `archlens-skill`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.0.1-Alpha-09 | | Published | 2026-09-25 | | First published | 2026-09-25 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=18.0.0 | | Dependencies | 0 | | Unpacked size | 122.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1 | | Author | Fady Matar | | Maintainers | slixes | | Keywords | archlens, clean-architecture, architecture-governance, dependency-inversion, claude-skill, gemini-skill, antigravity, npx-installer, scaffolder, code-analysis | ## Links - npm: https://www.npmjs.com/package/@fmatar/archlens-skill - Repository: https://github.com/fmatar/archlens - Homepage: https://github.com/fmatar/archlens#readme - Issues: https://github.com/fmatar/archlens/issues - npm.io page: https://npm.io/package/@fmatar/archlens-skill ## Alternatives - [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads - [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads - [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads - [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads - [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads ## Recent versions - 0.0.1-Alpha-09 (latest) — 2026-09-25 - 0.0.1-Alpha-07 — 2026-09-25 ## README # @fmatar/archlens-skill [![npm version](https://img.shields.io/npm/v/@fmatar/archlens-skill.svg)](https://www.npmjs.com/package/@fmatar/archlens-skill) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Node](https://img.shields.io/badge/Node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/) Zero-dependency CLI, policy scaffolder, and multi-agent skill installer for the **[Archlens Dynamic Clean Architecture Workbench](https://github.com/fmatar/archlens)**. Analyzes any project repository, detects programming languages and package hierarchies, classifies packages into concentric Clean Architecture tiers, scaffolds `.archlens/policy.json`, and equips AI coding assistants (Claude Code, Gemini CLI, Google Antigravity) with mailbox refactoring protocols. --- ## ⚡ Quickstart ### Option A: Run via NPX ```bash # Production Stable (recommended) npx @fmatar/archlens-skill # Canary / Development Preview (tracks latest develop branch) npx @fmatar/archlens-skill@dev # Direct GitHub Execution (zero registry dependencies) npx github:fmatar/archlens ``` ### Option B: Install Globally via NPM ```bash npm install -g @fmatar/archlens-skill archlens-skill ``` ### Option C: Run from Local Repository Clone ```bash # Install globally from the local repository: npm install -g ./cli archlens-skill # Or execute directly with Node: node ./cli/bin/index.js ``` --- ## 🚀 Key Features - **Zero External Dependencies**: Engineered with pure Node.js standard libraries (`node:fs`, `node:path`, `node:readline`, `node:test`, `node:os`). Executes immediately via `npx` without latency. - **Interactive Terminal UI**: Displays styled ANSI diagnostics, ASCII branding banner, and interactive guided choices when run in a terminal. - **Polyglot Codebase Analyzer**: Auto-detects project language and layout across Java, Kotlin, TypeScript, JavaScript, Python, Rust, Go, and Clojure. - **Concentric Tier Classification**: Maps packages automatically to Clean Architecture layers: - **Level 0 (Domain Core)**: `domain`, `model`, `entities`, `core`, `types` - **Level 1 (Application)**: `usecase`, `application`, `service`, `port`, `interactor` - **Level 2 (Adapters)**: `adapter`, `controller`, `gateway`, `presenter`, `repository`, `dto`, `api` - **Level 3 (Infrastructure)**: `infrastructure`, `config`, `db`, `web`, `server`, `client` - **Multi-Agent Skill Deployment**: Installs the `archlens-install-policy` skill globally into Claude Code (`~/.claude/skills/`), Gemini CLI / Antigravity (`~/.gemini/config/skills/`), and custom agent workspaces. - **Safe Incremental Updates**: Re-scans codebases for newly introduced packages, updating `order` and `levels` while preserving user custom rules and configurations. - **Seamless Upgrade Migration**: Automatically migrates legacy `.uml-viewer/` folders and companion files to modern `.archlens/` via `archlens-skill upgrade`. - **Model Context Protocol (MCP) Client Auto-Configuration**: Detects and configures host AI client manifests (Claude Desktop, Google Antigravity, Claude Code, Cursor, VS Code) in a single command (`--mcp`). - **On-Demand Container Orchestration & Stdio Bridge**: Automatically spins up the Archlens container when needed, bridges MCP over stdio (`mcp` command), and provides an instant offline AST fallback if Docker is unavailable. - **Mailbox Protocol Integration**: Injects the Clean Architecture Companion Protocol into `CLAUDE.md` and `AGENTS.md` for seamless asynchronous mailbox refactoring (`to-agent.json`, `to-viewer.json`). --- ## 🛠️ Usage & CLI Reference ### Common Workflows #### 1. Interactive Setup Wizard Guides you through repository inspection and option selection: ```bash npx @fmatar/archlens-skill ``` #### 2. Headless Local Initialization Initializes Clean Architecture governance in the current repository with default settings: ```bash npx @fmatar/archlens-skill --yes ``` Target a specific repository directory: ```bash npx @fmatar/archlens-skill --path /path/to/project --yes ``` #### 3. Global AI Agent Skill Installation Deploys the skill globally so Claude Code, Gemini CLI, and Antigravity can scaffold policies on demand: ```bash npx @fmatar/archlens-skill global ``` #### 4. Synchronize Existing Policy Re-scans code after adding new modules or packages to incorporate them into `.archlens/policy.json`: ```bash npx @fmatar/archlens-skill update ``` #### 5. Upgrade Legacy Configuration Migrates older `.uml-viewer/` directories and companions to the standard `.archlens/` layout: ```bash npx @fmatar/archlens-skill upgrade ``` #### 6. Export LLM Refactoring Prompt Dossier Generates copy-ready architectural diagnostics and concrete Dependency Inversion Principle (DIP) instructions for Claude Code, Gemini, ChatGPT, or Antigravity: ```bash # Print dossier to stdout npx @fmatar/archlens-skill prompt # Or copy directly to system clipboard npx @fmatar/archlens-skill prompt --copy ``` #### 7. Model Context Protocol (MCP) Setup & Stdio Bridge Configures detected AI client manifests or launches an interactive stdio bridge: ```bash # Auto-configure Claude Desktop, Google Antigravity, Claude Code, Cursor, and VS Code npx @fmatar/archlens-skill --mcp # Launch MCP stdio transport bridge (spins up Docker container automatically when needed) npx @fmatar/archlens-skill mcp ``` #### 8. Start Workbench Container & Auto-Resurrection Starts the Archlens container, mounts the workspace, verifies readiness, and optionally opens your browser. **If the container is killed or stopped, running `start` (or calling an MCP tool) automatically starts it again:** ```bash # Start container and automatically open workbench in browser: npx @fmatar/archlens-skill start --open # Start container in background on default port 8088: npx @fmatar/archlens-skill start # Specify a custom port or target workspace directory: npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open ``` --- ### Command-Line Options | Flag | Shorthand | Description | Default | |------|-----------|-------------|---------| | `start` | | Start Archlens Workbench container (auto-resurrects on demand) | | | `--open` | `-o` | Open visual workbench in default browser upon startup | `false` | | `--port ` | | Workbench HTTP port | `8088` | | `--path ` | `-p` | Target repository directory | `.` (current directory) | | `--title ` | `-t` | Project title in visual workbench | Formatted folder name | | `--prefix ` | | Common package prefix (e.g. `com.example.service`) | Auto-detected | | `--server-url ` | | Visual Workbench server endpoint | `http://localhost:8088` | | `--mcp` | `-m` | Auto-configure MCP client manifests (Claude, Antigravity, Cursor) | `false` | | `--copy` | `-c` | Copy LLM prompt output directly to system clipboard | `false` | | `--global` | `-g` | Install skill into global agent directories | `false` | | `--update` | `-u` | Re-scan code and update existing policy | `false` | | `--upgrade` | | Migrate legacy `.uml-viewer` to `.archlens` | `false` | | `--force` | `-f` | Overwrite existing configuration files | `false` | | `--dry-run` | | Simulate execution without writing files | `false` | | `--yes` | `-y` | Accept defaults automatically (non-interactive) | `false` | | `--version` | `-v` | Display package version | | | `--help` | `-h` | Display help reference | | --- ## 📁 Artifacts Generated Running the installer creates the following governance structure: ```text my-project/ ├── .archlens/ │ ├── policy.json # Clean Architecture concentric tiers & rules │ └── workbench.config.json # Workbench endpoint and mailbox IPC configuration ├── CLAUDE.md # Clean Architecture Mailbox companion protocol └── AGENTS.md # Agent instructions for DIP refactoring & AST reload ``` ### Visualizing in Archlens Workbench Once configured, launch the Archlens workbench and open your project: ```text http://localhost:8088/?projectRoot=/absolute/path/to/my-project ``` Or open the visual workbench and press `⌘O` / `Ctrl+O` to browse and select your project root. --- ## 🧪 Testing Execute the test suite with Node's native test runner: ```bash npm test ``` --- ## 📄 License Apache-2.0 © [Fady Matar](https://github.com/fmatar) --- _Source: https://npm.io/package/@fmatar/archlens-skill · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._