Skip to content
easl

Docs Reference

Troubleshooting and uninstall

Manage easl's terminal sessions from the shell, fix common snags, and remove every file easl writes.

All docs pages

Terminal sessions

Every terminal tile runs in a zmx session, which is why agents keep running when easl quits. easl’s sessions are named canvas-obj_…. To see or end them without the app:

zmx list                 # every session; easl's are canvas-obj_…
zmx kill <name>          # end one

Closing a terminal tile in easl ends its session too. Closing a tab or window with terminals asks first: Keep Running, End Sessions or Cancel.

Common snags

Symptom What to do
macOS blocks the first launch The app is ad-hoc signed, not notarized. Run xattr -dr com.apple.quarantine /Applications/easl.app, or open it once and choose Open Anyway in System Settings › Privacy & Security. (Right-click › Open works only on macOS 14; macOS 15 removed it.)
Terminal tiles don’t start Terminal tiles need zmx: brew install neurosnap/tap/zmx.
The easl CLI or the omp extension won’t run They need bun: brew install oven-sh/bun/bun.
omp shows no dot Link the omp extension (see Agents), then start a new omp session in a tile.
Gemini CLI shows no dot Gemini CLI 0.60 and later runs as a plain terminal. Use Hyper-V to paste mentions.
A Codex tile is orange right after launch Codex is asking whether to trust the folder. Answer it in the terminal.
“The socket exists but connecting to it failed … a sandbox may be blocking” The agent’s sandbox blocks the easl socket; the app isn’t down. Run the easl command outside the sandbox (Codex: with escalated permission).
A navigation panel says “text search, no language server” Install the server, or point EASL_LSP_<LANGUAGE> at it. See Language servers.
“⚠ git failed: …” in a code tile’s header Git couldn’t answer (cancelled, timed out, failed). It clears on the next load.
Terminal text too small Zoom stops at 100%. Scale the tile with ⌃⌘= (see Navigation).
A page shows “Can’t reach localhost:…” Its server isn’t answering yet. A local address keeps retrying and loads once the server is up; Retry asks now.
Lost on a big board ⌘9 (Zoom to Fit), ⌘[ (Back), or the “Back to content” pill.

What easl leaves alone

easl edits no shell, agent or Ghostty config. It reads your Ghostty config and never writes it. Claude Code, Codex, opencode and Gemini CLI get their integration per session, only inside easl tiles; Codex’s hooks are a per-session override, not written to ~/.codex. Shell history from easl tiles goes to your usual ~/.zsh_history.

Uninstall

  1. End the terminal sessions first, or they keep running: zmx list, then zmx kill <name> for each canvas-obj_… session.
  2. Delete /Applications/easl.app.
  3. Delete ~/Library/Application Support/Easl/ (boards, including archived ones, and open-boards.json).
  4. Delete the browser profile: ~/Library/WebKit/net.waldin.easl/, ~/Library/Caches/net.waldin.easl/, ~/Library/HTTPStorages/net.waldin.easl* (or first use easl › Clear Browsing Data…).
  5. Run defaults delete net.waldin.easl (export folder, lasso setting, window frames).
  6. Delete $(getconf DARWIN_USER_CACHE_DIR)net.waldin.easl and, in $(getconf DARWIN_USER_TEMP_DIR), net.waldin.easl, easl-renders, easl-exports and canvas-gemini.
  7. Delete ~/.local/state/zmx/logs/canvas-obj_*.log.
  8. Remove the omp extension symlink ~/.omp/agent/extensions/easl.ts, and ~/.claude/plugins/data/canvas-inline if you used Claude Code.
  9. Optional, the agents’ own: Codex’s trust_level entries for your repos in ~/.codex/config.toml, and ~/.easl/compositions if you or your agents wrote any.

A board you exported with easl board.export lives in your repository at .easl/board.json; delete it there if you don’t want it.