muck

A terminal MUD/MUCK client with highlights, gags, aliases, and session logging.

Installation

go install onlyhavecans.works/tools/muck/cmd/muck@latest

Or build from source:

make build
# Binary at bin/muck

Usage

muck <world>           # Connect to a configured world
muck -world myworld    # Alternative syntax
muck -config path.yaml # Use specific config file
muck -debug            # Enable debug logging
muck                   # List available worlds

Keyboard Controls

Input

Key	Action
Enter	Send command
Up/Down or Ctrl+P/N	Browse command history
Left/Right or Ctrl+B/F	Move cursor
Tab	Command/history completion
Ctrl+A / Home	Move to start of line
Ctrl+E / End	Move to end of line
Ctrl+D / Delete	Delete character forward
Ctrl+K	Delete to end of line
Ctrl+U	Delete to start of line
Ctrl+W	Delete previous word
Ctrl+S	Save input to buffer
Ctrl+R	Restore input from buffer
Ctrl+C / Esc	Quit

Input buffer: Use Ctrl+S to save your current input, type other commands, then Ctrl+R to restore what you were typing.

Viewport

Key	Action
PgUp/PgDown	Scroll viewport
Ctrl+Up/Down	Scroll one line
g / Ctrl+Home	Scroll to top
G / Ctrl+End	Scroll to bottom
/	Enter search mode
n	Next search match
N	Previous search match

When searching, press Enter to execute or Esc to cancel.

Client Commands

Commands starting with / are handled locally and not sent to the server. Tab completion is available for all commands.

Command	Description
/help	Show available commands
/quit or quit	Disconnect and exit
/highlight add <pattern> <color> [name]	Add a highlight pattern
/highlight remove <name>	Remove a highlight by name
/highlight list	List all highlights
/gag add <pattern> [name]	Add a gag pattern (hides matching lines)
/gag remove <name>	Remove a gag by name
/gag list	List all gags

Examples:

/highlight add "whispers to you" magenta
/highlight add "^\\[Combat\\]" red combat_lines
/gag add "has connected\\.$" connect_spam
/highlight list
/gag remove connect_spam

Patterns added at runtime are not saved to config and will be lost when you exit.

Configuration

Config is loaded from (in order):

1. Current directory (config.yaml)
2. ~/.config/muck/config.yaml
3. /etc/muck/config.yaml

Example Configuration

# Include additional config files (paths relative to this file)
includes:
  - highlights.yaml
  - aliases.yaml

global:
  logging:
    session_log_enabled: true
    session_log_path: "$HOME/.local/share/muck/logs/{world}/{YYYY}-{MM}-{DD}.log"
    session_log_strip_ansi: true
    session_log_commands: true

  input:
    command_delimiter: ";"
    history_size: 1000

  # Global highlights apply to all worlds
  highlights:
    - name: my_name
      pattern: "YourCharacterName"
      color: bright_yellow
      full_line: true

    - name: whispers
      pattern: "whispers to you"
      color: magenta

  # Global gags hide matching lines
  gags:
    - name: spam
      pattern: "^\\[OOC\\].*has connected\\."

  # Global aliases apply to all worlds
  aliases:
    - name: l
      expansion: "look"
    - name: n
      expansion: "north"
    - name: s
      expansion: "south"

worlds:
  myworld:
    host: muck.example.com
    port: 8888
    tls: false
    connect_timeout: 30s

    # World-specific patterns (merged with global)
    highlights:
      - pattern: "\\[Public\\]"
        color: cyan

    aliases:
      - name: home
        expansion: "teleport #1234"

  securemuck:
    host: secure.example.com
    port: 8889
    tls: true
    tls_skip_verify: false

    # Override logging for this world
    logging:
      session_log_enabled: false

Configuration Reference

World Settings

Field	Type	Default	Description
host	string	required	Server hostname or IP
port	int	23 (or 992 for TLS)	Server port
tls	bool	false	Enable TLS encryption
tls_skip_verify	bool	false	Skip certificate verification
connect_timeout	duration	30s	Connection timeout

Logging Settings

Session Logging (logs MUD output to file):

Field	Type	Default	Description
session_log_enabled	bool	false	Enable session logging
session_log_path	string	see below	Log file path template
session_log_strip_ansi	bool	true	Remove ANSI codes from logs
session_log_commands	bool	true	Log sent commands

Path template variables: {world}, {YYYY}, {MM}, {DD}, {HH}, {mm}, {ss}

Default path: $HOME/.local/share/muck/logs/{world}/{YYYY}-{MM}-{DD}.log

Logs are appended to existing files (never overwritten) and automatically rotate daily.

Application Logging (debug logs for troubleshooting the client):

Field	Type	Default	Description
app_log_level	string	info	Log level: debug, info, warn, error
app_log_path	string	stderr	File path for app logs (empty = stderr)

Input Settings

Field	Type	Default	Description
command_delimiter	string	;	Character for command stacking
history_size	int	1000	Commands to keep in history

Highlights

highlights:
  - name: optional_name     # For reference/debugging
    pattern: "regex"        # Go regex pattern
    color: red              # ANSI color name
    full_line: false        # Highlight entire line vs match only
    enabled: true           # Can disable without removing

Colors: black, red, green, yellow, blue, magenta, cyan, white, and bright_* variants.

Gags

gags:
  - name: optional_name
    pattern: "regex"        # Lines matching this are hidden
    enabled: true

Aliases

aliases:
  - name: shortcut          # What you type
    expansion: "full command"  # What gets sent
    enabled: true

Aliases support:

• Command stacking: go;look sends two commands (uses command_delimiter)
• Repeat prefix: #3 north sends "north" three times
• Nested expansion: Aliases can expand to other aliases

Modular Configuration

Split config across files using includes:

# config.yaml
includes:
  - worlds.yaml
  - highlights.yaml

global:
  input:
    command_delimiter: ";"

# worlds.yaml
worlds:
  myworld:
    host: example.com
    port: 8888

Included files are merged. Patterns (highlights, gags, aliases) are combined rather than replaced.

License

See LICENSE for details.