🕌

The reason why I switch from cmux to sesh

に公開

I did not switch because of features. I switched because of failure modes.

For a while, cmux looked like the right abstraction. It tried to unify session management, workspace switching, and command orchestration into a single interface. In small setups, that works. In a real repository with multiple worktrees, remote branches, and inconsistent environments (WSL2, mixed package managers), the abstraction becomes the problem.

The core issue is coupling. cmux assumes that session state, filesystem layout, and tooling behavior remain predictable. That assumption does not hold in practice. When something breaks, it is rarely isolated. A mismatch in PATH, a stale binary, or a partially broken Git reference propagates upward and manifests as a session failure. Debugging becomes indirect: you are not fixing tmux or Git, you are reverse-engineering the wrapper.

The breaking point came from Git integration. Tools that implicitly depend on repository invariants—such as a valid origin/HEAD or consistent worktree metadata—fail in non-obvious ways. When a wrapper tool encodes those assumptions, it inherits all edge cases of Git internals without exposing them clearly. The result is brittle behavior under perfectly valid but slightly irregular states.

Switching to sesh was not about gaining features. It was about removing hidden ones.

sesh does one thing: it maps directories to sessions. That constraint is deliberate. It does not attempt to understand Git. It does not infer branch state. It does not modify execution flow based on repository structure. Each session is just a working directory with a persistent terminal context.

That design has several practical consequences.

  • Failure is localized
    If a Git worktree is broken, only that directory is affected. sesh still launches the session. There is no orchestration layer to fail beforehand.

  • State is transparent
    A session corresponds directly to a path. There is no hidden mapping, no generated metadata, and no internal registry that can drift out of sync.

  • Tooling remains composable
    Git, shell, and editor behave exactly as they would outside sesh. There is no wrapper altering arguments or injecting flags.

  • Debugging is linear
    When something fails, the stack is explicit: shell → Git → filesystem. There is no intermediate layer to inspect.

This shift also forces a different workflow model.

Instead of “create a branch and let the tool manage everything,” the workflow becomes:

  • create or attach a worktree explicitly
  • enter it via sesh
  • run tools directly

That looks like more manual work, but in practice it is more predictable. The cost of typing an extra command is lower than the cost of diagnosing a hidden state machine.

There are trade-offs.

sesh does not manage Git worktrees. It does not create branches. It does not coordinate multi-session automation. If the goal is a tightly integrated environment where one command provisions everything, sesh is insufficient. It deliberately avoids that scope.

But that limitation is also its strength. By refusing to own the workflow, it avoids becoming a single point of failure.

In environments like WSL2, where path resolution, package managers, and binaries can diverge subtly, this matters. A thin layer that does not interpret state is more reliable than a thick layer that tries to normalize it.

The switch, then, is not about preference. It is about control over invariants.

cmux optimizes for convenience by abstracting complexity. sesh optimizes for correctness by exposing it.

In a stable environment, both approaches can work. In a system where inconsistencies are inevitable, the latter degrades more gracefully.

Discussion