Getting started

Why connect an agent at all

Everything so far happens on the map in your browser. Connecting an AI assistant, like Claude Code, is what lets it actually read that map for context before it starts building, and add new features back onto it as it works. Without this step, you'd be stuck copying and pasting between Mapwright and your assistant by hand.

This is the one part of Mapwright that happens in a terminal instead of a browser. If you've never used one before, that's okay. Every command below does one specific thing, and we'll explain what to expect from each one.

What you'll need

You'll be working in whatever terminal your AI coding assistant already uses (for Claude Code, that's the same terminal it runs in). No separate account or sign-up is required. You'll connect using your existing Mapwright account.

Step 1: Install the connector

The connector is a small command-line program called the Mapwright CLI (short for "command line interface," just a fancy way of saying "a program you talk to by typing commands"). Run this once:

npm install -g @mapwrightapp/cli

Step 2: Generate a key and log in

Visit your account's API Keys page in Mapwright and generate a new key. Think of this key as a password just for this connection, one you can revoke at any time without affecting your regular login. Copy it, then run:

mapwright auth login

Paste the key when asked. Your input is hidden as you paste it, the same way a password field works.

Step 3: Connect a project

From the folder where you're working with your AI assistant, link it to an existing Mapwright project:

mapwright init --project "<your project name>"

Starting something brand new instead? This creates a project with its starting map already in place, and links to it in one step:

mapwright project create "<new project name>"

Step 4: Check the connection

mapwright status

This confirms everything is working: the connector is installed, you're logged in, and a project is linked. If anything's missing, it'll tell you exactly what.

Step 5: Teach your assistant how to use it

Run this once, in the same folder:

npx skills add MapWrightApp/mapwright-skills

This adds a set of instructions that teach your AI assistant how to read and update your Mapwright map on its own. Once it's there, you don't need to run any commands yourself. Just ask your assistant things like "what's on my Mapwright map?" or "add a feature called X", and it takes care of the rest.

What your assistant can and can't do on its own

Your assistant can read your map, your specs, and your task list, and it can add new feature cards back onto the map as it works. Every card it adds is visibly marked as created by an agent, so you can always tell what came from a conversation with it versus what you added yourself.

Generating a brand new spec or task list still happens from the Mapwright app in your browser, the same one-click action described in turning ideas into specs. That's a deliberate choice: those actions have a small cost attached, and we'd rather you see and approve that spend happening than have it happen invisibly in the background.