# Reported issues for Terminal MCP Server

Pod holds 21 of 131 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Terminal MCP Server](/mcp/terminal-mcp-server).

## Most discussed

### [Bug] Error: MCP error -32603: Failed to wait for condition: PTY error: Tmux session 'terminal-mcp-d83406bb-ac21-4af5-b0a0-1f9209716f41' no longer exists

### Describe the bug

 `Error: MCP error -32603: Failed to wait for condition: PTY error: Tmux session 'terminal-mcp-d83406bb-ac21-4af5-b0a0-1f9209716f41' no longer exists`

how to fix it? i see it too ofter

### Steps to reproduce

`claude add mcp terminal-mcp -- npx -y terminal-server-mcp`

`claude -p "use terminal-mcp to figure out with bug ... , run it in the loop until bug will not fix`

### Expected behavior

i expected no errors here

### Actual behavior

 `Error: MCP error -32603: Failed

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/153) · 2025-12-26 · closed · external user · 2 comments

### [Bug] libc 2.39 not found after `npx -y` on ubuntu 22.04

### Describe the bug

`npx -y mcp-server-terminal@latest`

`/home/slach/.cache/mcp-server-terminal/terminal-mcp: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found (required by /home/slach/.cache/mcp-server-terminal/terminal-mcp)`

looks like latest package just doesn't work cause you require newer libc from your rust binary

ubuntu 22.04 have only libc 2.35

could we make fully static binary in rust without libc denedency?

### Steps to reproduce

`npx -y mcp-server-terminal@lates

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/152) · 2025-12-26 · closed · external user · 2 comments

### [Bug][Emulator][General][P0] - Alt-screen buffer updates not captured in visual mode

## Summary
In visual mode (tmux), terminal snapshots capture the **initial render** of applications using alternate screen buffers (via `CSI ?1049h`), but **fail to reflect any dynamic updates** after user interactions.

## Steps to Reproduce
1. Create visual terminal session with TUI application that uses alt-screen:
```json
{
  "command": "vim",
  "visual": true,
  "dimensions": {"rows": 30, "cols": 100}
}
```

2. Take initial snapshot:
```json
terminal_snapshot({"session_id": "..."})
```
**Re

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/142) · 2025-12-07 · closed · 2 comments

### [Enabler][Schema][Gemini][P1] - Add JSON Schema transformation layer for AI client compatibility

## Summary
Technical foundation work to transform `schemars`-generated JSON Schema (draft-2020-12) into formats compatible with various AI clients, starting with Gemini CLI.

## Motivation
The `schemars` crate generates JSON Schema using draft-2020-12 features that some AI clients don't support:
- `$defs` instead of `definitions`
- `anyOf` with `nullable: true` patterns
- Complex nested references

