# AnythingLLM Workspaces (VS Code / Cursor)

Extension that talks to the **AnythingLLM developer HTTP API** (list/create workspaces, open the UI in a browser). Optionally uses a **local repos HTTP service** (`repos-devtools-server`) to clone or open Git folders under a configured root, from a **Dev tools** webview panel.

## Features

| Area | What it does |
|------|----------------|
| AnythingLLM | List workspaces, open one in the browser, open the web UI. |
| Workspace ensure | If no workspace matches a repo folder name, create it via `POST /api/v1/workspace/new`. |
| Local repos API | Clone (`branch` **test** by default), list git folders, resolve paths — requires `repos-devtools-server`. |

## Requirements

1. **AnythingLLM** reachable at a public base URL (example: `https://ia.enso.4nkweb.com/anythingllm`).
2. An **API key** from AnythingLLM: **Settings → API Keys**.

**Important:** Do **not** put the **nginx Bearer secret** used for `/ollama/` here (see `deploy/nginx/README-ia-enso.md`). AnythingLLM only accepts keys stored in its own app; a wrong value returns `403` and `{"error":"No valid api key found."}`.

3. For **clone / repos-list / repos-load** commands: run **`repos-devtools-server`** on the machine that owns the clone directory (see `../../services/repos-devtools-server/README.md`). Default URL from the editor: `http://127.0.0.1:37140`. If Cursor connects over **SSH** to that host, `127.0.0.1` is the remote machine — no port forward needed. If the editor runs on another PC, set `anythingllm.reposApiBaseUrl` to a tunnel or the server’s reachable address.

## Installation

- **From source:** open `extensions/anythingllm-workspaces` in VS Code / Cursor, **Run → Start Debugging** (Extension Development Host).
- **From VSIX:**  
  `npm install && npm run compile && npx @vscode/vsce package`  
  then **Extensions → … → Install from VSIX…** and pick `anythingllm-workspaces-*.vsix`.

After install or upgrade, run **Developer: Reload Window** if commands are missing.

## Configuration

Open **Settings**, search for **AnythingLLM**, or edit **User** `settings.json`:

| Key | Description |
|-----|-------------|
| `anythingllm.baseUrl` | AnythingLLM public base URL, **no** trailing slash. |
| `anythingllm.apiKey` | API key from AnythingLLM (a leading `Bearer ` prefix is stripped if present). |
| `anythingllm.reposApiBaseUrl` | `repos-devtools-server` base URL, no trailing slash (default `http://127.0.0.1:37140`). |
| `anythingllm.reposApiToken` | Same secret as `REPOS_DEVTOOLS_TOKEN` on the server. |

Use **User** settings so secrets are not committed with a workspace.

## Commands (Command Palette)

Open the palette: **Ctrl+Shift+P** (Windows / Linux) or **Cmd+Shift+P** (macOS).

| Title in palette | Command ID | Action |
|------------------|------------|--------|
| **AnythingLLM: List workspaces** | `anythingllm.listWorkspaces` | Calls `GET /api/v1/workspaces`, pick a workspace, open it in the browser. |
| **AnythingLLM: Open web UI** | `anythingllm.openWebUi` | Opens `anythingllm.baseUrl` in the browser. |
| **AnythingLLM: Dev tools panel** | `anythingllm.openDevToolsPanel` | Opens the Dev tools webview (see below). |

## Dev tools panel

### How to open it

1. **Ctrl+Shift+P** / **Cmd+Shift+P**
2. Type **AnythingLLM: Dev tools panel** (or `dev tools`, `anythingllm`).
3. **Enter**

A side editor tab opens with:

- A **Commands** text area (one command per line)
- **Run** — execute all non-empty lines in order
- **Clear output**
- **Response** — JSON or text from the server / API, or `ERROR: …`

Settings are read **when you click Run**, so you can change `baseUrl` or tokens without reopening the panel.

### Command lines

| Line | Behaviour |
|------|-----------|
| `/repos-clone <git-url>` | `POST /repos-clone` — clone into `REPOS_DEVTOOLS_ROOT`, branch **`test`**. |
| `/repos-clone-sync <url>` | Same as clone, then ensure an AnythingLLM workspace with the **same name as the repo folder**, **Open folder** in the editor, open that workspace in the browser. |
| `repos-list` or `/repos-list` | `GET /repos-list` — git repositories under the server root. |
| `/repos-load <folder-name>` | `POST /repos-load` — verify folder + **Open folder**. |
| `/repos-load-sync <name>` | Same as load + ensure workspace + browser. |
| `/workspace-load <name>` | List workspaces; if none matches by **name** or **slug**, create via API; then open browser. |
| `help` or `/help` | Print built-in help in **Response**. |

**Workspace name:** Matching uses **exact** equality on AnythingLLM `name` or `slug` and the repo folder name you pass. Creation body: `{ "name": "<name>" }`.

**API key vs browser user:** The extension only uses the **developer API key**. Multi-user behaviour is defined by AnythingLLM for that key.

## Ollama

This extension does **not** call Ollama. For OpenAI-compatible URLs such as `https://ia.enso.4nkweb.com/ollama/v1`, configure the editor’s model provider and use the nginx Bearer as documented in `deploy/nginx/README-ia-enso.md`.

## Troubleshooting

| Symptom | Check |
|---------|--------|
| `403` / `No valid api key found` | Use an AnythingLLM **Settings → API Keys** value, not the Ollama nginx Bearer. |
| `401` on clone/list/load | `anythingllm.reposApiToken` must equal `REPOS_DEVTOOLS_TOKEN` on `repos-devtools-server`. |
| `ECONNREFUSED` / fetch failed | Server running? Correct `anythingllm.reposApiBaseUrl`? |
| Command palette has no AnythingLLM entries | Extension enabled? **Developer: Reload Window**. |
| Clone fails | Remote must expose branch **`test`** (or change branch via the HTTP API body, not the one-line panel command). |

## Build

```bash
cd extensions/anythingllm-workspaces
npm install
npm run compile
```

Package: `npx @vscode/vsce package --allow-missing-repository` (Node 20+ recommended for current `vsce`).

## API reference

- AnythingLLM (upstream): Mintplex-Labs **anything-llm** — `server/endpoints/api/workspace/index.js` (routes under `/api`, e.g. `GET /v1/workspaces`, `POST /v1/workspace/new`).
- Local repos: `services/repos-devtools-server/README.md`.

## License

MIT