Get started with TILL

With your agent

Paste the setup prompt into an agent that can run commands on your computer: Claude Code (terminal or desktop app), Cursor or Windsurf. It checks Node, installs TILL, starts the Studio, asks you to click "Try the demo" and connects itself. Read the prompt before you paste it.

You are helping me set up TILL, a local-first Swiss accounting app that runs on my own computer. Do it end to end and explain each step in plain language.

1. TILL runs on macOS and Linux. Check that Node.js is version 22 or newer with `node --version`. If it is missing or older, install or upgrade it for my operating system, then confirm the version.
2. Install TILL with `npm install -g tillbooks@beta`.
3. Start it with `till up` and leave it running. The Studio opens at http://127.0.0.1:8788.
4. Ask me to choose "Try the demo" on the Studio's first screen ("Demo ausprobieren" if it is in German), so we work on a demo company with sample data, not on real books.
5. Connect yourself to the running TILL over MCP at http://127.0.0.1:8788/mcp. If your client only supports stdio, use: {"mcpServers":{"tillbooks":{"command":"npx","args":["-y","tillbooks@beta","mcp"]}}} If you need a restart to load it, tell me.
6. Read https://github.com/tillbooks/tillbooks/blob/HEAD/AGENTS.md for the rules you work under, then show me three things you can do in the demo company.

These rules hold from the first step, even before you read AGENTS.md:
- Work only in the demo company until I say otherwise. Never create, restore or open real books on your own.
- Never read, type or store any password, bank login or EBICS key. I enter those myself.
- By default, wait for my OK before you book anything, move money, grant access or delete data for good. Never try to get around that.

Or add only the MCP server, in one click

The buttons register the stdio server. If you want the Studio as well, run till up beside it.

claude mcp add tillbooks -- npx -y tillbooks@beta mcp

{
  "mcpServers": {
    "tillbooks": {
      "command": "npx",
      "args": [
        "-y",
        "tillbooks@beta",
        "mcp"
      ]
    }
  }
}

Terminal

You need Node.js 22 or newer, on macOS or Linux. node --version tells you which one you have.

The Studio opens in your browser at http://127.0.0.1:8788. It listens on your own machine only.

The first screen asks how you want to start

• Try the demo

  A demo company with sample postings, to look around first. You can delete it later.

• Start your own books

  Enter your company name, and TILL sets up the books with the Kontenrahmen KMU.

• Restore a backup

  A .tillbackup file goes into a fresh workspace. Nothing you have is overwritten.

• Adopt an existing database

  A TILL book already on this computer: choose the file, and TILL opens it where it is. It is never copied or moved.

Inside an agent session

In a sandboxed agent session (a Claude Code or Cowork session in the cloud, for example), TILL runs inside the session itself. Register the server with its books in a file in the session folder; the agent starts it when it needs it. A server added mid-session shows up after a new session or an MCP reconnect.

claude mcp add tillbooks -e TILL_DB_PATH="$PWD/till.db" -- npx -y tillbooks@beta mcp

{
  "mcpServers": {
    "tillbooks": {
      "command": "npx",
      "args": [
        "-y",
        "tillbooks@beta",
        "mcp"
      ],
      "env": {
        "TILL_DB_PATH": "/absolute/path/to/the/session/folder/till.db"
      }
    }
  }
}

A cloud session runs on the vendor's machine, not yours, and its folder is wiped afterwards. Take a backup at the end of every session and keep the file somewhere of your own.