Gemini CLI fails with errors like:
```
Error: Invalid JSON schema for tool terminal_session_create

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/129) · 2025-12-06 · closed · 2 comments

### [Test] Input Tools - terminal_type and terminal_press_key Navigation

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Test `terminal_type` and `terminal_press_key` tools for reliable keyboard interaction with ffice TUI application including text entry, navigation, function keys, and control sequences.

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Text entry: Characters appear correctly in input fields
- [ ] Special characters: Spa

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/114) · 2025-12-03 · closed · 2 comments

### [Test] terminal_snapshot - Element Detection with ffice TUI

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Validate `terminal_snapshot` tool's element detection engine using ffice TUI's rich interface (borders, menus, tables, buttons, input fields, selection states).

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Border detection: Window borders detected with priority 100
- [ ] Menu detection: Menu items detected with re

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/113) · 2025-12-03 · closed · 2 comments

### [Test] terminal_session_create - Headless and Visual Mode Validation

## Epic
Epic: Comprehensive MCP Tools Testing with ffice TUI

## Description
Test `terminal_session_create` MCP tool with ffice TUI application in both headless (PTY-only) and visual (terminal window) modes to validate session initialization, configuration, and lifecycle management.

**Test Application**: `/mnt/d/Projects/ffice-suite/epic-ff-ice-r1-flight-filing-service/ffice-bridge/ffice-tui/bin/ffice`

## Acceptance Criteria
- [ ] Headless mode: Sessions create successfully with default dimens

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/112) · 2025-12-03 · closed · 2 comments

### [Critical Bug] terminal_snapshot hangs indefinitely due to blocking PTY reads

## Problem

`terminal_snapshot` hangs indefinitely when called with `idle_threshold_ms` parameters (500ms, 1000ms, etc.), never returning and blocking all snapshot operations.

**Symptoms**:
- Tool invocation logs: `Capturing terminal snapshot: session_id=..., idle_threshold_ms=Some(500)`
- Function never completes
- No timeout is respected
- Process must be killed manually

**Affected Operations**:
- ✅ `terminal_snapshot` - PRIMARY
- ⚠️ `terminal_wait_for` - Uses similar waiting logic
- ⚠️ Any 

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/99) · 2025-12-03 · closed · 2 comments

## Most recent

### [Task][Documentation][Windows][P3] - Windows testing and documentation

## Summary

Test terminal-mcp on Windows and update documentation with Windows-specific instructions.

## Parent Epic

#147 - Full Windows Support

## Testing Plan

### Manual Testing Checklist

- [ ] Install via npm on Windows
- [ ] Run `terminal-mcp --headless` 
- [ ] Test with Claude Desktop on Windows
- [ ] Test with Gemini CLI on Windows
- [ ] Test TUI apps: htop equivalent, vim, etc.
- [ ] Test Go TUI apps (Bubble Tea)
- [ ] Test Python TUI apps (Textual, Rich)

### Test Scenarios

1. **He

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/151) · 2025-12-18 · open · 1 comment

### [Task][Platform][Windows][P1] - Basic Windows compilation fix

## Summary

Add platform guards to enable Windows compilation. Currently blocked by Unix-specific `libc::kill` call.

## Parent Epic

#147 - Full Windows Support

## Problem

```rust
// session.rs:480 - Unix only!
unsafe {
    libc::kill(handle.pid as i32, libc::SIGTERM);
}
```

## Solution

### 1. Platform-specific process termination

```rust
#[cfg(unix)]
fn kill_process(pid: u32) {
    unsafe { libc::kill(pid as i32, libc::SIGTERM); }
}

#[cfg(windows)]
fn kill_process(pid: u32) {
    use std

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/148) · 2025-12-18 · closed · 1 comment

### [Epic][Platform][Windows][P2] - Full Windows Support

## Summary

Epic tracking issue for full Windows platform support. This enables Windows developers to use terminal-mcp for TUI/CLI application debugging and automation.

## Motivation

- Windows is a major development platform
- Many TUI applications (Go, Rust, Python) run on Windows
- Current codebase uses Unix-specific APIs (`libc::kill`, `tmux`)

## Current State

| Component | Status |
|-----------|--------|
| PTY handling (`portable-pty`) | ✅ Cross-platform |
| Visual terminal implementatio

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/147) · 2025-12-18 · open · 1 comment

### [Feature] windows support

### Problem description

Thanks for really great project. Could you add support Windows for your project?

### Proposed solution

Hope current rust implementation allow to add support windows

### Alternatives considered

_No response_

### Use case

I developed some TUI applications in golang and would like to debug them with code agents under Windows.

### Would you be willing to contribute?

None

### Additional context

_No response_

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/146) · 2025-12-14 · open · external user · 1 comment

### [Bug][Schema][Gemini][P1] - Missing $schema field transformation causes Gemini rejection

## Summary
Gemini CLI rejects terminal-mcp tool schemas with error: `no schema with key or ref "https://json-schema.org/draft/2020-12/schema"`. The schema transformation layer transforms `$defs` and `anyOf` patterns but does NOT update the `$schema` field itself from draft-2020-12 to draft-07.

## Steps to Reproduce
1. Install terminal-mcp v1.0.3 via npm
2. Configure Gemini CLI to use terminal-mcp
3. Try to invoke `terminal_session_create` tool
4. Observe schema validation errors

## Expected Be

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/145) · 2025-12-10 · closed · 1 comment

### [Bug][Session][General][P1] - Visual mode session creation fails after first session closed

## Summary
Creating terminal sessions with `visual: true` fails intermittently after the first session is closed, making iterative testing workflows impossible.

## Steps to Reproduce

**Attempt 1** - Initial Session (SUCCESS):
```json
terminal_session_create({
  "command": "bash",
  "visual": true,
  "dimensions": {"rows": 30, "cols": 100}
})

// Response:
{
  "session_id": "8ef1cadb-4b85-40f2-af78-74901841800a",
  "message": "Session created successfully"
}
```
✅ Session works correctly

**Clo

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/143) · 2025-12-07 · closed · 1 comment

