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.

Related MCP server: KeyStack

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:

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:

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

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.