Testing Mastracode TUI

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

Devin Secrets Needed

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

Prerequisites

1. Build mastracode and its dependencies:

``bash cd /home/ubuntu/repos/mastra COREPACKENABLESTRICT=0 pnpm build:mastracode ``

This may take a few minutes. If pnpm has corepack issues, install directly: npm install -g [email protected]

1. 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:

``bash COREPACKENABLESTRICT=0 pnpm turbo build --filter ./mastracode --continue ``

1. 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:

``json { "customProviders": [ { "name": "OpenRouter", "url": "https://openrouter.ai/api/v1";, "apiKey": "<OPENROUTERAPIKEY 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" } ] } ``

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

1. 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

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 taskwrite tool explicitly. Some models (e.g., minimax) may not call it automatically — you may need to say something like: "Please use the taskwrite tool to create a task list with 3 items: Fix login bug, Add unit tests, Update docs"

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

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

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

1. 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 GOOGLEGENERATIVEAIAPIKEY 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.