Quickstart

#Set up

1. Create an account

   Go to chronos.2090.tech/signup and continue with GitHub, or with your email and the code we send you. A new account is on the free plan with an org of its own.

2. Connect the project folder

   In the folder of the app you’re building, install the CLI and run chronos init. It signs you in (it prints a code and opens the browser), finds or makes the project’s database, and writes the files every agent in the folder reads.

   curl -fsSL https://github.com/Abhishekxdg/chronosdb/releases/latest/download/install.sh | shcd myappchronos init

   chronos: to sign in to Chronos Cloud, open https://chronos.2090.tech/device and enter the code WDJB-MJHTchronos: signed in as ada (key saved in ~/.config/chronos/cloud.toml)chronos: project myapp (prj_...), database db_... (running)chronos: DATABASE_URL=postgres://app:****@.../main?sslmode=require&options=endpoint%3Ddb_... (in .env)chronos: wrote .chronos/project.json, .mcp.json, .env, .gitignore, CLAUDE.mdOpen Claude Code here and ask it to build.

   Rather not install anything? Add the MCP server to your agent instead (the dashboard’s Connect page has the line for each tool) and ask it to set up the project: it calls setup_project and writes the same files. See Coding agents.

3. Open your agent

   Open Claude Code (or Cursor, Codex, VS Code) in the folder. The first time it uses the database it opens the browser to connect: allow it. From then on it has the Chronos tools and the CLAUDE.md block that says how to use them.

#The first change

Ask for something that touches data: “add a plan column to users, default free, and mark the users in vip.csv as pro”. The agent:

1. calls describe to read the schema, then fork to make a world (add-plans), an instant copy of main;
2. runs the migration and the update with sql on that world: main, and your app, see nothing yet;
3. runs your app’s tests against the world, by pointing DATABASE_URL at it (/add-plans in place of /main);
4. shows you the diff: one schema change, then the rows, field by field;
5. calls merge. In development, with no rules set, it lands at once.

Open the dashboard: Worlds shows the world while it’s open, Activity shows the fork, writes and merge, and History can read any table as it was before the merge.

#Add a rule

Agents merge on their own until you say otherwise. Start every agent with one rule: no merge that deletes rows lands without a person. In the dashboard’s SQL editor:

create merge policy careful with (max_rows = 500, max_deletes = 0, review_tables = 'payments');show agents;                                          -- your agent is claude-<you>-<project>alter agent "claude-ada-myapp" set (policy = 'careful');

Now a merge that changes more than 500 rows, deletes any row, or touches payments waits for you. Everything else still lands on its own. The Policies page does the same without SQL, and shows which agents keep to which policy.

#Review a held change

Ask the agent to “delete test accounts”. Its merge is refused with the reason, and the world waits:

merging cleanup-test-users needs a person's review (merge policy careful: it deletes 37 rows (at most 0)); it's queued (SHOW REVIEWS)

The agent stops and gives you the link. In Reviews you see the world’s changes, deleted rows first with what they held, the rule it broke, and whether the agent wrote more since it asked. Then:

#Your app and tests

Your app connects with DATABASE_URL from .env, like any Postgres: it reads and writes main. To run the tests against an agent’s world, change the database name:

# mainpsql "$DATABASE_URL" -c 'select count(*) from users'# the world add-plans: same URL, its name in place of mainDATABASE_URL=$(echo "$DATABASE_URL" | sed 's#/main?#/add-plans?#') npm test

See Your app for drivers, ORMs and reading the past.

#Next

• Core concepts: what a world is, how merges decide, what agents may do.
• Merge policies: every rule, and recipes for common agents.
• Merge checks: rules about the data every merge must keep.
• Time travel and undo: reading the past and taking changes back.