# Loomscope

**Agent work, visible.** Loomscope is a password-protected dashboard and a Remote MCP observer for long-running Codex work. It records concise task milestones rather than private reasoning or raw logs.

## Why one deployment

This repository is intentionally a single Cloudflare Worker deployment:

- `src/web/` is the Vite + React + Tailwind dashboard.
- `src/worker/` is the independently testable HTTP, auth, MCP, validation, and storage boundary.
- `migrations/` owns D1 schema changes.
- `plugins/loomscope-observer/` contains the installable Codex plugin: its reporting Skill and Remote MCP configuration.

The UI and API share an origin, so no CORS policy or second deployment needs to be maintained. Static assets are served by the Worker, while `/api/*` and `/mcp` remain dynamic.

## Setup

1. Install dependencies: `pnpm install`.
2. Copy `.dev.vars.example` to `.dev.vars` and set three distinct long secrets.
3. Authenticate Wrangler: `pnpm exec wrangler login`.
4. Apply schema: `pnpm exec wrangler d1 migrations apply loomscope --remote`.
5. Check locally: `pnpm build`, then `pnpm dev:worker`.
6. Deploy: `pnpm deploy`.

`wrangler.jsonc` is already bound to the production `loomscope` D1 database. If you intentionally deploy this project to a different Cloudflare account, create a new D1 database and replace that binding's `database_id` first.

The deployment configuration provisions `loomscope.vortexislabs.com` as the Worker custom domain. Before the first production deploy, set production secrets without putting them in `wrangler.jsonc`:

```sh
pnpm exec wrangler secret put DASHBOARD_PASSWORD
pnpm exec wrangler secret put DASHBOARD_SESSION_SECRET
pnpm exec wrangler secret put MCP_WRITE_TOKEN
```

## Codex integration

The `plugins/loomscope-observer/` directory is the source for the `loomscope-observer` Codex plugin. It contains the reporting Skill and the deployed Remote MCP endpoint. Start a new Codex thread after installation so its Skill and MCP tools are discovered.

The plugin reads its write token from `LOOMSCOPE_MCP_TOKEN`. For Codex CLI, set the variable before starting Codex:

```sh
export LOOMSCOPE_MCP_TOKEN="your-agent-write-token"
codex
```

The Worker exposes `observe_start`, `observe_report`, and `observe_finish`. The dashboard only accepts its own signed, password-created session; the MCP token has no read access.

## Commands

```sh
pnpm lint
pnpm test
pnpm build
pnpm check
pnpm dev:worker
pnpm deploy
```

## Data boundaries

D1 stores normalized projects, agents, runs, and event summaries. Large artifacts are represented by links in the initial release; add R2 only when artifact upload becomes a product requirement. This keeps reporting fast and avoids turning the observability database into an unbounded log store.