snatching amp's walkthrough for my own purposes mwhahaha
traverse.dunkirk.sh/diagram/6121f05c-a5ef-4ecf-8ffc-02534c5e767c
docs: update readme
+31
-39
+31
-39
README.md
+31
-39
README.md
···
1
1
# traverse
2
2
3
-
interactive code walkthrough diagrams via MCP. share them with anyone.
3
+
[](https://traverse.dunkirk.sh/diagram/6121f05c-a5ef-4ecf-8ffc-02534c5e767c)
4
+
5
+
One of my favorite features about [amp](https://ampcode.com) is their walkthrough feature. It runs a sub agent which goes and breaks your repo into parts and then sends it up to amp's services to get rendered into a nice web page! I got curious and ended up dumping the tool prompt for both the walkthrough subagent and the tool prompt that generates the diagram.
4
6
5
-
The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
7
+
Turns out they are using mermaid syntax with ids on each node that are linked to a json object that has the summary in md of each section. Looking into their web ui rendering they have actually designed their own mermaid renderer likely to get better routing with the paths. We can get amazingly close to that with regular mermaid still and that is what this project is!
6
8
7
-
## try it now
9
+
This is a mcp server that also launches a web server in the background. You can hook this into whatever ai tool that you want that supports mcp (which is north of 80% of coding tools at this point if not nearing 100%) and start generating walkthroughs! It will initally give you a local url but if you want to share it with others then you can use the share button in the top corner of the page and it will by default share it to my hosted instance at [`traverse.dunkirk.sh`](https://traverse.dunkirk.sh) but if you configure the json settings or add an env variable you can point it to your own selfhosted instance!
10
+
11
+
## let's try it!
12
+
13
+
The mcp server must be run with bun since it uses the `Bun.serve` api extensively. If you haven't tried bun yet I would highly recommend it!
8
14
9
15
```sh
10
-
bunx @taciturnaxolotl/traverse
16
+
bunx @taciturnaxolotl/traverse@latest
11
17
```
12
18
13
-
requires [bun](https://bun.sh). runs an MCP server on stdio and a web server on `localhost:4173`.
19
+
By default this runs an MCP server on stdio and a web server on `localhost:4173`.
14
20
15
-
## setup
21
+
### I want this in my agent of choice!
16
22
17
-
add to your MCP client:
18
-
19
-
**claude code:**
23
+
For claude code they have made this fairly easy:
20
24
21
25
```sh
22
-
claude mcp add traverse -- bunx @taciturnaxolotl/traverse
26
+
claude mcp add traverse -- bunx @taciturnaxolotl/traverse@latest
23
27
```
24
28
25
-
**claude desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
29
+
For claude desktop (on mac) you can add the following to `~/Library/Application Support/Claude/claude_desktop_config.json`:
26
30
27
31
```json
28
32
{
29
33
"mcpServers": {
30
34
"traverse": {
31
35
"command": "bunx",
32
-
"args": ["@taciturnaxolotl/traverse"]
36
+
"args": ["@taciturnaxolotl/traverse@latest"]
33
37
}
34
38
}
35
39
}
36
40
```
37
41
38
-
**other MCP clients** — same JSON config, wherever your client reads `.mcp.json` or equivalent.
39
-
40
-
your AI calls the `walkthrough_diagram` tool with mermaid code + node descriptions, and you get a clickable diagram in your browser.
41
-
42
-
diagrams persist to sqlite at `~/Library/Application Support/traverse/traverse.db` (macOS) or `$XDG_DATA_HOME/traverse/traverse.db` (linux). override with `TRAVERSE_DATA_DIR`.
42
+
For other agents its the same JSON config typically.
43
43
44
-
## sharing
44
+
## Config
45
45
46
-
click the share button on any diagram to upload it to `traverse.dunkirk.sh` and copy a public link.
46
+
### json config
47
47
48
-
configure the share server in `~/Library/Application Support/traverse/config.json`:
48
+
On macos edit/create `~/Library/Application Support/traverse/config.json`. If you are on Linux then `~/.config/traverse/config.json` (or `$XDG_CONFIG_HOME/traverse/config.json`)
49
49
50
50
```json
51
51
{
52
-
"shareServerUrl": "https://traverse.dunkirk.sh"
52
+
"shareServerUrl": "https://traverse.dunkirk.sh",
53
+
"port": 4173,
54
+
"mode": "local"
53
55
}
54
56
```
55
57
56
-
or set `TRAVERSE_SHARE_URL`.
58
+
### env vars
57
59
58
-
## server mode
60
+
| var | default | description |
61
+
| -------------------- | ----------------------------- | ------------------------------------------ |
62
+
| `TRAVERSE_PORT` | `4173` | web server port |
63
+
| `TRAVERSE_MODE` | `local` | `local` (mcp + web) or `server` (web only) |
64
+
| `TRAVERSE_SHARE_URL` | `https://traverse.dunkirk.sh` | share server url |
65
+
| `TRAVERSE_DATA_DIR` | platform default | sqlite db location |
59
66
60
-
run your own share server:
61
-
62
-
```sh
63
-
TRAVERSE_MODE=server bun run src/index.ts
64
-
```
65
-
66
-
accepts `POST /api/diagrams` with a diagram JSON body, returns `{ id, url }`.
67
-
68
-
## env vars
69
-
70
-
| var | default | description |
71
-
|-----|---------|-------------|
72
-
| `TRAVERSE_PORT` | `4173` | web server port |
73
-
| `TRAVERSE_MODE` | `local` | `local` (mcp + web) or `server` (web only) |
74
-
| `TRAVERSE_SHARE_URL` | `https://traverse.dunkirk.sh` | share server url |
75
-
| `TRAVERSE_DATA_DIR` | platform default | sqlite db location |
67
+
The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
76
68
77
69
<p align="center">
78
70
<img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />