systemap

Guide · 1 of 8

Get started

This page tells you how to install systemap and make the first map of a small Python project with a coding agent.

All command output on this page comes from that example project.

What you need

Install systemap

uv tool install systemap

For a TypeScript repository, install the typescript extra. It adds the tree-sitter parser.

uv tool install 'systemap[typescript]'

To add systemap to the development dependencies of your project, use uv add --dev systemap. Then run each command with uv run systemap.

Write the initial files

At the root of your repository, run systemap init. These are the first lines of the output:

$ systemap init
wrote systemap.toml
wrote map/model.py
wrote docs/map/.gitkeep
wrote .github/workflows/systemap.yml
The command wrote .claude/skills/systemap/ (SKILL.md and 9 references)

Give the instruction to your agent

The output ends with the instruction for your coding agent. Give it to the agent:

Make a map of this repository with systemap. Obey the systemap skill and its writing rules.

The agent extracts the facts, gives each module a component, and writes the flows and the sequences. It does the checks until they pass. Then it gives a completion report. Read the report. Correct each claim that you do not agree with. Coding agents gives the full procedure.

The example project has three modules, an empty package marker, and one test file. Its pyproject.toml file declares the console script shop = "shop.cli:main". In this project, the agent wrote three components, one actor, three flows, and one sequence in map/model.py. systemap place calculates the positions of the components. Concepts gives the terms, and the reference gives a complete small model.

Run the first refresh

systemap refresh extracts the facts, does the checks, and renders the page and the configured figures:

$ systemap refresh
map: The refresh uses the working tree.
map: The command updated docs/map/map.json, docs/map/index.html, docs/map/figures/structure.svg, docs/map/figures/system.svg
map: Commit docs/map/ to record this system state.

If the model has no components, the refresh stops with exit code 1:

$ systemap refresh
The model has no components. Read the skill instructions.

Run the checks

systemap check compares the map with the code:

$ systemap check
map routes: 0 flow paths across components other than their endpoints, 0 across regions other than their endpoint regions.
coverage: 4 of 4 modules mapped, 1 an empty package marker
map layout: has no errors (4 components, 3 orthogonal flow paths with labels, no text size less than 11px)

If a rule rejects the map, or an output is stale, the command exits 1. Each finding gives a correction.

systemap judgement prints possible map errors for a person or an agent to examine. These are the first lines of the output:

$ systemap judgement
judgement: 8 possible map errors to examine
  single module: CommandLine contains only shop.cli

For each line, change the map, or record an answer under [judgement] answered in systemap.toml. Concepts tells how to record an answer. With --strict, the command exits 1 while a line stays open.

In the example, the agent changed the map for some lines and recorded answers for the other lines. Then the strict command passed. This is the first line of the output:

$ systemap judgement --strict
judgement: No possible map error to examine, 4 answered

A result without open findings does not show that each claim is correct. See Limits.

Open the page

$ systemap serve
The server serves docs/map at http://127.0.0.1:8765/. Use Ctrl-C to stop the server.

Open the URL in a browser. Read the map tells how to use the page. The live example is the map of systemap itself. For a different port, see the reference.

Commit the map

Commit map/model.py, systemap.toml, and docs/map/ with the source code. Then the workflow from init compares the map with the source on each push to main and on each pull request.

Next steps