Open Mercato

Open Mercato

Open Mercato Core is MIT licensed

Open Mercato - the AI-Engineering Foundation Framework. Start with 80% done.

Open Mercato is an open-source TypeScript framework on Next.js and PostgreSQL. It ships ready business modules for CRM, ERP, commerce and more, so a new app starts as a working back office. It is built for AI coding agents: Claude Code, Codex and Cursor get the rules and skills that say where code goes, and Cezar, the agentic development IDE, runs each task in its own git worktree and streams it live. It is for teams and developers building business apps and backends, and for business owners who want one.

npx create-mercato-app my-app

No terminal? Open Mercato Cloud gives you the same app in the browser, with Claude Code, Codex and Cezar already inside (account required).

Prefer to delegate? Paste this line into Claude Code, Codex or Cursor:

Read https://raw.githubusercontent.com/open-mercato/open-mercato/main/README.md and follow it for my project, stage by stage. Stop and ask me at every "You decide" and at every open question.

Note

For AI coding agents. To build an app, scaffold it with npx create-mercato-app <name> --preset <classic|empty|crm|wms> --agents all --init-git (or a comma-separated list of claude-code, codex, cursor, github-copilot) and never clone this repository unless the human wants to change Open Mercato Core. If the request is ambiguous, such as "install this repo", ask that one question first. After scaffolding, the app's own AGENTS.md takes over and every task starts with om-help. Work one stage at a time: ask the You decide question and offer the bold default, do Run, confirm every Done when box. Stop at every "You decide" and at the spec's Open Questions.

Quick start · Cloud · Cezar · Modules · Docs · Tutorials and videos · Discord · Contributing

