---
name: Arclux
description: Use when analyzing codebases for structural issues, tracing impact of changes, enforcing architecture conventions, or building code intelligence tools. Agents should reach for ARCLUX when users ask to understand dependencies, find dead code, detect circular imports, verify framework conventions, or trace what breaks when a file changes.
metadata:
    mintlify-proj: arclux
    version: "1.0"
---

# ARCLUX Skill Reference

## Product summary

ARCLUX is a deterministic structural-analysis engine that builds a live dependency graph of any codebase, traces the blast radius of changes, and detects architectural rot (circular dependencies, dead code, orphan files, layer violations) across 27 languages. It is not a semantic search engine or AI system — every finding is traceable to a real import statement or export declaration.

**Key entry points:**
- CLI: `arclux analyze [path]` (one-off analysis), `arclux daemon [path]` (always-on background), `arclux script <file.arclux>` (DSL scripting)
- Web: `cd apps/web && pnpm run dev` (interactive graph + impact visualization)
- MCP: `arclux mcp` (32 registry-driven tools for agent integration)
- Core package: `packages/engine/pipeline.ts` (analyzeRepository orchestrator)

**Supported languages:** TypeScript, JavaScript, Python, Go, Java, PHP, Ruby, Rust, C++, C#, Bash, C, Dart, Elixir, Kotlin, Lua, Objective-C, OCaml, Scala, Solidity, Swift, Vue, Zig, Elm, ReScript (25 via web-tree-sitter, 2 via TypeScript Compiler API) + manifest parsers (package.json, go.mod, Cargo.toml, Gemfile, composer.json, .csproj, Gradle/POM, requirements.txt).

**Primary docs:** https://arclux-os.mintlify.app

## When to use

Reach for ARCLUX when:
- User asks to analyze a codebase for structural issues (circular deps, dead code, orphan files, layer violations)
- User needs to understand what breaks if they change a specific file (impact analysis)
- User wants to verify a repo follows framework conventions (Next.js, NestJS, Express, Vite, Electron, React, Laravel)
- User needs to trace architectural changes between two git refs (diff)
- User is building code intelligence tools and needs a structural model as input
- User wants to run security analysis (secrets, unsafe patterns, trust boundaries, attack surface)
- User needs to search across a codebase (fuzzy filename + export-name matching)
- User is integrating ARCLUX into CI/CD to gate PRs on structural health

Do NOT use ARCLUX for semantic search, embeddings, RAG, or AI-driven code understanding — those are consumer layers built on top of ARCLUX's structural model, not part of ARCLUX itself.

## Quick reference

### Essential CLI commands

| Command | Purpose |
|---------|---------|
| `arclux analyze [path]` | Parse repo, build graph, run all 20 detectors |
| `arclux graph [path]` | Print dependency graph (or `-o out.json` to save) |
| `arclux impact <file> [path]` | Trace what breaks if this file changes |
| `arclux doctor [path]` | Run all 20 detectors, report findings by severity |
| `arclux verify [path]` | Run detectors + framework rules, PASS/FAIL verdict (CI gate) |
| `arclux diagnose [path]` | Detectors + impact context + fix suggestions |
| `arclux diff <refA> <refB> [path]` | Architectural changes between two git refs |
| `arclux security [path]` | Secrets, unsafe patterns, trust boundaries, attack surface |
| `arclux search <query> [path]` | Fuzzy search (filenames + export names) |
| `arclux script <file.arclux>` | Run DSL script (chain analyze, impact, doctor, etc) |
| `arclux daemon [path]` | Always-on background analysis (watch + re-analyze on save) |
| `arclux mcp` | Start MCP server (32 tools for agent integration) |
| `arclux config [path]` | Show auto-detected framework + package manager |

### DSL scripting (arclux script)

Chain engine capabilities in plain-text `.arclux` files:

```arclux
repo = analyze("~/flask")
impact(repo, "app.py")
check(repo, "orphanFiles")
```

**Built-in functions:** analyze, doctor, check, graph, callgraph, impact, search, security, diff, archdiff + helpers (len, sum, filter, sort, exists, keys, values, env, cwd, extensions, checkids).

