Debugging

Tools and workflows for debugging meloqui assistants.

Debug Tmux Layout

Most assistant packages include a debug:tmux script that launches a split-pane layout with:

• Main pane: The assistant UI
• Log pane: Real-time JSON logs (tail -f on log file)
• Conversation pane: Human-readable conversation transcript

# In any assistant package
npm run debug:tmux

Environment Variables

The debug script sets these automatically:

Variable	Description
MELOQUI_LOG_FILE	Path to JSON log file
MELOQUI_LOG_LEVEL	Log verbosity (DEBUG, INFO, WARN, ERROR)
MELOQUI_CONVERSATION_FILE	Path to conversation transcript

Tmux Navigation

Scrolling

The assistant UI (Ink/React) captures mouse events. To scroll the tmux buffer:

Method	Description
Shift + scroll wheel	Bypasses the app, scrolls tmux buffer
PageUp	Enters copy mode and scrolls up
prefix + [	Enters copy mode manually

Copy Mode Navigation

Once in copy mode (prefix + [ or PageUp):

Key	Action
q	Exit copy mode
j/k	Line up/down
Ctrl+u	Page up
Ctrl+d	Page down
g	Go to top
G	Go to bottom
/	Search forward
?	Search backward

Copy/Paste

With mouse mode enabled:

Method	Description
Drag to select	Auto-copies to system clipboard
Double-click	Selects word and copies
Option + drag	Uses iTerm2 native selection (bypasses tmux)
v (copy mode)	Start selection
y (copy mode)	Copy selection to clipboard
Cmd+V	Paste from system clipboard

Pane Navigation

Key	Action
prefix + arrow	Move between panes
prefix + z	Toggle pane zoom (fullscreen)
prefix + q	Show pane numbers
prefix + x	Close current pane

Note: Default prefix is Ctrl+b

Recommended Tmux Config

Add to ~/.tmux.conf:

# Enable mouse support
set -g mouse on

# Increase scrollback buffer
set -g history-limit 50000

# Page up enters copy mode
bind -n PageUp copy-mode -u

# Vi-style copy mode
setw -g mode-keys vi

# Copy to system clipboard (macOS)
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
bind -T copy-mode-vi MouseDragEnd1Pane send -X copy-pipe-and-cancel "pbcopy"

Reload config: tmux source-file ~/.tmux.conf

Log Levels

Set MELOQUI_LOG_LEVEL to control verbosity:

Level	Shows
DEBUG	Everything including request/response details
INFO	Normal operations
WARN	Warnings and errors
ERROR	Errors only

Conversation Logging

The conversation file shows a human-readable transcript:

═══════════════════════════════════════════════════════════════════
[2024-01-15 22:30:45] USER
───────────────────────────────────────────────────────────────────
Hello, can you help me with this code?

═══════════════════════════════════════════════════════════════════
[2024-01-15 22:30:47] ASSISTANT
───────────────────────────────────────────────────────────────────
Of course! I'd be happy to help. What would you like me to look at?

  🔧 Tool: read_file
     {"filePath": "/path/to/file.ts"}
  ✓ read_file: export function example() { ... }

Uses synchronous writes so tail -f shows output immediately.