_{Kaldi & Co. is a fictional specialty coffee roaster in Lisbon. The screens on this page are from the app built with the four stages below, with the roaster's own demo data loaded through the API.}

What is Open Mercato

AI code assistants generate code. They do not decide where it goes, how it is layered, or whether it stays consistent across 30 or 50 engineers in a team. Open Mercato gives them a foundation that does:

• Architecture-aware AI harness. Every app ships an AGENTS.md and skills that tell the agent where code, modules, data models and UI belong, how to troubleshoot and how to upgrade, from a data table or a design-system form up to a whole feature with unit and integration tests. The open-mercato/skills collection adds code review, ticketing and debugging.
• Spec-first. Specs live next to the code in .ai/specs/ and drive the agent's work: plan, approve, then implement.
• Start with 80% done. Dozens of business modules already work together: customers, catalog, sales, warehouse, portal, workflows and more (what's in the box).
• Unattended when you want it. Cezar runs the same skills in parallel, on a schedule or on GitHub events, and never merges on its own.
• No lock-in. You own the code. The core is MIT with no per-seat licence; enterprise modules are licensed separately.

Built for CTOs and team leads who already rolled out Cursor or Copilot and noticed it is not enough, and for developers who want to build professional business apps and backends without constantly checking their back.

Get started

Pick your row. Everyone who builds an app goes through the same four stages, and each stage has the same shape: You decide (a question with a bold default), Run (commands or the exact prompt), Done when (checks you can tick), then a screenshot from the Kaldi run. The whole run, from npx to a working module with a business rule and a cafe login, took one agent evening: about 2 hours 10 minutes of wall time, the long parts being the first install and the module build.

No terminal: Open Mercato Cloud

Open Mercato Cloud is a hosted trial workspace (Beta) with the app already initialised. Inside you get:

• the templates crm, classic or empty, demo users, a View as role switcher and a live preview;
• VS Code in the browser and a web terminal;
• Claude Code and Codex, on managed credits by default or on your own subscription (claude auth login --claudeai, codex login --device-auth);
• Cezar, preinstalled as the AI Coding Agent tab (Beta): the default way to drive the agent here;
• PostgreSQL and Redis. There is no Docker inside, and it is not production hosting.

Keep your work: run gh auth login in the web terminal, then use Create repository and Create PR in the portal, or Export sandbox (a tar with your workspace and a database dump). If sign-up says "Email registration is currently closed", you are on the waitlist. Watch the Open Mercato Cloud tour, or follow the video course for non-developers built on the sandbox (Polish only).

Minute 10: a running back office

You decide: which starter? classic (CRM, catalog, sales, warehouse, portal, demo data) · crm · wms · empty. Which agents? all (Claude Code, Codex, Cursor and GitHub Copilot, which gets instructions only, no hooks) · one of them.

Run in a terminal, as is. You need Docker running (Docker Desktop, OrbStack or Colima) and about 8 GB of free RAM; mise installs Node.js 24 and Yarn 4 for you. On Windows use WSL2 and see Developing on Windows. All options: installation guides.

curl https://mise.run | sh && export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:$PATH"
mise use -g node@24 yarn@4      # Node.js 24 and Yarn 4; skip both lines if you already have them
npx create-mercato-app my-app --preset classic --agents all --init-git
cd my-app
docker compose up -d --wait     # PostgreSQL 17 with pgvector, Redis 7, Meilisearch
yarn setup                      # installs, creates .env, migrates, seeds demo data, starts the dev runtime and keeps running

A plain npx create-mercato-app my-app asks these questions plus Git init (its agent default is Claude Code). Without a terminal it silently picks classic, claude-code and no git, so agents always pass the flags and run yarn setup in the background. If docker compose fails, offer Open Mercato Cloud instead. To keep mise after this terminal closes, add eval "$(~/.local/bin/mise activate zsh)" (or bash) to your shell profile. Pushing to GitHub is optional and comes later, in Day 1.

In the Cloud: sign in or request access (registration may be closed, see the waitlist note), create a sandbox from the classic template, wait until it shows Running, then click Open app.

Done when

• the terminal prints Backend URL http://localhost:3000/backend; the logins are admin@acme.com / secret, also superadmin@acme.com and employee@acme.com with the same password (the full box is in .mercato/logs/*-dev-setup-runner.log, or run yarn setup --verbose)
• you open http://localhost:3000/backend and sign in as admin@acme.com / secret (Cloud: Open app, then View as Admin). Open it as localhost, not 127.0.0.1 or the machine's IP: the dev server serves its scripts to localhost only, so other hosts get a page that never finishes loading (on a remote box, use an SSH tunnel)
• for agents: curl -s -o /dev/null -w '%{http_code}' localhost:3000/login prints 200 and .agents/skills/om-help exists (if not, run yarn install-skills)
• Customers lists demo companies and people, and Sales lists demo orders

In the Kaldi run this stage took about 11 minutes from npx to a working login (about 7 minutes of that was installing dependencies and the first setup, on an 8-core Linux box with warm caches). Stuck? See troubleshooting.

Start the Coding Agent

Your app is running. Now start the agent that builds on it. The quickest way is your agent's CLI in the app folder: claude, codex or agent (Cursor CLI, formerly cursor-agent). For the best developer experience, use Cezar, the open-source (MIT) agentic development IDE: you type a task, Cezar runs the agent in its own git worktree and streams the run live, with its changes, commits and a terminal one click away.

npx cezar-run                                        # in the app folder; opens Cezar at `http://localhost:4321`

It works with seven agent CLIs: Claude Code, Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Junie and pi, runs the om-* skills in parallel, on a schedule or on GitHub events, and never merges on its own.

npx cezar-run run "<task>"                           # one task, headless
npx cezar-run server-install --platform ubuntu-vps   # always on, 24/7 (or --platform macosx-ngrok)

• What it does: locally each task runs in its own git worktree. Automations start tasks on a schedule, when a GitHub PR is opened (needs the GitHub remote from Day 1), on reviews or issues, or from Jira and Linear, and a task can spawn child tasks.
• What it needs: Node.js 20+ and one agent CLI that is already logged in. git and gh are optional; you need them for pull requests and the GitHub tab.
• Where it runs: in any repository (it is not specific to Open Mercato), on your laptop, on a server, or in Open Mercato Cloud as the AI Coding Agent tab (Beta).

You will hand it real work in Month 1. See it first in the Cezar demo video.

Build the missing 20% with your agent

Buy vs. build? Now, you can have best of both. Use Open Mercato enterprise-ready business features like CRM, Sales, OMS, Encryption, and build the remaining 20% that really makes the difference for your business. Watch: Start with 80% done

Your app already knows how it is built. Start every task with om-help: /om-help in Claude Code, $om-help in Codex, or the sentence Use om-help: <task> in any agent. It only routes: it returns the ordered list of guides and skills, why each one is needed, the delivery shape and the smallest set of checks. It never writes code, plans your business or loads data.

Hour 1: a route and a spec

You decide: what does your business need that the demo does not do? Use the Kaldi & Co. example as it is to see the flow, or describe your own business in two or three sentences. Kaldi's answer: "We buy green-coffee lots and roast three blends, Alfama Espresso, Belem Filter and Douro Decaf. We sell wholesale to about 40 cafes that order weekly. We lend espresso machines and send technicians, and every lot needs origin evidence under the EU deforestation rules."

Run: paste this into your agent.

Use om-help: <your sentences>. Tell me which guides and skills this needs. Then write a spec with om-spec-writing for the first slice and stop at Open Questions. No code yet.

In the Cloud: open the AI Coding Agent tab and start a task with the same prompt, or run claude (or codex) in the web terminal and paste it there.

Done when

• om-help returned the ordered guides and skills and the checks to run (about 3 minutes in the Kaldi run)
• a spec exists at .ai/specs/<date>-<slug>.md (about 10 minutes)
• you answered every Open Question; the agent waits there until you do

In the Kaldi run, the om-help route plus the spec work mapped the business like this:

Day 1: the missing 20% as a module

You decide: read the spec. Approve it · change it. Where should the work land? locally, phase by phase · as a pull request. If the spec still lists open questions, the agent refuses to build and asks you to answer them; "use the recommended defaults" is a valid answer.

Run: paste this into your agent.

Implement the approved spec with om-implement-spec, phase by phase. Show me the SQL from yarn db:generate and ask me before yarn db:migrate. Then run the full check.

As a pull request instead: /om-auto-implement-spec .ai/specs/<date>-<slug>.md opens its own PR. It needs a GitHub remote, which you add once with git add -A && git commit -m "Initial commit" && gh repo create --private --source=. --remote=origin --push (gh 2.82.1+ and jq); without one, agents report "PR delivery unavailable" and work locally. Either way, this is what the agent runs, so you can follow along:

# creates src/modules/roast_batches/ and adds to src/modules.ts:
#   enabledModules.push({ id: 'roast_batches', from: '@app' })
yarn generate
yarn db:generate                    # writes the migration: review the SQL, the agent asks you
yarn db:migrate                     # only after your yes
yarn mercato auth sync-role-acls    # without it, even admin does not see the new page
# then stop and start `yarn dev` once: the running dev runtime does not pick up a new entity,
# and the new API answers 500 until it restarts (the menu entry can take up to 5 minutes, the role cache)
yarn generate && yarn typecheck && yarn lint && yarn ds:check && yarn test && yarn build
yarn test:integration:ephemeral     # integration tests, needs Docker

In the Cloud: the same prompt in the AI Coding Agent tab or the web terminal. PostgreSQL and Redis already run, so there is nothing to start, and the new page appears in the live preview.

Important

Rules for agents in an app. Never edit node_modules or .mercato/generated/**. Never run yarn db:greenfield, yarn reinstall or yarn setup --reinstall without asking. Ask before yarn db:migrate. Follow the app's AGENTS.md.

Done when

• Roast batches is in the admin menu with a list and a detail page
• its REST API appears under /backend/docs (served from /api/docs/openapi) and is guarded by the new permissions
• the full check above exits 0 (about 45 minutes in the Kaldi run, from approved spec to green module tests, including the restart above).

Month 1: unattended work with Cezar, upgrades, production

You decide: what runs without you? **a review