# Molecule.dev

> An AI-first, composable package ecosystem for building full-stack apps that scale. Molecule.dev generates real, production-grade full-stack code from 1,000+ composable, swappable `@molecule/*` packages — not throwaway prototypes. Its bond system keeps generated code decoupled: swap a provider (Stripe → Apple Pay, PostgreSQL → MySQL, one OAuth provider for another) by changing one line, not rewriting the app.

## Core ideas

- [Documentation](https://www.molecule.dev/docs): the full docs section — getting started, core concepts (packages, bonds, templates, project structure), and guides (CLI, MCP, deploy, database, environment, teams, personal API tokens) — organized with search, one page per topic at `https://www.molecule.dev/docs/<slug>`.
- [How it works](https://www.molecule.dev/): describe an app in plain language; an AI harness composes the right packages and wires them via the bond system.
- [Templates](https://www.molecule.dev/templates): start from a real full-stack app and shape it with AI — no blank-page setup. Each template has its own page at `https://www.molecule.dev/templates/<slug>` (screens, data model, API handlers, the packages it is built from).
- [CLI (mlcl)](https://www.molecule.dev/mlcl): the open-source command line — `mlcl create <name> --template <slug>`, add/swap packages, `env check` for missing env vars, deploy. Official page: `https://www.molecule.dev/mlcl`.
- [Packages](https://www.molecule.dev/packages): every `@molecule/*` package, grouped by category, each with its own page at `https://www.molecule.dev/packages/<name>` (the name without the `@molecule/` scope): what it is, how it works, the install command, and its generated reference. All of them, concatenated: [llms-full.txt](https://www.molecule.dev/llms-full.txt).
- [Pricing](https://www.molecule.dev/pricing): start free and scale as your app grows.

## For AI agents — molecule's full capability surface

Building an app for a user? Molecule gives you (and them) production-grade TypeScript from composable `@molecule/*` packages behind swappable bonds. The output is a conventional, fully-owned project.

### Discover what exists
- **Packages**: 1013+ composable packages — search at https://www.molecule.dev/packages or `mlcl search <capability>` (e.g. "payments", "send emails", "social login")
- **Templates**: 152+ flagship apps (blog, CRM, team-chat, online-store, kanban, hotel-booking, AI chatbot builder, …) — browse https://www.molecule.dev/templates or `mlcl templates`
- **Full package reference**: https://www.molecule.dev/llms-full.txt (every package's API, examples, wiring)
- **Per-package docs**: every installed package carries a generated README at `node_modules/@molecule/<name>/README.md`

### Scaffold and build (CLI)
- `mlcl create <name> --template <slug> --no-interactive --json` — scaffold a flagship app unattended
- `mlcl create <name> --type full-stack --framework react --packages @molecule/... --no-interactive` — custom stack
- `mlcl add @molecule/<name> --inject` — install + wire a capability (bonds + migrations + routes in one step)
- `mlcl swap @molecule/<new-provider>` — change a provider (Postgres → MySQL, Stripe → PayPal) without rewriting

### Structured tools (MCP server)
- Install with `mlcl mcp install` — works with Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, Kiro, Trae, Zed, Amp, Crush, Cline, VS Code, and any MCP client
- Tools: `search_packages`, `list_templates`, `scaffold_project`, `add_package`, `swap_provider`, `read_package_doc`, `agent_init`, `login`, `login_poll`, `logout`, `whoami`, `list_devices`, `revoke_device`, `list_projects`, `create_api_key`, `check_env_vars`, `list_env_vars`, `get_env_var`, `set_env_var`, `unset_env_var`, `push_env_vars`, `pull_env_vars`, `export_project`, `embed_text`, `translate`, `text_to_speech`, `transcribe_audio`, `moderate_content`, `extract_text`, `web_search`, `geocode`, `reverse_geocode`, `ai_decision`, `transform_image`, `generate_image`, `submit_agent_run`, `get_agent_run`, `cancel_agent_run`, `import_transcripts`, `list_transcripts`, `remove_transcript`, `share_visibility`, `check_project`
- Capability services (no vendor account needed — metered to your molecule project, also available in app code via `@molecule/*` bonds): embeddings (`embed_text`), translation (`translate`), speech (`text_to_speech`, `transcribe_audio`), moderation (`moderate_content`), OCR (`extract_text`), web search (`web_search`), geocoding (`geocode` / `reverse_geocode`), AI decisions (`ai_decision`), image transformation (`transform_image`), image generation (`generate_image`), unattended agent runs (`submit_agent_run` / `get_agent_run`)
- Hosted endpoint (no local install): `https://mcp.molecule.dev/mcp`
- Resource: `molecule://conventions` — the molecule way (bonds, ClassMap, i18n, migrations)

### Platform operations (after `mlcl login`, or with `MOLECULE_TOKEN` set to a personal API token)
- Personal API tokens: `mlcl token create <name> [--expires-in-days N] [--json]`, `mlcl token list [--json]`, `mlcl token revoke <id-or-name>` — named, revocable tokens (expire in at most 365 days) for CI and scripts; send as `Authorization: Bearer <token>` or set `MOLECULE_TOKEN` for mlcl and the MCP server. Guide: https://www.molecule.dev/docs/api-tokens
- Deploy: `mlcl deploy --project <id> --follow` — same pipeline as the molecule.dev IDE's Deploy button
- Projects: `mlcl project list/get/open` — list, inspect, deep-link to IDE
- Sandboxes: `mlcl sandbox status/start/stop/exec/restart --project <id>`
- Snapshots: `mlcl snapshot create/list/restore/rm --project <id>`
- Git: `mlcl git push/pull --project <id>` — platform-mediated
- Environment: `mlcl env list/get/set/unset` (local) + `env push/pull --project <id>` (platform sync) + `mlcl env check` — which env vars the app needs (code reads + installed-package declarations) and which are missing from your .env (`--fix` appends the fixable ones)
- Database: `mlcl db migrate/reset/console/url` (local) + `db info/tables/query/backup --project <id>` (cloud)
- Domains: `mlcl domain list/add/verify/rm --project <id>`
- API keys: `mlcl apikey list/create/rm --project <id>`
- Team: `mlcl team list/invite/revoke/set-role/rm --project <id>`
- Shares: `mlcl share list/create/rm/visibility --project <id>`
- Session transcripts: `mlcl transcripts import/list/rm --project <id>`
- Builds: `mlcl build mobile/desktop/list/status --project <id>`
- Logs: `mlcl logs --project <id> [--stream]`
- Verify: `mlcl check [--steps typecheck,lint,build,unit,e2e] [--e2e "<filter>"]` — runs the project's own checks (discovered from its scripts) concurrently and prints one compact report with the first actionable errors; MCP: `check_project`
- CI workflows: `mlcl deploy workflow-github/workflow-gitlab --project <id> [--apply]`
- Usage: `mlcl usage [--project <id>]` / `mlcl usage tiers`

### Make any agent molecule-aware
- `mlcl agent init` — writes the molecule conventions + quickstart into AGENTS.md (the cross-harness standard Claude Code, Codex, Cursor, Pi, … all read) + harness-native files (.cursor/rules, .claude/skills, .gemini/extensions, .windsurf/rules)

### In every molecule-scaffolded project
- `AGENTS.md` at the project root carries the full conventions — any agent that opens the project immediately knows how to work with bonds, ClassMap styling, handler patterns, and migrations
- `README.md` describes the architecture and growth commands
- `.env.example` lists every secret the app expects
- `node_modules/@molecule/*/README.md` — per-package usage docs (always current, generated from source)

## What's new

- [Changelog](https://www.molecule.dev/changelog): what shipped, by day — `@molecule/*` package releases and molecule.dev changes. Feeds: [RSS](https://www.molecule.dev/changelog.xml), [Atom](https://www.molecule.dev/changelog.atom).
- [Showcase](https://www.molecule.dev/showcase): apps built with Molecule, including Molecule itself.
- [Blog](https://www.molecule.dev/blog/): engineering notes and updates. Feeds: [RSS](https://www.molecule.dev/blog/feed.xml), [Atom](https://www.molecule.dev/blog/atom.xml). Machine-readable index: [llms.txt](https://www.molecule.dev/blog/llms.txt), [posts.json](https://www.molecule.dev/blog/posts.json).

## Resources

- [GitHub (molecule)](https://github.com/molecule-dev/molecule): the open-source package ecosystem.
- [Security](https://www.molecule.dev/security): what Molecule.dev does to protect your projects, stated plainly.
- [Licensing](https://www.molecule.dev/licensing): the packages are Apache-2.0; the apps you build are yours.

## Legal

- [Terms](https://www.molecule.dev/terms)
- [Privacy](https://www.molecule.dev/privacy)
- [DPA](https://www.molecule.dev/dpa)