# Tidy – Open-Source Paper

> Source: <https://github.com/tidydesigns/tidy>
> Published: 2026-10-12 19:13:44+00:00

Tidy is a product canvas for designers, engineers and agents. It includes an editable design workspace, collaboration, a webpage-capture extension and an MCP server for working with designs through agents.

Tidy is open source under the [Apache License 2.0](https://github.com/tidydesigns/tidy/blob/main/LICENSE). Bundled third-party
assets retain their own licenses; see [third-party notices](https://github.com/tidydesigns/tidy/blob/main/THIRD_PARTY_NOTICES.md).

Requirements: Bun 1.3.14, Git, Docker Compose and PostgreSQL 17 command-line tools for the disposable database tests. Use your own development mail and optional provider applications; the source contains no hosted-service credentials.

```
bun install --frozen-lockfile
docker compose up -d --wait
cp apps/web/.env.example apps/web/.env.local
```

Generate `BETTER_AUTH_SECRET` and a separate base64-encoded 32-byte
`VAULT_ENCRYPTION_KEY` in the app's local environment file. The example database
URL points to loopback PostgreSQL on port 55432; its password is a development
fixture, never a production credential. Do not inherit a production database URL
when running local commands. Fresh Docker databases apply ordered migrations
automatically; existing databases need the missing files from `migrations/`.

Password accounts must verify email before sign-in. Configure your own Cloudflare
Email Sending token, account and sender before creating accounts; disable email
previews that retain verification/reset links. Optional social sign-in,
connectors, analytics, billing and native agents stay unconfigured until you add
their own environment values in [the environment example](https://github.com/tidydesigns/tidy/blob/main/apps/web/.env.example).

```
bun dev
# In another terminal, for local realtime presence:
bun dev:realtime
```

Open `http://localhost:3000`. `bun dev:site` starts the optional landing page on
port 3001. `bun dev:extension` starts the WXT extension; its default server is
localhost. To load it in your own Chrome profile, run `bun run build:extension`,
enable Developer mode at `chrome://extensions`, and load unpacked
`apps/extension/.output/chrome-mv3`. Set `WXT_BELLA_URL` to your own HTTPS app
origin when building for distribution.

Stop the local database with `docker compose down`; adding `-v` removes its data.
Local Node development bypasses Worker-specific shared attempt limits. See
[self-hosting](#self-hosting) before exposing any deployment publicly.

| Workspace | Purpose | 
|---|---|
| `apps/web` | Next.js application and Cloudflare Worker | 
| `apps/site` | Optional static landing page | 
| `apps/extension` | WXT webpage capture extension | 
| `apps/gpt-plugin` | Agent plugin, skill and preview UI | 
| `packages/design` | Browser-safe document and capture schemas | 
| `packages/design-renderer` | Shared editor, preview and export rendering | 
| `packages/ui` | Shared UI controls | 

Workspace commands run from the root: `bun typecheck`, `bun lint`, `bun test` and
`bun run build`. Use `bun run build:worker` for the Cloudflare Webpack/OpenNext build.
Source archives and new repositories with no commits are supported. You can set
`NEXT_PUBLIC_APP_VERSION` for a release label independent of Git.

Database fixtures own disposable PostgreSQL clusters and simulate provider HTTP.
Run the relevant suites explicitly; default unit tests skip database suites.
The account suite is `bun run test:account-controls`; `package.json` also lists
auth, MCP, agents, plans, files, versions, images, clipboard, runtime, storage, multiplayer
and connector suites. See [contributing](https://github.com/tidydesigns/tidy/blob/main/CONTRIBUTING.md) for required checks.

Run `bun run bench:mcp` for authenticated MCP HTTP latency, throughput, query-count
and payload benchmarks against a disposable local database. See the
[MCP performance report](https://github.com/tidydesigns/tidy/blob/main/docs/performance/mcp-2026-10.md) for reproducible comparisons
and the distinction between local measurements and hosted Worker performance.

The hosted app uses Cloudflare Workers, Hyperdrive, private R2 buckets, Images
and Durable Objects. The tracked `apps/web/wrangler.jsonc` is a build template.
Copy it to the ignored `apps/web/wrangler.deploy.jsonc` and configure your own
Worker name, matching `WORKER_SELF_REFERENCE`, domain, Hyperdrive connection and
storage bindings. Retain the Durable Object bindings and migration tags.

Use separate runtime and migration database logins. Apply ordered
[database migrations](https://github.com/tidydesigns/tidy/blob/main/migrations/README.md) and the restricted runtime grants
before starting the app. Configure `BETTER_AUTH_URL` to your HTTPS origin and
supply runtime variables and secrets through Cloudflare, using
`apps/web/.env.example` as the configuration reference. Keep secrets out of
Wrangler files and `NEXT_PUBLIC_*` variables. Preserve both auth and encryption
secrets when restoring an existing database.

From the repository root, build and deploy using your private configuration:

```
bun run build:worker
TIDY_DEPLOY_CONFIG=./wrangler.deploy.jsonc bun run deploy:worker
```

The configuration path is relative to `apps/web`. Preview and production need
separate secrets, databases and buckets. Test authentication and workspace
isolation with two users before accepting real data. Public Node deployments
require an equivalent shared limiter, private storage and realtime transport;
the Node commands support local development.

See the [agent plugin](https://github.com/tidydesigns/tidy/blob/main/apps/gpt-plugin/README.md) and
[native runner](https://github.com/tidydesigns/tidy/blob/main/apps/web/agent-runner/README.md) for agent setup.
CI uses synthetic fixtures and a read-only token. Report vulnerabilities privately
using the process in [SECURITY.md](https://github.com/tidydesigns/tidy/blob/main/SECURITY.md).