**Registry-driven:** extensions() and checkids() auto-grow as new parsers/detectors are registered — no code changes needed.

### The 20 detectors

| Severity | Detectors |
|----------|-----------|
| **error** | circularDependency, unusedExports, orphanFiles, layerViolation, ambiguousSymbolResolution |
| **warning** | largeModules, duplicateModules, indexFiles, deadCode, componentConvention, featureStructure, missingExports, repositoryPattern, routeConvention, storyConvention, testConvention, unusedFiles |
| **info** | sharedModules, entryPoints |

### Framework rules

14 rules across Next.js, NestJS, Express, Vite, Electron, React, Laravel. Only fire when framework is detected. Currently only `packages/rules/nextjs/requirePage.ts` is fully implemented; others are stubs.

### Daemon endpoints

When running `arclux daemon`, find the port in `~/.arclux/endpoints/DAEMON_ID.json`:

```bash
curl http://127.0.0.1:PORT/analysis       # Current analysis result
curl http://127.0.0.1:PORT/events         # SSE stream (analysis, diagnostics events)
curl http://127.0.0.1:PORT/diagnostics    # Last diagnostics run
```

### Web dashboard

```bash
cd apps/web && pnpm run dev
# Open localhost:3000/ORG/REPO
```

Features:
- Interactive dependency graph (SVG + d3-force physics)
- File tree with syntax highlighting + inline diagnostics
- Dependencies & Impact tabs (what a file needs, what breaks if you change it)
- Graph variants: import / call / folder views
- Search, detector findings, route/component resolution

## Decision guidance

### When to use each command

| Situation | Command | Why |
|-----------|---------|-----|
| First look at a repo | `arclux analyze [path]` | Quick summary: modules, graph size, detector findings |
| Before editing a file | `arclux impact <file> [path]` | Know exactly who imports this file |
| Find all structural issues | `arclux doctor [path]` | Full detector suite with severity grouping |
| Gate CI on health | `arclux verify [path]` | PASS/FAIL verdict (exit code 0/1) |
| Understand architectural drift | `arclux diff <refA> <refB> [path]` | What changed between commits |
| Detailed diagnostics + fixes | `arclux diagnose [path]` | Detectors + impact context + suggestions |
| Interactive exploration | Web dashboard | Visual graph, file details, impact halo |
| Always-on monitoring | `arclux daemon [path]` | Watch repo, re-analyze on save, expose HTTP bridge |
| Automate multi-step analysis | `arclux script <file.arclux>` | Chain commands in readable DSL |
| Agent integration | `arclux mcp` | 32 registry-driven tools for Claude, Cursor, etc |

### When to use local vs remote analysis

| Scenario | Use |
|----------|-----|
| Analyzing your own repo on disk | `arclux analyze /path/to/repo` (local, no network) |
| Analyzing a public GitHub repo | `arclux analyze https://github.com/org/repo` (clones, analyzes, cleans up; SSRF-guarded) |
| Web dashboard | Always local (clone repo first, then `cd apps/web && pnpm run dev`) |

## Workflow

### Typical task: analyze a repo and find issues

1. **Run analyze** to get a baseline:
   ```bash
   arclux analyze ~/myrepo
   ```
   Read the output: modules indexed, graph size, detector summary.

2. **Run doctor** for detailed findings:
   ```bash
   arclux doctor ~/myrepo
   ```
   Findings grouped by severity (error, warning, info). Fix error-severity items first.

3. **Trace impact before editing**:
   ```bash
   arclux impact src/core/engine.ts ~/myrepo
   ```
   See direct consumers (who imports this) and full affected-files tree.

4. **Verify the fix**:
   ```bash
   arclux verify ~/myrepo
   ```
   Should return PASS (exit code 0) if all error-severity findings are resolved.

5. **Gate CI**:
   ```bash
   arclux verify .
   ```
   Add to your CI pipeline; blocks PRs if findings exist.

### Typical task: integrate ARCLUX into an agent workflow

1. **Start the MCP server**:
   ```bash
   arclux mcp
   ```
   Exposes 32 tools (analyze, doctor, verify, graph, impact, security, search, detect, diff, parse_file, run_rules, etc).

2. **Agent calls tools** via MCP protocol (Claude, Cursor, etc auto-discover).

