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

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:

{"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 handles the default path construction:

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 (lines 842-856), the rig manager constructs a beads.Route value and appends it to the town-level table:

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 (lines 13-30), it iterates over routes to query rig-level beads directories while skipping town-level entries:

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 parses the file to map prefixes to database names. Lines 184-215 demonstrate the parsing logic:

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:

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:

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

Cross-Rig Mail Routing

To find agents on another rig programmatically:

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 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 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 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 file handles writes via beads.AppendRoute when rigs are added. Readers include the beads library for command routing, internal/mail/router.go for mail delivery, and plugins/dolt-snapshots/main.go for database mapping. These components use beads.LoadRoutes or custom parsing logic to consume the file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}