Agentic coding without running off the cliff

A map of your project, from features down to the code.

A worried cartoon coyote running in mid-air, past the edge of a cliff

The Coyote Effect

When coding agents generate most of your code, you can lose track of your project's features and implementation. Everything runs fine until the day you look down and see there is nothing under your feet. This is the Coyote Effect.

coyomap helps you avoid it: you keep visibility into the project and find your way around it as it grows.

What coyomap is

coyomap analyzes your project and builds an interactive map of its features, in plain language, linked to the underlying architecture and code. Use it to understand what your project does and how it is implemented, top-down, without reading all the code. Drill into the code only where and when you actually need to.

It is also a shared picture of the project for your non-developer teammates.

What coyomap shows

The viewer shows your project in two views: Product and Under the hood.

The coyomap viewer on a project's Features page: the people who use the product on the left, its features in happy-path order in the middle, and the data each feature owns on the right. No code on screen.

Product shows the project's functionality: who uses it, its features and use cases, the happy path, the rules it enforces, and the data it keeps.

The coyomap viewer on a project's Components page: the map of one subsystem with one component selected and explained in a sentence, and that component's source code open on the right at the line the map points to.

Under the hood shows how the project is built and run: its components and their dependencies, where data is stored, how it is deployed.

You can start from a feature and drill down: the interfaces and data it touches, the components that do the work, and the code behind each.

Why not just ask my agent to explain the code?

You can ask your agent to analyze the code, generate summaries and draw diagrams. coyomap differs in two ways:

coyomap builds an explorable, hierarchical map: every box has a plain-language note, links to related elements, and links into the architecture and code. The map is saved with the project, so everyone sees the same one.
An AI agent can miss things or make things up. So coyomap reads the code with the help of an index, makes every claim point at a real file and line, checks the map for gaps and contradictions, and has fresh agents try to prove each claim wrong before the map is written.

Get started

coyomap runs as an agent skill on Claude Code, Codex, and Cursor. Install it once, then drive everything with /coyomap. You need a checkout of the project and one of the three agents. Having written the code, or reading it, is not required.

Install the skill, once

Requirements: Python 3.10 or newer, git, and a macOS or Linux shell. Clone the repo, then from its root:

git clone https://github.com/nseniak/coyomap.git
cd coyomap
make install

This puts the skill into each agent's skills home and builds a repo-local virtualenv with the coyomap command. Nothing lands in your system Python.

Build the map

In your project, with no map yet:

/coyomap

coyomap first prints what it is about to read, then builds the map into .coyomap/, pinned to the current commit. Commit that folder with your code. The initial build is the agent's biggest job: up to an hour, once per project. After that, changes are cheap.

View the map

A small local server renders the viewer. Start it from the coyomap clone:

make start

It opens a landing page at http://127.0.0.1:8765/. Pick your project's folder there once.

Ask for changes in plain language

/coyomap move the payments module into a new "Billing" subsystem
/coyomap the "utils" component is really two things, split it
/coyomap add a use case for an admin resetting a user's password

Every edit runs the same checks as a build. Ask for a feature the code does not have, and coyomap says so instead of drawing it.

Status

coyomap is work in progress, in daily use. The stored map format still moves: a newer coyomap may not read an older map, and a rebuild is the fix, so treat a map as replaceable. Map quality depends on the coding agent and model: read it, and correct it.

Feedback and bug reports are welcome: open an issue.