3. **Tools are registry-driven**: adding a new detector or parser automatically makes it available in tool descriptions — no code changes needed.

### Typical task: set up always-on analysis

1. **Start daemon**:
   ```bash
   arclux daemon ~/myrepo --detach
   ```

2. **Check status**:
   ```bash
   arclux daemon ~/myrepo --status
   arclux daemon ~/myrepo --health
   ```

3. **Connect editor or tool** to the HTTP bridge (port in `~/.arclux/endpoints/DAEMON_ID.json`):
   ```bash
   curl http://127.0.0.1:PORT/analysis
   ```

4. **Stop when done**:
   ```bash
   arclux daemon ~/myrepo --stop
   ```

## Common gotchas

- **nodeRequire.resolve() is unreliable in webpack bundles** — returns relative path to bundle, not filesystem path. Use `process.cwd()` walkup instead. This has caused bugs twice already.

- **Next.js dev server port shifts + zombie processes** — if curl/test gets empty response, check `ps aux | grep node` (should be empty before restart) and verify the port matches the `Local:` line exactly. This is the most common source of confusion.

- **Always cat the file first before patching** — don't assume content from previous drafts/issues. Files change between sessions and PRs.

- **Patch with python3 heredoc + verify anchor count == 1** — abort if 0 or >1. Set `set +H` at session start so bash doesn't eat `!` in heredoc.

- **ArcluxError in API routes doesn't auto-log** — check if error-handling intentionally skips `console.error`.

- **Testing via tsx (analyzeRepository/buildIndex) skips webpack** — proves Node logic works, NOT that it works in Next.js runtime. Test both separately.

- **Components marked "typecheck-only, not visually verified"** — take bug reports seriously even if code looks correct.

- **wasmPath is hardcoded to pnpm structure** — will break if switching to npm/yarn.

- **Typecheck apps/web from inside apps/web, not repo root**:
   ```bash
   cd apps/web && npx tsc --noEmit
   ```
   Running from root produces 100+ false `@/` alias errors (known, harmless, documented).

- **/tmp doesn't exist on Termux** — put throwaway scripts inside the repo and delete after use.

- **Turbopack not supported on Termux/arm64** — don't add `--turbo` to `pnpm run dev` in apps/web.

- **Tree-sitter WASM blocks MCP startup if parsers imported at top level** — lazy-load tree-sitter parsers only when needed.

- **MCP protocol requires initialize → notifications/initialized → tools/list** — not just initialize.

- **pnpm workspace.yaml must include packages/*** — or workspace deps fail to resolve.

## Verification checklist

Before submitting work with ARCLUX:

- [ ] Run `arclux analyze .` on the target repo — no parse errors or skipped files
- [ ] Run `arclux doctor .` — confirm detector findings match expectations
- [ ] Run `arclux verify .` — should PASS (exit code 0) if no structural issues
- [ ] If adding a detector: verify it fires on a positive control (planted violation) and stays empty on negative control
- [ ] If adding a parser: test against a real fixture (not just empty file)
- [ ] If modifying core packages (engine, repository, shared, indexer, graph, impact): add a `decisions.md` entry first
- [ ] If adding to extension points (parser, detector, cache, rules): no discussion needed, just add
- [ ] If touching apps/web: typecheck from inside apps/web (`cd apps/web && npx tsc --noEmit`), not repo root
- [ ] If running daemon: confirm port in `~/.arclux/endpoints/DAEMON_ID.json` matches what you're hitting
- [ ] If using MCP: confirm all 32 tools appear in `tools/list` response (registry-driven, auto-evolving)

## Resources

**Comprehensive page listing:** https://arclux-os.mintlify.app/llms.txt

**Critical docs:**
- [Tutorial](https://arclux-os.mintlify.app/tutorial) — end-to-end walkthrough with real Flask repo output
- [Architecture](https://arclux-os.mintlify.app/architecture) — boundary map (core, core-adjacent, extension points, stubs)
- [How to Use](https://arclux-os.mintlify.app/how-to-use) — CLI, daemon, web, VS Code extension, DSL scripting

---

> For additional documentation and navigation, see: https://arclux-os.mintlify.app/llms.txt