Getting Started

init drops a complete, working project in the target directory. 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.

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 tools 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 directory that holds app/manifest.json:

{
  "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

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.

Now just ask. The agent grounds itself first (it reads the manifest, the dataset schema, and real rows), proposes 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.