### [Bug][Detector][General][P3] - Snapshot elements detection produces false positives

## Summary
The snapshot `elements` array incorrectly identifies UI elements. Git branch indicators are detected as "buttons", and random text is detected as "progress bars".

## Steps to Reproduce
1. Open a terminal with a git repository prompt showing branch name (e.g., `user@host:/path(main)$`)
2. Take a snapshot with `terminal_snapshot`
3. Examine the `elements` array in the response

## Expected Behavior
Elements should accurately represent interactive UI components:
- Buttons should be clic

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/141) · 2025-12-07 · closed · 1 comment

### [Bug][Emulator][General][P2] - TUI/Interactive menu rendering issues in raw_text

## Summary
Interactive TUI menus (arrow key navigation, selection prompts) are only partially visible in `raw_text`. The rendered snapshot doesn't properly capture the menu state with correct line breaks and structure.

## Steps to Reproduce
1. Create a terminal session
2. Run a command that shows an interactive menu (e.g., `fzf`, selection prompt, breakdown wizard)
3. Take a snapshot with `terminal_snapshot`
4. Examine the `raw_text` field

## Expected Behavior
Menu should be clearly visible wi

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/140) · 2025-12-07 · closed · 1 comment

### [Bug][Emulator][General][P2] - clear command doesn't reset terminal buffer

## Summary
The `clear` command doesn't properly clear the terminal buffer. Old content persists and mixes with new content in snapshots.

## Steps to Reproduce
1. Create a terminal session
2. Run several commands that produce output
3. Run `clear` command
4. Run new commands
5. Take a snapshot with `terminal_snapshot`

## Expected Behavior
Buffer should be cleared after `clear` command. Snapshot should show only content after the clear.

## Actual Behavior
Old content remains in `raw_text`:
```

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/139) · 2025-12-07 · closed · 1 comment

### [Bug][Session][General][P2] - cwd parameter not honored in terminal_session_create

## Summary
The `cwd` parameter in `terminal_session_create` is ignored. Sessions always start in the default directory regardless of the specified working directory.

## Steps to Reproduce
1. Call `terminal_session_create` with:
   ```json
   {
     "command": "bash",
     "cwd": "/mnt/d/Projects/upm-framework/tmp/litpay"
   }
   ```
2. Observe the terminal prompt after session creation
3. Run `pwd` to verify current directory

## Expected Behavior
Terminal should start in `/mnt/d/Projects/upm-f

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/138) · 2025-12-07 · closed · 1 comment

### [Bug][Emulator][General][P1] - Screen buffer corruption after ASCII art display

## Summary
After displaying ASCII art banners (e.g., installation wizards with box-drawing characters), the terminal screen buffer becomes permanently corrupted. Subsequent commands and their output are garbled or mixed with old content.

## Steps to Reproduce
1. Create a visual terminal session
2. Run a command that displays ASCII art with Unicode box-drawing characters (╔═╗║╚╝)
3. Run subsequent commands
4. Take snapshots or read output

## Expected Behavior
Screen should render correctly afte

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/137) · 2025-12-07 · closed · 1 comment

### [Bug][Session][General][P1] - idle wait returns immediately (0ms) without waiting

## Summary
The `terminal_wait_for` with `idle: true` returns immediately with `waited_ms: 0` even when commands are still executing or output hasn't appeared yet.

## Steps to Reproduce
1. Create a terminal session
2. Run a command that takes time (e.g., AI-powered breakdown, npm install)
3. Immediately call:
   ```json
   {
     "session_id": "...",
     "idle": true,
     "timeout_ms": 30000
   }
   ```

## Expected Behavior
Should wait until terminal is truly idle:
- Command has completed exe

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/136) · 2025-12-07 · closed · 1 comment

### [Bug][Snapshot][General][P0] - Command output not captured in snapshots

## Summary
Commands are typed and executed, but their output never appears in `terminal_snapshot` or `terminal_read_output`. Only the command itself is visible in `raw_text`.

## Steps to Reproduce
1. Create a terminal session with `terminal_session_create`
2. Type and execute a command: `./.upm/bin/upm create epic "Test"`
3. Wait for execution using `terminal_wait_for`
4. Call `terminal_snapshot` or `terminal_read_output`

## Expected Behavior
Output should show the command result (success mess

[Read the thread](https://github.com/aybelatchane/mcp-server-terminal/issues/135) · 2025-12-07 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/aybelatchane/mcp-server-terminal/issues).