Skip to main content
Glama
README.md
# twinlens

A lens is a public AI page that answers questions from its
owner's own material, with citations. twinlens is a small
forwarding client for the hosted lens service: it creates a
lens from a profile, adds knowledge to an unclaimed lens, and
reports how ingestion is going.

Creation is anonymous by default — no account, no token. An
anonymously created lens is live immediately at its share
URL, can be claimed afterwards through its claim URL, and
expires after 30 days if it never is. If you do have an
account, setting `MINDOLA_SESSION_TOKEN` sends it as a Bearer
token and the lens is created directly under that account.
The endpoint can be overridden with `MINDOLA_MCP_URL`
(default `https://app.mindola.ai/mcp/lens`).

**Creation etiquette (part of the contract):** summarize the
proposed profile and get the user's explicit confirmation
*before* calling create, and only include information the
user provided or confirmed. Never fill a profile with
guesses.

## CLI

```bash
npx @reneturcios/twinlens create '{"displayName":"Ada Example","tone":"warm","facts":["Works on compilers"]}'
npx @reneturcios/twinlens add-knowledge '{"lens_token":"abc123","items":[{"type":"text","content":"A note","title":"Note"}]}'
npx @reneturcios/twinlens status abc123
npx @reneturcios/twinlens --version
```

`create` takes the profile as one JSON object (every field
optional). `add-knowledge` takes `{lens_token, items}` the
same way. `status` takes the share token (the part of the
share URL after `/me/`) directly.

Exit codes: `0` on success, `1` on a runtime error (including
an upstream rejection, e.g. adding knowledge to a claimed
lens), `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/twinlens mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "twinlens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/twinlens", "mcp"]
    }
  }
}
```

### Tools

- `create_digital_twin_lens` — Create a lens from a
  user-confirmed profile. All fields optional: `displayName`
  (≤80 chars), `tagline`, `bio`, `context`, `audience`
  (≤500 chars), `sourceSummary`, `topicName` (≤80 chars),
  `locale` (BCP-47), `tone` (`warm` | `neutral` |
  `professional` | `playful`), `accentColor`, `expertise`
  (string[]), `boundaries` (string[]), `facts` (string[],
  ≤30), `suggestedPrompts` (string[], ≤4), `vibeWords`
  (string[], ≤4). Read the result from `structuredContent`:
  `shareUrl`, `claimUrl`, `manageUrl`, `claimRequired`,
  `expiresAt`, `factCount`.
- `add_lens_knowledge` — Add up to 20 items to an unclaimed
  lens. `lens_token` (string, required), `items` (required):
  each `{type: "text" | "url", content (≤20000 chars),
  title? (≤80 chars)}`. Items ingest in the background.
- `get_lens_status` — `lens_token` (string, required).
  Reports `claimed` and `knowledge` totals (`total`, `ready`,
  `pending`, `failed`); poll with it after adding knowledge
  until `pending` reaches zero.

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/twinlens
docker run --rm ghcr.io/cloudcorprecords/twinlens status abc123
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios