# What Is routes.jsonl in Gas Town? The Complete Guide to the Central Routing Table

> Discover the function of routes.jsonl in Gas Town. This guide explains how the central routing table maps bead prefixes to filesystem paths for efficient command, plugin, and mail delivery.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: deep-dive
- Published: 2026-07-07

---

**The `routes.jsonl` file serves as the central routing table for Gas Town, mapping bead name prefixes to filesystem paths so that commands, plugins, and mail delivery can locate beads across different rigs.**

`routes.jsonl` is the backbone of prefix-based routing in the gastownhall/gastown ecosystem. This newline-delimited JSON file lives at the town level and translates short identifiers like `hq-` or `myrig-` into concrete directory paths. Without this lookup table, cross-rig operations ranging from simple bead commands to complex mail routing would fail to locate their targets.

## Understanding the routes.jsonl File Format

`routes.jsonl` follows the JSON Lines format (JSONL), containing one JSON object per line. Each entry maps a **prefix**—the short identifier used in bead names—to a **path** relative to the town root where that rig's beads reside.

A typical entry looks like this:

```json
{"prefix":"myrig-","path":"myrig"}

```

When a user executes a beads command containing a prefix, such as `bd show myrig-abc`, the beads library queries this file to determine that beads for the `myrig-` prefix live in the `myrig/.beads` directory.

### Default Location and Resolution

By default, Gas Town expects `routes.jsonl` at `~/gt/.beads/routes.jsonl`. The resolution logic in [`plugins/dolt-snapshots/main.go`](https://github.com/gastownhall/gastown/blob/main/plugins/dolt-snapshots/main.go) handles the default path construction:

```go
home, _ := os.UserHomeDir()
return filepath.Join(home, "gt", ".beads", "routes.jsonl")

```

If the file is missing or malformed, the system logs a warning and falls back to a local-only view of beads, limiting cross-rig functionality.

## How routes.jsonl Is Populated

The file is automatically created and updated whenever a new rig is added to the town. In [`internal/rig/manager.go`](https://github.com/gastownhall/gastown/blob/main/internal/rig/manager.go) (lines 842-856), the rig manager constructs a `beads.Route` value and appends it to the town-level table:

```go
route := beads.Route{
    Prefix: opts.BeadsPrefix + "-", // e.g. "myrig-"
    Path:   routePath,               // e.g. "myrig" or "myrig/mayor/rig"
}
beads.AppendRoute(m.townRoot, route) // writes a line to routes.jsonl

```

This ensures that every rig registered via `gt rig add myrig --prefix myrig` immediately becomes reachable through the routing system.

## How routes.jsonl Is Consumed

Multiple subsystems within Gas Town read `routes.jsonl` to resolve prefixes to physical locations.

### Beads Command Routing

The beads library uses this file to route prefixed commands (`bd show`, `bd list`, etc.) to the correct rig-level beads directory. It translates the prefix portion of a bead name into the absolute path where the bead data lives.

### Mail Routing in internal/mail/router.go

The mail router loads the file via `beads.LoadRoutes` to discover agents on other rigs. As implemented in [`internal/mail/router.go`](https://github.com/gastownhall/gastown/blob/main/internal/mail/router.go) (lines 13-30), it iterates over routes to query rig-level beads directories while skipping town-level entries:

```go
routes, routeErr := beads.LoadRoutes(routesDir)
for _, route := range routes {
    if strings.HasPrefix(route.Prefix, "hq-") {
        continue // town‑level already queried
    }
    rigBeadsDir := filepath.Join(r.townRoot, route.Path, ".beads")
    // …query agents in rigBeadsDir…
}

```

### Dolt Snapshots Plugin Integration

The **dolt-snapshots** plugin in [`plugins/dolt-snapshots/main.go`](https://github.com/gastownhall/gastown/blob/main/plugins/dolt-snapshots/main.go) parses the file to map prefixes to database names. Lines 184-215 demonstrate the parsing logic:

```go
var r route
json.Unmarshal([]byte(line), &r)
prefix := strings.TrimRight(r.Prefix, "-")
dbName := r.Path
if idx := strings.Index(r.Path, "/"); idx > 0 {
    dbName = r.Path[:idx]
}
result[prefix] = dbName

```

This enables the plugin to determine which Dolt database corresponds to a given prefix when creating or accessing snapshots.

## Practical Usage Examples

### Adding a New Rig

When you add a rig via the CLI, the system updates `routes.jsonl` automatically:

```bash
gt rig add myrig --prefix myrig

```

After execution, `routes.jsonl` contains the new route mapping the prefix to the rig's path.

### Looking Up a Prefix in a Plugin

To resolve a prefix to a database name in your own plugin:

```go
routes := loadRoutes("/home/user/gt/.beads/routes.jsonl")
dbName := routes["myrig"] // → "myrig"

```

### Cross-Rig Mail Routing

To find agents on another rig programmatically:

```go
router := mail.NewRouter(townRoot)
addresses, _ := router.resolveAgentsByRig("myrig")

```

The router reads `routes.jsonl`, locates the entry for `myrig-`, and scans `myrig/.beads` for available agents.

## Summary

- **`routes.jsonl`** is a newline-delimited JSON file that serves as Gas Town's central routing table, mapping prefixes like `myrig-` to filesystem paths.
- **Located** by default at `~/gt/.beads/routes.jsonl`, it is created automatically and updated by [`internal/rig/manager.go`](https://github.com/gastownhall/gastown/blob/main/internal/rig/manager.go) whenever rigs are added.
- **Populated** through the `beads.Route` struct and `beads.AppendRoute` function, which append new entries as rigs are registered.
- **Consumed** by the beads library for command routing, the mail router in [`internal/mail/router.go`](https://github.com/gastownhall/gastown/blob/main/internal/mail/router.go) for cross-rig agent discovery, and the dolt-snapshots plugin for database resolution.
- **Enables** cross-rig operations without hard-coded paths, allowing the system to locate beads directories dynamically based on prefix identifiers.

## Frequently Asked Questions

### What format does routes.jsonl use?

`routes.jsonl` uses the JSON Lines (JSONL) format, with each line containing a single JSON object featuring `prefix` and `path` fields. This format allows easy appending of new routes and efficient line-by-line parsing without loading the entire file into memory.

### Where is routes.jsonl located by default?

By default, the file resides at `~/gt/.beads/routes.jsonl`. The `resolveRoutesFile` helper function in [`plugins/dolt-snapshots/main.go`](https://github.com/gastownhall/gastown/blob/main/plugins/dolt-snapshots/main.go) constructs this path by joining the user's home directory with `gt/.beads/routes.jsonl`.

### What happens if routes.jsonl is missing or corrupted?

If the file is missing or contains malformed JSON, Gas Town logs a warning and falls back to a local-only view of beads. This means cross-rig operations will fail, but local bead operations remain functional. The system does not crash, but multi-rig commands like cross-rig mail delivery will be unable to resolve remote targets.

### Which components read and write routes.jsonl?

The [`internal/rig/manager.go`](https://github.com/gastownhall/gastown/blob/main/internal/rig/manager.go) file handles writes via `beads.AppendRoute` when rigs are added. Readers include the beads library for command routing, [`internal/mail/router.go`](https://github.com/gastownhall/gastown/blob/main/internal/mail/router.go) for mail delivery, and [`plugins/dolt-snapshots/main.go`](https://github.com/gastownhall/gastown/blob/main/plugins/dolt-snapshots/main.go) for database mapping. These components use `beads.LoadRoutes` or custom parsing logic to consume the file.