# LexAI Desktop Tracker — User guide

---

## English

### What this is

A small **Windows program** that runs in the background. It notices which app you are using and when you save or export files in watched folders. That activity can appear in the **LexAI web app** (Project Home) when it is linked to your project.

You do **not** need to install Python if you use the **`LexAI-Tracker.exe`** build from the website ZIP.

---

### Install (recommended: EXE)

1. Download **`LexAI-Tracker-Windows.zip`** from the LexAI website.
2. Unzip it anywhere (for example `Documents\LexAI-Tracker`).
3. Open the folder. You should see **`LexAI-Tracker.exe`**, **`.env.example`**, **`SETUP.txt`**, and this **`README`**.

---

### First-time setup (3 steps)

1. Run **`LexAI-Tracker.exe`** once.  
   - It automatically creates **`.env`** from `.env.example` if missing.

2. In **`.env`**, set **`LEXAI_AGENT_PROJECT_ID`** to your project number from the LexAI app:  
   - Open [LexAI Hub](https://app.lexai.ai.kr/hub) and look at the URL. It contains `project_id=NUMBER`. Use that **NUMBER**.

3. Save **`.env`**. Keep **`LEXAI_AGENT_BACKEND_BASE`** as the default unless your team gave you a different server URL.

> Recommended login setup: run `python main.py --configure` once.  
> It opens a web device-login flow and writes `LEXAI_AGENT_ACCESS_TOKEN` to `.env`.  
> With default `LEXAI_AGENT_REQUIRE_LOGIN=1`, tracker sends events only while this token exists.

---

### Run

- Run **`LexAI-Tracker.exe`** directly.  
- The EXE now opens the **desktop UI first** (sign in, pick/create project, start tracking).  
- If you need legacy console mode, run with `--headless` (for source run: `python main.py --headless`).

---

### Project-scoped tracking + AI prompt capture (new)

Add these to `.env` when you want strict project-only tracking:

```text
LEXAI_AGENT_PROJECT_ROOT=C:\path\to\your\project
LEXAI_AGENT_ALLOWED_TOOLS=gemini,nanobanana,chatgpt,paint,photoshop
LEXAI_AGENT_CAPTURE_AI_PROMPTS=1
LEXAI_AGENT_PROMPT_INCLUDE_KEYWORDS=your-brand,project-name
LEXAI_AGENT_PROMPT_EXCLUDE_KEYWORDS=personal,password,bank
```

- `LEXAI_AGENT_PROJECT_ROOT`: only tracks file activity under this folder tree.
- `LEXAI_AGENT_ALLOWED_TOOLS`: keep only events from selected tools.
- `LEXAI_AGENT_CAPTURE_AI_PROMPTS=1`: captures copied prompt text from active Gemini/ChatGPT/nanobanana browser tabs (best effort).
- Include/exclude keywords help filter out unrelated prompts.
- Current scope captures **prompt preview** and metadata, not full browser history.
- For higher prompt-submit accuracy, use the browser extension in `connectors/browser/extension` together with this desktop tracker.
- If backend tracker profile is configured in Hub, that policy overrides local prompt/project filtering fields.

---

### Check that it works

1. With the tracker running, use an app (for example Photoshop) and save a file into **Pictures** or **Desktop** (these folders are watched by default).
2. Open **LexAI Hub** for the **same project id** and look for recent activity.

Logs are also written to **`agent_events.log`** in the same folder as the `.exe`.

---

### Install (advanced: Python)

If you prefer to run from source: install **Python 3.10+**, then in this folder run:

```text
pip install -r requirements.txt
python main.py
```

Use the same **`.env`** file next to `main.py`.

### Desktop UI (optional)

From this folder, you can run a small **Tkinter** window for login, project pick/create, Hub tracker policy, and start/stop tracking (CLI/headless mode is unchanged):

```text
python main.py --gui
```

Tokens are stored in the OS secure store (Windows Credential Manager via `keyring`); general settings are saved under `%APPDATA%\\LexAI\\tracker_app_config.json` on Windows.

---

### Troubleshooting

| Problem | What to try |
|--------|-------------|
| Nothing shows in the web app | In tracker startup logs, verify `Tagging events with project_id=...` equals Hub URL `project_id=...`. Also verify `Sending events to backend: ...` uses the same host as Hub Network request `.../api/v2/projects/{id}/agent-events`. |
| Console shows events but Hub is empty | You likely edited a different folder's `.env`. Check startup log `Env file: ... (loaded)` and edit that exact path. |
| “Backend POST failed” in the console | Internet or server issue. Try again later or ask your admin for the correct **`LEXAI_AGENT_BACKEND_BASE`**. |
| Antivirus blocks the `.exe` | Allow the app or use the Python method above. |

---

## 한국어

### 이 프로그램이 하는 일

**Windows용 추적 프로그램**입니다. 실행해 두면 어떤 프로그램을 쓰는지, 사진/문서 폴더에 파일을 저장·내보내는지 감지합니다. **LexAI 웹 앱**의 프로젝트와 연결해 두면 **프로젝트 홈**에 활동이 표시될 수 있습니다.

웹사이트에서 받은 **`LexAI-Tracker.exe`** 만 쓰면 **Python 설치는 필요 없습니다.**

---

### 설치 (권장: EXE)

1. LexAI 웹사이트에서 **`LexAI-Tracker-Windows.zip`** 을 다운로드합니다.
2. 원하는 위치에 압축을 풉니다 (예: `문서\LexAI-Tracker`).
3. 폴더 안에 **`LexAI-Tracker.exe`**, **`.env.example`**, **`SETUP.txt`**, **`README`** 가 있는지 확인합니다.

---

### 처음 설정 (3단계)

1. **`LexAI-Tracker.exe`** 를 한 번 실행합니다.  
   - 없으면 `.env` 파일이 `.env.example` 기준으로 자동 생성됩니다.

2. **`.env`** 안에서 **`LEXAI_AGENT_PROJECT_ID`** 를 LexAI 앱의 프로젝트 번호로 맞춥니다.  
   - [LexAI Hub](https://app.lexai.ai.kr/hub) 주소에 `project_id=숫자` 가 있으면 그 **숫자**를 넣습니다.

3. **`.env`** 를 저장합니다. 팀에서 따로 서버를 주지 않았다면 **`LEXAI_AGENT_BACKEND_BASE`** 는 기본값 그대로 두면 됩니다.

> 권장 로그인 설정: `python main.py --configure` 를 한 번 실행하세요.  
> 웹 디바이스 로그인 후 `LEXAI_AGENT_ACCESS_TOKEN` 이 `.env`에 저장됩니다.  
> 기본값 `LEXAI_AGENT_REQUIRE_LOGIN=1` 에서는 이 토큰이 있어야 이벤트가 서버로 전송됩니다.

---

### 실행 방법

- **`LexAI-Tracker.exe`** 를 직접 실행합니다.  
- **검은 콘솔 창**이 뜨고 계속 켜져 있어야 합니다. 작업하는 동안 그대로 둡니다.  
- 끝낼 때는 창을 닫거나 **Ctrl+C** 를 누릅니다.

---

### 프로젝트 범위 추적 + AI 프롬프트 캡처 (신규)

프로젝트 관련 작업만 엄격히 추적하려면 `.env`에 아래를 추가하세요.

```text
LEXAI_AGENT_PROJECT_ROOT=C:\path\to\your\project
LEXAI_AGENT_ALLOWED_TOOLS=gemini,nanobanana,chatgpt,paint,photoshop
LEXAI_AGENT_CAPTURE_AI_PROMPTS=1
LEXAI_AGENT_PROMPT_INCLUDE_KEYWORDS=브랜드명,프로젝트명
LEXAI_AGENT_PROMPT_EXCLUDE_KEYWORDS=개인,비밀번호,은행
```

- `LEXAI_AGENT_PROJECT_ROOT`: 해당 폴더 트리 안의 파일 이벤트만 추적
- `LEXAI_AGENT_ALLOWED_TOOLS`: 지정한 도구 이벤트만 유지
- `LEXAI_AGENT_CAPTURE_AI_PROMPTS=1`: Gemini/ChatGPT/nanobanana 탭에서 복사된 프롬프트를 캡처(베스트에포트)
- include/exclude 키워드로 업무 외 프롬프트 제외 가능
- 현재 버전은 브라우저 전체 기록이 아닌 **프롬프트 미리보기 + 메타데이터**를 수집
- 프롬프트 전송 시점 정확도를 높이려면 `connectors/browser/extension` 브라우저 확장을 함께 사용하세요.
- Hub에서 tracker profile을 저장하면, 해당 정책이 로컬 필터보다 우선 적용됩니다.

---

### 잘 되는지 확인

1. 추적 프로그램을 켠 상태로 포토샵 등을 쓰고, **사진** 또는 **바탕 화면** 등에 파일을 저장해 봅니다 (기본으로 보는 폴더입니다).
2. 같은 **프로젝트 id** 로 **LexAI Hub** 를 열어 최근 활동을 확인합니다.

같은 폴더에 **`agent_events.log`** 파일로도 기록됩니다.

---

### 설치 (고급: Python)

소스로 실행하려면 **Python 3.10 이상**을 설치한 뒤 이 폴더에서:

```text
pip install -r requirements.txt
python main.py
```

**`.env`** 파일은 `main.py` 와 같은 위치에 두면 됩니다.

### 데스크톱 UI

기본 실행(EXE)은 데스크톱 UI를 엽니다. 소스 실행 시에는 `python main.py --gui` 를 사용할 수 있습니다. 로그인·프로젝트 선택/생성·정책 편집·추적 시작/중지를 할 수 있고, 토큰은 OS 보안 저장소에, 그 외 설정은 `%APPDATA%\\LexAI\\tracker_app_config.json` 에 저장됩니다.

레거시 콘솔만 사용하려면 `python main.py --headless` 를 사용하세요.

---

### 문제 해결

| 증상 | 확인할 것 |
|------|-----------|
| 웹에 활동이 안 보임 | 트래커 시작 로그의 `Tagging events with project_id=...` 숫자가 Hub 주소 `project_id=...`와 같은지 확인. 또 `Sending events to backend: ...` 호스트가 Hub Network의 `.../api/v2/projects/{id}/agent-events` 호스트와 같은지 확인 |
| 콘솔엔 이벤트가 쌓이는데 Hub는 비어 있음 | 다른 폴더의 `.env`를 수정했을 가능성이 큽니다. 시작 로그 `Env file: ... (loaded)` 경로의 `.env`를 수정하세요 |
| 콘솔에 Backend 오류 | 인터넷/서버 문제일 수 있음. **`LEXAI_AGENT_BACKEND_BASE`** 를 관리자에게 문의 |
| 백신이 .exe 차단 | 예외 허용하거나 Python 방식으로 실행 |
