snatching amp's walkthrough for my own purposes mwhahaha
traverse.dunkirk.sh/diagram/6121f05c-a5ef-4ecf-8ffc-02534c5e767c
docs: update readme
+71
-1
+71
-1
README.md
+71
-1
README.md
···
1
1
# traverse
2
2
3
-
snatching amp's walkthrough for my own purposes mwhahaha
3
+
interactive code walkthrough diagrams via MCP. share them with anyone.
4
4
5
5
The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
6
+
7
+
## try it now
8
+
9
+
```sh
10
+
bunx @taciturnaxolotl/traverse
11
+
```
12
+
13
+
requires [bun](https://bun.sh). runs an MCP server on stdio and a web server on `localhost:4173`.
14
+
15
+
## setup
16
+
17
+
add to your MCP client:
18
+
19
+
**claude code:**
20
+
21
+
```sh
22
+
claude mcp add traverse -- bunx @taciturnaxolotl/traverse
23
+
```
24
+
25
+
**claude desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
26
+
27
+
```json
28
+
{
29
+
"mcpServers": {
30
+
"traverse": {
31
+
"command": "bunx",
32
+
"args": ["@taciturnaxolotl/traverse"]
33
+
}
34
+
}
35
+
}
36
+
```
37
+
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`.
43
+
44
+
## sharing
45
+
46
+
click the share button on any diagram to upload it to `traverse.dunkirk.sh` and copy a public link.
47
+
48
+
configure the share server in `~/Library/Application Support/traverse/config.json`:
49
+
50
+
```json
51
+
{
52
+
"shareServerUrl": "https://traverse.dunkirk.sh"
53
+
}
54
+
```
55
+
56
+
or set `TRAVERSE_SHARE_URL`.
57
+
58
+
## server mode
59
+
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 |
6
76
7
77
<p align="center">
8
78
<img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />