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 vitest run src/tui/__tests__/

Some pre-existing test failures may exist in the broader test suite — focus on tests relevant to the feature being verified.