Getting Started

Scaffold a project

init drops a complete, working project workspace in the target directory — your apps live under apps/<id>/, starting with one. With no flag it scaffolds the empty template — a blank starter with one welcome note and an empty data/, so you and your agent build it up from your own files.

npx openislands init my-dashboard
cd my-dashboard

Want a populated example instead? Pass --template:

npx openislands init my-dashboard --template finance

finance is the flagship — net worth, allocation, holdings, and transactions as typed islands over CSVs you own. health and operations are there too.

Connect your agent over MCP

init already did this. The scaffold ships a local .mcp.json wiring the @openislands/mcp server, an AGENTS.md, and the OpenIslands skill under .agents/skills/openislands/ — so any agent that reads the project picks up the execute tool and the conventions. Open the folder in your agent and you're connected.

If you're wiring it into a project by hand, this is the config it expects, pointed at the project root that holds your apps under apps/<id>/:

{
  "mcpServers": {
    "openislands": {
      "command": "npx",
      "args": ["-y", "@openislands/mcp", "."]
    }
  }
}

npx runs the latest published server on demand; its -y flag skips the install prompt, so there's nothing to install globally. The last argument is the project directory — . if your agent runs from inside it.

To add the skill to a project that doesn't have it (or to your own agent setup):

npx skills add lukaisailovic/openislands --skill openislands

Serve it so you can watch

npx openislands serve

This renders the dashboard at 127.0.0.1:4321, querying your files on every request. Leave it running — each edit the agent applies live-updates the page over SSE.

Prompt the agent

Now just ask. The agent grounds itself first (it reads the manifest, the dataset schema, and real rows), stages the change so you see a diff before anything is written, applies it with a snapshot of the prior version, and rolls back if the result is wrong. A binding to a column that doesn't exist comes back as a named error, so a broken dashboard never ships.

Prompts that work well:

Drop data/spending.csv into the project and add a page that charts monthly spend by category.

Give the net-worth KPI a delta against last month, and add a gauge for my savings-rate goal.