ForgeLens

Why ForgeLens?

AI coding agents often start in the wrong files. That creates slow edits, wasted context, and risky changes.

Common problems:

• Agents miss auth boundaries and session rules.
• Agents skip database/schema risk and server action risk.
• Agents ignore route exposure and env/config risk.
• Project rules drift over time, while old context is still used.

ForgeLens solves this with a local-first workflow:

• Scan the repo and generate compact AI-ready context.
• Highlight risky files and boundaries first.
• Save a baseline snapshot.
• Detect drift between baseline and current reports.
• Compare drift across git refs with main..HEAD.

Quick Start

npx forgelens scan
npx forgelens baseline save --name current
npx forgelens drift --from current
npx forgelens drift --git main..HEAD

What ForgeLens Generates

AI_COMPACT_CONTEXT.md
AI_FOCUS_MAP.md
FORGE_CONTEXT.md
ARCHITECTURE_MAP.md
ROUTES_MAP.md
DATABASE_MAP.md
SERVER_ACTIONS_MAP.md
SECURITY_RULES.md
ENV_REPORT.md
RISK_REPORT.md
DRIFT_REPORT.md
REPO_REPORT.json

Workflow Map

flowchart TD
  A[Scan repo] --> B[Generate AI context]
  B --> C[Risk reports]
  C --> D[Save baseline]
  D --> E[Detect drift]
  E --> F[Git drift]
  F --> G[AI agent reads focused context]
  G --> H[Safer code changes]

Works With

ForgeLens is built for Codex, Claude Code, Cursor, Copilot, Gemini CLI, OpenCode, and other AI coding agents.

Install

Quick run:

npx forgelens scan

Global install:

npm install -g forgelens
forgelens scan

Local development:

pnpm install
pnpm build
pnpm link --global
forgelens scan

CLI Commands

forgelens scan
forgelens doctor
forgelens baseline save
forgelens drift
forgelens clean --yes
forgelens prompt codex

Sample Output

$ forgelens scan --format all
ForgeLens scan complete: /path/to/repo/.forgelens
- FORGE_CONTEXT: /path/to/repo/.forgelens/FORGE_CONTEXT.md
- ROUTES_MAP: /path/to/repo/.forgelens/ROUTES_MAP.md
- DATABASE_MAP: /path/to/repo/.forgelens/DATABASE_MAP.md
- SECURITY_RULES: /path/to/repo/.forgelens/SECURITY_RULES.md
- ENV_REPORT: /path/to/repo/.forgelens/ENV_REPORT.md
- UI_UX_REPORT: /path/to/repo/.forgelens/UI_UX_REPORT.md
- PERFORMANCE_RISK_REPORT: /path/to/repo/.forgelens/PERFORMANCE_RISK_REPORT.md
- REPO_REPORT_JSON: /path/to/repo/.forgelens/REPO_REPORT.json

Developer Shortcuts

make check          Run typecheck, tests, build, and diff check
make scan           Generate ForgeLens reports
make baseline       Save current ForgeLens baseline
make drift          Compare against saved baseline
make release-check  Run all release checks

Docs

• Live product/docs website: forgelens-lyart.vercel.app
• GitHub launch checklist: docs/GITHUB_LAUNCH_CHECKLIST.md
• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md

Safety Notes

• Scan and doctor do not modify source files.
• ForgeLens writes only inside the selected output folder (default .forgelens/).
• Env report includes file names and key names only, never secret values.
• Detection is static and deterministic; no runtime code execution.
• Security and auth findings are heuristic signals, not guarantees.

Limits

• This is static analysis, not a full semantic or runtime analyzer.
• It is not a replacement for security review or penetration testing.
• No warning does not mean safe. False negatives and false positives are possible.
• Do not use ForgeLens as a security scanner or compliance gate.