Critical Stability Issues: App Freezing & Hanging Analysis

[3dyuval]

Problem Statement

Multiple critical stability issues are causing opencode to freeze or hang indefinitely, requiring external intervention to recover. Analysis of 8+ reported issues reveals systematic problems in process management, file handling, and external service integration.

Root Cause Categories

1. File System Bottlenecks

• Large files (multi-GB .tar.gz) cause indefinite hangs
• Synchronous file operations without size limits
• Impact: Complete app freeze, "session is busy" errors

2. Process Management Gaps

• Non-terminating processes make TUI unresponsive
• Missing stdin handling causes sudo command deadlocks
• Impact: ESC key ineffective, 1-minute timeout waits

3. MCP Server Failures ⚠️ Critical Missing Case

• Failed MCP servers cause indefinite hangs during startup/operation
• No timeout or health checks for MCP server connections
• Impact: Complete app freeze when MCP servers fail to start or respond

4. Network/Firewall Conflicts

• Hangs with network monitors (LuLu, Little Snitch)
• No retry logic after firewall approval
• Impact: Requires manual restart after network permission

5. Terminal Integration Issues

• Scroll-related freezes, terminal corruption
• Complex scroll debouncing logic causes instability
• Impact: Complete terminal freeze, affects new sessions

Technical Evidence

Bash Tool Issues (packages/opencode/src/tool/bash.ts:30-38)

const process = Bun.spawn({
  cmd: ["bash", "-c", params.command],
  // Missing: stdin handling, process type detection, size limits
})

MCP Server Initialization (packages/opencode/src/mcp/index.ts:35-42)

const client = await experimental_createMCPClient({
  // ...
}).catch(() => {}) // Silent failure, no timeout

TUI Interrupt Handling (packages/tui/internal/tui/tui.go:256-272)

• Complex debounce logic for interrupts
• No direct process termination capability

Affected Issues

• v0.1.161 - Opencode hangs, presumably from limits, with no error messaging #519 - v0.1.161 hangs with no error messaging
• Launching opencode crashes the file system (Linux) #721 - Launching crashes file system (Linux)
• Starting opencode from source leads to freeze #706 - Starting from source leads to freeze
• Hangs if there is a multi gb .tar.gz file in current directory #683 - Hangs with multi-GB .tar.gz files
• TUI becomes unresponsive upon running a non-terminating process such as a web server #682 - TUI unresponsive with non-terminating processes
• App becomes unresponsive when executing commands requiring sudo password #652 - Unresponsive with sudo commands
• Terminal freezes sometimes and cant open a new session #471 - Terminal freezes, can't open new sessions
• bug: hangs with firewall/network monitor #421 - Hangs with firewall/network monitors
• big mess in terminal when MCP server fails #504 - Big mess in terminal when MCP server fails

Proposed Solutions

Phase 1: Critical Fixes (Immediate)

1. File Size Guards - Add size validation before processing
2. MCP Timeouts - Connection timeouts and health checks for MCP servers
3. Command Detection - Identify interactive/long-running commands
4. Process Interruption - Basic process termination capabilities

Phase 2: Architectural Improvements

1. Streaming File Operations - Progressive loading with size limits
2. Network Circuit Breakers - Retry logic and graceful degradation
3. Resource Management - Memory/CPU limits and monitoring
4. Error Boundaries - Component isolation and recovery

Success Criteria

• ✅ Zero indefinite hangs on large files
• ✅ Reliable process interruption with ESC key
• ✅ Clean recovery from MCP server failures
• ✅ Stable terminal behavior across platforms
• ✅ Clear error messages when operations are blocked

Documentation

• Branch: stability-analysis-issue
• Full analysis: STABILITY_ANALYSIS.md
• Architectural decisions: ARCHITECTURAL_DECISIONS.md
• Implementation roadmap: 8 ADRs with phased approach

Priority: Critical - These issues make opencode unusable in common scenarios and require external intervention to recover.

---

Analysis based on issues #519, #721, #706, #683, #682, #652, #471, #421, #504 + comprehensive codebase review

[RingOfStorms]

This is the closest issue I could find and I assume it may be related but I haven't confirmed/gathered a lot of evidence yet to know if the things OP posted cause memory leaks. But if you leave opencode open for a long time (1d20h10m16s) I notice it running away with processes and memory/CPU consumption.

Opening htop showed tens to a hundred or so child process of cache..tui something or other running. Next time it happens I will come back and report more details on that since I did not copy or screenshot it.

When I killed opencode I noticed that it was using up ~16GB of memory at that point.

[RingOfStorms]

After 9h40m59s hours of leaving open code open

USER         PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
josh     1847241 99.4  1.7 78635084 1131508 pts/3 Sl+ Jul13 577:03 opencode
josh     1847313  152  0.0 1580444 58220 pts/3   Sl+  Jul13 887:40 /home/josh/.cache/opencode/tui/tui-63z1eeqs.

I will add I think it is related to spawning LSP servers which seems related to the OP. Even after exiting open code the clippy-drivers/rust-analyzer for my rust projects stays open in processes using a bunch of CPU and memory as well.

[almirsarajcic]

For me, in a few sessions, it started hanging, just writing working... without giving me any response for prolonged periods. I don't think my case was related to usage limits because in another session I was running in parallel, it was working at that time.

When I ran opencode auth and logged in with my Claude Code subscription, the problem seemed to have disappeared. I'll post if it continues.

Nope, logging in again didn't help. I've encountered the issue again, but haven't had logging enabled. I'll update with logs when I come across it again.

Seems like in my case, it hangs when I'm idle for a few minutes and ask it something again.

[RingOfStorms]

I believe my stuff has been fixed in the latest versions, seems like stability with LSPs was my main issue that got many improvements the last week.