/testing-mastracode-tui

name: testing-mastracode-tui
description: Testing mastracode TUI features interactively in Konsole. Covers model configuration, thread lifecycle, task state isolation, and common blockers.

Testing Mastracode TUI

Guide for interactive testing of mastracode's terminal UI in Konsole.

Devin Secrets Needed

• `OPENROUTER_API_KEY` — for using OpenRouter as a custom provider when Anthropic/OpenAI keys are unavailable

Prerequisites

1. Build mastracode and its dependencies:

   cd /home/ubuntu/repos/mastra
   COREPACK_ENABLE_STRICT=0 pnpm build:mastracode

This may take a few minutes. If `pnpm` has corepack issues, install directly: `npm install -g pnpm@10.11.0`

2. If the build fails due to pre-existing DTS errors in `@mastra/core` or `@mastra/memory`, use `--continue` to let downstream packages (including mastracode) still build:

   COREPACK_ENABLE_STRICT=0 pnpm turbo build --filter ./mastracode --continue

3. If unit tests fail with missing `@mastra/core/workspace`, run `pnpm build:core` first.

Configuring a Custom Provider (OpenRouter)

If you don't have a direct Anthropic/OpenAI API key, configure OpenRouter as a custom provider:

1. Edit `~/.local/share/mastracode/settings.json`:

   {
     "customProviders": [
       {
         "name": "OpenRouter",
         "url": "https://openrouter.ai/api/v1",
         "apiKey": "<OPENROUTER_API_KEY value>",
         "models": ["minimax/minimax-m2.7"]
       }
     ],
     "models": {
       "activeModelPackId": "custom:Custom",
       "modeDefaults": {
         "build": "openrouter/minimax/minimax-m2.7",
         "plan": "openrouter/minimax/minimax-m2.7",
         "fast": "openrouter/minimax/minimax-m2.7"
       }
     },
     "customModelPacks": [
       {
         "name": "Custom",
         "models": {
           "build": "openrouter/minimax/minimax-m2.7",
           "plan": "openrouter/minimax/minimax-m2.7",
           "fast": "openrouter/minimax/minimax-m2.7"
         },
         "createdAt": "2026-01-01T00:00:00.000Z"
       }
     ]
   }

2. After launching mastracode, you may also need to activate the custom pack via `/models` → select "Custom" → "Activate".

3. Verify the status bar at the bottom shows the correct model (e.g., `build openrouter/minimax/minimax-m2.7`).

Launching Mastracode

cd /home/ubuntu/repos/mastra/mastracode
COREPACK_ENABLE_STRICT=0 pnpm cli

On first launch, mastracode may show a setup wizard. Select "Skip" to proceed to the main TUI without configuring models interactively.

Key TUI Commands

| Command | Action | | ---------- | ------------------------------------------------ | | `/new` | Create a new empty thread | | `/threads` | Open thread selector (↑↓ navigate, Enter select) | | `/clone` | Clone current thread | | `/models` | Switch model pack | | `/help` | Show all available commands |

Programmatic Rendering Tests

For visual/rendering bugs (e.g., border alignment, padding, wrapping), writing a quick `tsx` script that directly renders the component is more reliable than visual inspection alone:

cd /home/ubuntu/repos/mastra/mastracode
npx tsx test-script.ts

Key approach:

• Import the component directly (e.g., `UserMessageComponent` from `./src/tui/components/user-message.js`)
• Render at specific widths and strip ANSI codes to measure visible character widths
• Assert all lines have identical visible width (for bordered components)
• Test at multiple terminal widths (40, 60, 80, 100, 120+) to catch edge cases
• Filter out trailing empty lines from `Spacer` components when measuring
• For before/after comparisons, simulate the old logic inline to confirm the bug exists

This approach catches bugs that are hard to see visually and provides concrete pass/fail evidence.

Testing Thread State Isolation

The key scenario for thread state testing:

1. **Generate tasks**: Ask the model to use the `task_write` tool explicitly. Some models (e.g., minimax) may not call it automatically — you may need to say something like: "Please use the task_write tool to create a task list with 3 items: Fix login bug, Add unit tests, Update docs"

2. **Verify tasks visible**: Look for the "Tasks [0/N completed]" section with ○/▶/✓ icons between the status line and the editor input.

3. **Test `/new`**: The task progress component should completely disappear. The screen should show only "Ready for new conversation" and an empty input.

4. **Test `/threads` switch**: Switch back to the original thread — messages and tasks should restore correctly.

5. **Test `/clone`**: Cloned threads should start with empty tasks (tasks are ephemeral, not persisted to clones).

Common Issues

• **Observational memory errors**: You may see errors about `GOOGLE_GENERATIVE_AI_API_KEY` for the OM model. Fix this by setting the OM model to an OpenRouter model via `/om` or in settings.json (`models.omModelOverride`). Configure the OM model if you expect observation to trigger during testing.
• **Model not calling tools**: Less capable models may not use mastracode's tool system. Explicitly instruct them to use specific tools by name.
• **Status bar shows wrong model**: After changing settings.json, you may need to use `/models` in the TUI to activate the custom pack.
• **Build failures**: If `pnpm cli` fails with module resolution errors, run `pnpm build:mastracode` (or with `--continue`) from the repo root to build all transitive dependencies.
• **User message rendering without LLM**: The user message box renders immediately on Enter, before any LLM response. You can test rendering bugs without a working LLM connection — just submit a message and inspect the bordered box.

Running Unit Tests

cd /home/ubuntu/repos/mastra
COREPACK_ENABLE_STRICT=0 pnpm --filter mastracode exec