Subdirectories in the cmd Directory of gastownhall/gastown: A Complete Guide

The cmd directory contains three subdirectories: gt, gt-proxy-server, and gt-proxy-client, each providing distinct command-line entry points for the Gas Town system.

The gastownhall/gastown repository organizes its command-line binaries under the cmd directory following standard Go project conventions. This directory houses three focused subdirectories that define the entire command-line surface of the system, from the main agent coordination interface to secure proxy components for sandboxed environments.

Overview of the cmd Directory Structure

The cmd directory follows the canonical Go layout where each subdirectory represents a separate binary entry point. Unlike monolithic CLI applications, Gastown separates concerns into three distinct executables: the primary user-facing tool, a server-side proxy for secure container communication, and a lightweight client wrapper. This architecture ensures that privileged operations run isolated while providing convenient access to external processes.

The Three Subdirectories Explained

cmd/gt – The Main Gas Town CLI

The cmd/gt subdirectory contains the primary Gas Town CLI used for everyday agent coordination, issue tracking, and workspace management. Its entry point at cmd/gt/main.go delegates to cmd.Execute() to dispatch subcommands such as status, bd ready, and nudge. This binary serves as the main interface for developers interacting with the Gas Town system.

cmd/gt-proxy-server – The mTLS Proxy Server

The cmd/gt-proxy-server subdirectory implements an mTLS proxy server that runs on the host machine to expose safe gt and bd subcommands to containers. Located at cmd/gt-proxy-server/main.go, this component parses configuration flags, loads or generates a Certificate Authority (CA), and configures the specific subcommands allowed through the proxy boundary. This isolation mechanism prevents containers from accessing privileged operations directly.

cmd/gt-proxy-client – The Proxy Client Wrapper

The cmd/gt-proxy-client subdirectory provides a thin client wrapper that communicates with the proxy server over mutually authenticated TLS. Implemented in cmd/gt-proxy-client/main.go, this binary forwards user commands to the proxy server, allowing external processes to invoke proxy-mediated commands safely without direct access to the host's gt binary.

Key Source Files and Entry Points

Each subdirectory contains a main.go file that serves as the compilation entry point:

• cmd/gt/main.go: Calls cmd.Execute() to initialize the CLI framework and register subcommands.
• cmd/gt-proxy-server/main.go: Sets up the HTTP listener, configures mTLS certificates from the specified -ca-dir, and validates allowed commands against the -town-root configuration.
• cmd/gt-proxy-client/main.go: Establishes the mTLS connection to the proxy address specified by -proxy and forwards the remaining arguments as a remote procedure call.

Practical Usage Examples

Below are typical invocations for each binary built from the cmd directory subdirectories.

Running the main CLI:

# Check workspace status

gt status

# List issues ready for development

gt bd ready

# Send a message to the mayor agent

gt nudge mayor "Hi!"

Starting the proxy server:

gt-proxy-server \
  -listen=:9876 \
  -admin-listen=127.0.0.1:9877 \
  -ca-dir=~/gt/.runtime/ca \
  -town-root=~/gt

Using the proxy client:

gt-proxy-client \
  -proxy=localhost:9876 \
  gt status

Summary

• The cmd directory contains exactly three subdirectories: gt, gt-proxy-server, and gt-proxy-client.
• Each subdirectory maps to a distinct binary with a specific security and operational role in the Gas Town ecosystem.
• The entry points (main.go files) implement the separation between user-facing commands, host-level proxy services, and client-side wrappers.
• All other files under cmd/ are supporting Go source files; no additional nested subdirectories exist beyond these three.

Frequently Asked Questions

What is the purpose of the cmd directory in gastownhall/gastown?

The cmd directory organizes the command-line binaries following Go standards, containing three subdirectories that provide the complete command-line surface for the Gas Town system: the main CLI, a proxy server, and a proxy client.

How does the gt-proxy-server differ from the main gt binary?

The gt-proxy-server runs as a privileged host daemon that exposes a subset of gt commands over mTLS to sandboxed containers, while the gt binary executes directly with full user privileges for interactive development workflows.

Can I run Gastown commands without using the proxy components?

Yes. The gt binary in cmd/gt operates independently; the proxy components (gt-proxy-server and gt-proxy-client) are only required when running commands from within restricted container environments that need to access host-managed resources.

Where are the entry points for each cmd subdirectory located?

Each subdirectory contains a main.go file at its root: cmd/gt/main.go, cmd/gt-proxy-server/main.go, and cmd/gt-proxy-client/main.go. These files compile into the respective binaries and handle flag parsing, initialization, and command dispatch.

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