Routecraft

Routecraft is a CLI for agents that build bicycle routes one road or path at a time.

The CLI shows connected choices and source evidence. The agent selects each segment. Routecraft validates every change and records an immutable revision.

Routecraft leaves road ranking and route decisions to the agent. It does not generate loops.

What Routecraft provides

• Road, path, surface, access, speed, control, and bicycle facility data from OpenStreetMap
• Connected route choices that keep each exact segment reference
• Weather, elevation, nearby places, and route comparison data
• Optional Google map, aerial, and Street View images
• Exact edits, hand-drawn connectors, and GPX or GeoJSON export with a Routecraft provenance file
• The same command contracts through a CLI and an MCP server

Source data can be incomplete. Routecraft reports unknown values and never labels a road as safe.

Requirements

Use Node.js 22 or newer.

Install from source

git clone https://github.com/quinnsprouse/routecraft.git
cd routecraft
npm install
npm run build
npm link
routecraft --version

Start an agent session

Create a separate workspace for each route.

export ROUTECRAFT_HOME="$(mktemp -d)"
routecraft guide next --json

Read result.actions from guide next. After a normal command, follow result.nextActions when that field exists.

Each executable action includes the next CLI and MCP calls with their expected results.

Load the bundled network when you want a local demo.

routecraft guide topic network --json

Run the command in result.bundledDemo.invoke.cli. Then run the returned route.create action and continue through result.nextActions.

Use a command guide before you need more options.

routecraft guide command route.append --json
routecraft guide command route.export --json

Agent skill

Routecraft includes a skill that matches the installed CLI version.

routecraft skills get core --json
routecraft skills get core --full --json

Register result.path with the agent host. Use result.content when the host accepts inline instructions.

MCP

Run routecraft mcp over standard input and output.

{
  "mcpServers": {
    "routecraft": {
      "command": "routecraft",
      "args": ["mcp"],
      "env": {
        "ROUTECRAFT_HOME": "/absolute/path/to/a/route-workspace"
      }
    }
  }
}

Routecraft hides Google imagery commands until ROUTECRAFT_GOOGLE_MAPS_API_KEY exists. Run routecraft provider status --json to inspect the current setup.

Data sources

Data	Source	Required setup
Roads, paths, surfaces, and access	OpenStreetMap and Overpass	None
Place lookup	Nominatim	Explicit public-service consent or a configured endpoint
Route weather	Open-Meteo	None for its public noncommercial endpoint
Segment elevation	USGS 3DEP	None
Map, aerial, and street images	Google Maps Platform	ROUTECRAFT_GOOGLE_MAPS_API_KEY

Personal Strava and Ride with GPS data are not implemented.

Data license

Routecraft uses road and path data from OpenStreetMap contributors. OpenStreetMap licenses this data under the ODbL.

Develop

npm ci
npm run check
npm run package:smoke

See the architecture note for the module boundaries and project patterns.

License

MIT