Agent Lens (Java)

Spring Boot port of the Agent Lens dashboard (same behaviour as streamlit_app.py + cursor_lens.py in the parent repo). After start, open http://127.0.0.1:8501/ (unless you change the port).

Full project overview (Python + Java): ../README.md

---

One command: clone + run (any machine)

Replace YOUR_ORG/cursor-lense with your real GitHub owner/repo (same value in both places in each line). You need Git and internet. A GitHub Release with agent-lens.jar is required for the “no Java” path (see below); otherwise the script still clones and will use Java + Maven if installed.

macOS / Linux (bash)

R=YOUR_ORG/cursor-lense; curl -fsSL "https://raw.githubusercontent.com/$R/main/agent-lens-java/quick-run.sh" | bash -s "$R"

Clone directory default: /tmp/agent-lens-work/ (override with AGENT_LENS_CLONE_DIR).

Windows (PowerShell)

$env:AGENT_LENS_REPO='YOUR_ORG/cursor-lense'; (Invoke-WebRequest "https://raw.githubusercontent.com/$env:AGENT_LENS_REPO/main/agent-lens-java/quick-run.ps1" -UseBasicParsing).Content | Invoke-Expression

Default clone: %LOCALAPPDATA%\agent-lens-work\ (override with AGENT_LENS_CLONE_DIR).

Already cloned?

cd agent-lens-java && ./start.sh

(Or START.bat on Windows.)

---

Quick choose how to run

You have…	Command / action
Nothing installed (Windows)	Double‑click START.bat (needs a GitHub Release with agent-lens.jar).
Nothing (Mac / Linux)	chmod +x start.sh && ./start.sh
Docker	./run-docker.sh or docker compose up --build
JDK 17 + network	./run.sh or ./mvnw spring-boot:run

---

Windows

Easiest (no Java installed)

1. Clone the parent repository (or set AGENT_LENS_GITHUB_REPO=owner/repo if you only have a ZIP).
2. Make sure a GitHub Release exists with agent-lens.jar (below).
3. Open this folder in Explorer and double‑click START.bat.
4. First run downloads a portable Java 17 (into %LOCALAPPDATA%\agent-lens\) and agent-lens.jar — internet required.
5. Browser: http://127.0.0.1:8501/

You already have Java 17+

cd agent-lens-java
START.bat

Uses target\agent-lens-*.jar if present, otherwise mvnw.cmd spring-boot:run.

Docker

Install Docker Desktop, then:

cd agent-lens-java
run-docker.cmd

Or: docker compose up --build — UI on http://127.0.0.1:8501/ (set HOST_PORT=8502 if 8501 is taken).

---

macOS

No Java

cd agent-lens-java
chmod +x start.sh
./start.sh

Uses portable Temurin 17 under ~/.cache/agent-lens and downloads agent-lens.jar from GitHub Releases.

Java 17 (e.g. Homebrew)

brew install temurin@17
cd agent-lens-java
chmod +x run.sh
./run.sh

Docker

cd agent-lens-java
chmod +x run-docker.sh
./run-docker.sh

---

Linux

No Java

cd agent-lens-java
chmod +x start.sh
./start.sh

Needs curl and tar. JRE cache: $XDG_CACHE_HOME/agent-lens or ~/.cache/agent-lens.

Java 17 (Debian / Ubuntu example)

sudo apt update && sudo apt install -y openjdk-17-jdk
cd agent-lens-java
chmod +x run.sh
./run.sh

Docker

cd agent-lens-java
./run-docker.sh

---

GitHub Release with agent-lens.jar

Scripts START.bat / start.sh (no local build) download:

https://github.com/<owner>/<repo>/releases/latest/download/agent-lens.jar

Maintainers: push a version tag from the repo root:

git tag v1.0.0
git push origin v1.0.0

Workflow: .github/workflows/release-agent-lens.yml (in parent repo) builds this module and uploads agent-lens.jar to that release.

---

Developers (build from source)

Requirements: JDK 17, optional Maven (wrapper ./mvnw is included).

cd agent-lens-java
./mvnw -q -DskipTests package
java -jar target/agent-lens-*.jar

Or one step (picks a free port 8501–8509 if needed):

./run.sh

---

Configuration

Name	Meaning
server.port / SERVER_PORT	HTTP port (default 8501).
agentlens.data-dir	Directory for policies.json and APPLIED_POLICIES.md (default ./agent_lens relative to process cwd).
AGENT_LENS_PRICING_URL	Optional JSON URL merged with OpenRouter pricing.
AGENT_LENS_GITHUB_REPO	owner/repo when there is no git remote (ZIP users) for JAR download.
HOST_PORT	With Docker Compose: host port mapped to 8501 (default 8501).

---

Files in this folder (runner scripts)

File	Role
START.bat	Windows launcher (Java / no‑Java / mvnw).
setup-and-run.ps1	Used by START.bat when Java is missing.
start.sh	macOS / Linux launcher.
run.sh	Dev run with Maven wrapper + free port helper.
run-docker.sh / run-docker.cmd	Docker Compose.
HOW_TO_RUN.txt	Very short reminder list.
Dockerfile / docker-compose.yml	Container image and service.

---

Troubleshooting

• Port in use: use ./run.sh, or Docker HOST_PORT=8502 ./run-docker.sh, or set SERVER_PORT.
• 404 on agent-lens.jar: create a Release by pushing a v* tag, or build with ./mvnw package and run the JAR from target/.
• Policies not saving: check write permission on agentlens.data-dir (default ./agent_lens here).

---