Troubleshooting

Start with the log

The server writes what it does to server.log, usually ~/.local/state/cornercase/server.log, including everything it couldn’t do and why. cornercase logs prints the end of it. See The server log.

Installing and updating

cornercase: command not found after installing

The install script puts cornercase in ~/.local/bin and adds that folder to the PATH in your shell profile, which only new shells read. Open a new terminal, or run ~/.local/bin/cornercase directly.

GLIBC_2.35' not found

The prebuilt Linux binaries need glibc 2.35 or newer (Ubuntu 22.04 or later, and similar). On an older system, build from source.

An update fails

The update dialog shows what went wrong in red, keeps the old binary, and offers try again. cornercase update prints the same errors and also keeps the old binary:

• the download does not match its checksum: the download was cut short or altered on the way. Try again.
• the new cornercase does not run here: …: the new binary was downloaded but couldn’t start on this machine, for instance because glibc is older than 2.35. The old one stays in place.
• GitHub answered … for …, or a network error: the download didn’t get through. Check your connection and try again later.

You can always update by hand with the install script or brew update && brew upgrade cornercase; see Update.

No update shows up

cornercase checks when the server starts and then every hour, and only if settings → UI → check for updates is on; builds made with cargo run never check. A release that came out less than an hour ago may not have been seen yet. Run cornercase update to install it right away. When the check itself fails, server.log says why, in a line with update: check failed.

Turning update checks off

Set settings → UI → check for updates to never, or "check_updates": false in config.json. cornercase then never contacts GitHub, and you update with the install script or Homebrew when you choose.

Building from source

The build fails in Ghostty or Zig

Ghostty’s terminal core only builds with Zig 0.15.2. Check:

zig version

If it prints anything else, download 0.15.2 from ziglang.org/download and put it first on your PATH. Package managers often ship a newer Zig.

On macOS, also make sure the Xcode Command Line Tools are installed: xcode-select --install.

The first build is slow or fails to download

The first build downloads Ghostty’s sources and compiles them, which takes a couple of minutes and needs network access. If you already have a Ghostty checkout, set GHOSTTY_SOURCE_DIR to its path to skip the download.

Starting

“The running cornercase server comes from another build”

You installed a new version while the old server is still running, and a client never attaches to a server from another build, so cornercase asks whether to restart it. Save your work in the panes and answer y: your layout comes back, with new shells.

If you answered no, or ran it without a terminal, it stops with the running cornercase server comes from another build instead. Restart the server yourself when you’re ready:

cornercase kill-server
cornercase

The same goes for “the running cornercase server is incompatible with this build”.

“cornercase is already running in this terminal; nesting it is not supported”

You ran cornercase from a pane of cornercase itself, where CORNERCASE=1 is set. Open it from another terminal window instead.

“no cornercase server is running”

The commands for scripts and agents talk to a running server and never start one, except cornercase start-server. Run cornercase first, or cornercase start-server without a window. If cornercase is running, check that the command uses the same socket: a different CORNERCASE_SOCKET, XDG_STATE_HOME or HOME points it at another server. Set XDG_STATE_HOME where every shell reads it, not only in an interactive rc file.

“the running cornercase server is too old for cornercase …”

The server started before you updated to a version with that command. Save your work in the panes, then restart it:

cornercase kill-server
cornercase

“failed to start the cornercase server”

The server didn’t come up within five seconds. The message names its log file; open it to see why. If you use CORNERCASE_SOCKET, check that the folder can be created and that the path is short: Unix socket paths are limited to about 100 bytes. If your home folder is on a network disk, see “cannot listen on …” below.

“refusing to use …: it can be written by other users”

cornercase keeps its socket in a folder only you can use, next to your session: ~/.local/state/cornercase (or $XDG_STATE_HOME/cornercase). It refuses a folder that belongs to another user or that is a symbolic link, because whoever controls that folder could pose as the cornercase server and see what you type. A folder only you own that is too open (the usual 0775) is not refused: cornercase makes it private itself. The message names the folder and what is wrong with it.

What to do depends on where the folder comes from.

cornercase’s own folder (you didn’t set CORNERCASE_SOCKET). It holds your session, stats, TODOs and logs, so never remove it. Check who owns it with ls -ld on that path:

• It is a symbolic link: put the real folder there instead of the link (move the link’s target to that path), or point XDG_STATE_HOME at the folder you want.
• It belongs to another user: someone may be trying to pose as cornercase, or it was created with sudo. If you own the machine, fix it with sudo chown -R "$USER" ~/.local/state/cornercase; otherwise tell whoever runs it. Until then, point CORNERCASE_SOCKET at a socket in a folder only you can write to, for example export CORNERCASE_SOCKET=~/.cornercase/server.sock. With it set, cornercase keeps its settings and session next to that socket, so it starts with default settings and a new session (see Files and environment).

The folder of your own CORNERCASE_SOCKET: don’t remove it, since it may hold your other files. Point CORNERCASE_SOCKET at a socket in a folder only you can write to instead. A CORNERCASE_SOCKET without a folder, such as server.sock, uses the folder you start cornercase from.

“the cornercase socket … is … bytes long”

A Unix socket path can have at most 107 bytes (103 on macOS). Set XDG_STATE_HOME to a shorter folder, or CORNERCASE_SOCKET to a shorter path. With either, cornercase keeps its settings and session next to the socket.

“cannot listen on …”

The disk holding that folder cannot hold a socket or a lock, as some network disks cannot. Set XDG_STATE_HOME to a folder on a local disk, or CORNERCASE_SOCKET to a socket on one.

“a cornercase server holds the lock … but does not answer there”

A server that uses the same folder is stuck, or runs on another machine that shares your home folder. Stop it there, or give this machine its own socket with CORNERCASE_SOCKET on a local disk.

“the other end of the cornercase socket belongs to another user”

Where you see it tells you which side refused:

• In your terminal, when you start cornercase or run cornercase kill-server: the socket is served by a process of another user, so cornercase refuses to talk to it. Check who owns the socket with ls -l on it, and handle it like a socket folder that belongs to another user (above).
• In server.log, in a line with server: connection refused: a process of another user tried to connect to your cornercase server and was turned away, so nothing reached your shells. The line gives that user’s uid. Another user can only reach your socket when its folder lets others in (the folder cornercase creates doesn’t) and the socket is writable by them, as a loose umask leaves it. Make the folder private with chmod 700 on it, and tell whoever runs the machine.

My session didn’t come back

Sessions are restored only by a new server, and projects or workspaces whose folders no longer exist are skipped. The session is saved two seconds after your layout last changed, so a change made right before a crash or a power cut may be missing.

If some tabs were missing and a message said could not restore … see server.log, their shells couldn’t start: server.log says why, and the session as it was saved is in session.json.bak (an older copy, if there was one, in session.json.bak.1). To get it back, stop the server (cornercase kill-server) and copy session.json.bak over session.json.

An agent didn’t resume its conversation

Claude Code, Codex, Gemini CLI, Grok Build, Cursor CLI and GitHub Copilot CLI resume, and only a conversation that had something in it when the server stopped. cornercase remembers it while the agent runs, so one started a second or two before the server stopped may be missed. If the pane shows the resume command and then an error such as No conversation found, the conversation was deleted or lives under another account or config folder (CLAUDE_CONFIG_DIR, CODEX_HOME) than the shell’s; run claude --resume or codex resume there to pick one. If no pane resumes, check that settings → Agents → resume conversations is on.

Using cornercase

“cornercase hit a bug, see server.log”

Something went wrong inside cornercase itself. It dropped only what it was doing at that moment and carried on: your shells and agents keep running. A dialog or menu you had open may have closed. A dialog that was waiting for something in the background, such as creating a worktree, shows the message in red instead; close it or try again. A command for scripts and agents that was running, such as cornercase wait, fails with the same message.

server.log says where it happened, in a line with ERROR panic: thread 'main' panicked at (or another thread’s name), followed by a backtrace. The lines before it show what led there. Please open an issue with those lines and what you were doing. A bug that keeps happening is written in full only the first time, then without the backtrace and ever more rarely.

If the message keeps coming back, or the screen stays blank, the bug happens every time cornercase checks or draws something. Your shells still run, so finish what you’re doing, then restart the server with cornercase kill-server (it closes them) and start cornercase again, or update once a fix is out.

Copying doesn’t reach my clipboard

cornercase copies with the OSC 52 escape sequence, which your terminal has to allow:

• iTerm2: enable Applications in terminal may access clipboard in the settings.
• tmux (when cornercase runs inside it): set -g set-clipboard on.

Over SSH, it’s your local terminal that needs to allow it.

No desktop notification shows up

• Only a tab you aren’t looking at notifies you, and only when Claude Code runs in it; see Notifications.
• Check that settings → UI → desktop notifications isn’t off. With auto, cornercase picks from your terminal’s name; if it picks wrong, for example over SSH with a terminal that doesn’t say its name, choose the one your terminal understands.
• Your system must let your terminal show notifications: on macOS, in System Settings → Notifications.
• iTerm2 shows them only with Notification Center Alerts on, in Settings → Profiles → Terminal.
• foot shows them with notify-send, which has to be installed.
• Ghostty on macOS, foot, Konsole and Warp don’t show one while their window is in front, and kitty, Contour, VS Code, foot 1.18 or later and Konsole 24.12 or later are asked not to: look for the toast.
• Inside tmux, screen or Zellij, cornercase only rings the bell, which your multiplexer decides what to do with.

No sound plays

• Check that settings → UI → sound is on. Only a tab you aren’t looking at plays one, a second after the agent needs you or finishes.
• Agents started by another agent or by a flow play none unless sound for subagents is on.
• It plays on the computer the window is on, with afplay on macOS and the first of pw-play, paplay and aplay on Linux; with none of them installed, nothing plays. A window opened in a plain SSH session plays none: use cornercase remote.
• A tmux session started over SSH keeps SSH_CONNECTION when you reattach to it on the computer itself, so a window opened in it still counts as remote and plays none. Open cornercase outside that session, or run tmux set-environment -gu SSH_CONNECTION and tmux set-environment -gu SSH_TTY, then open a new pane.
• A file of your own that is missing or can’t be read plays the built-in sound, and so does a path that is neither absolute nor starts with ~/; aplay reads only WAV.

open in… shows copy path, or misses an app

• It opens on the computer the window is on, so only a local window offers it. A window from cornercase remote, your phone’s browser or a plain SSH session shows copy path, since the folders are on the other computer.
• A tmux session started over SSH keeps SSH_CONNECTION when you reattach to it on the computer itself, so a window opened in it still counts as remote. Open cornercase outside that session, or run tmux set-environment -gu SSH_CONNECTION and tmux set-environment -gu SSH_TTY, then open a new pane.
• An editor appears when its command is on the PATH (code, cursor, zed, subl), or on macOS when its app is in /Applications or ~/Applications. On Linux Zed’s command is often zeditor; a zed outside a zed.app folder is ignored, since on some systems that name is ZFS’s daemon.
• On Linux every choice needs a graphical session (WAYLAND_DISPLAY or DISPLAY); on a text console the menu shows copy path. The file manager and default app also need xdg-open; the editors only need their own command.
• default app is offered for plain files only, never for a folder or a program you could run.
• When an app can’t start, a toast says could not open in … with the reason.

A click on a notification doesn’t take me to the agent

Only kitty, VS Code, Contour, foot 1.18 or later and Konsole 24.12 or later report a click; Ghostty, iTerm2, WezTerm and Warp only bring the window forward. Use the go button of the toast, which comes back when you return to the window, in any terminal. Inside tmux, screen or Zellij cornercase only rings the bell, so there is nothing to click. If text like 99;i=cc-… appears in a shell, a notification was clicked after its window was killed or lost its connection, so cornercase could not close it first; it is harmless.

An image shows a message instead of the picture

Your terminal can’t draw pictures, or something between it and cornercase stops them, such as tmux without passthrough. The message says which and what to do; every message and its fix is in When a picture doesn’t show. cornercase checks your terminal when it starts, so after changing a setting, quit it with Quit and start it again.

If the panel stays empty instead, with no message:

• iTerm2 may be waiting for your answer to Allow Terminal-Initiated Display?, or remember that you declined it; see iTerm2 asks first.
• tmux with allow-passthrough on drops a picture sent while cornercase’s window is hidden. Open the file again, or use all (tmux 3.4 or later); see Inside tmux.
• CORNERCASE_IMAGES may name a protocol your terminal doesn’t understand. Start cornercase without it.

Dragging doesn’t select text

The program in the pane is using the mouse, so the drag goes to it. Many such programs have their own way to select and copy, or a setting to turn their mouse support off.

Right-click doesn’t open the pane menu

That pane sends right-clicks to its program while the program uses the mouse. Quit the program or turn its mouse support off, then right-click and choose use this menu on right-click.

Shift+Enter or Ctrl+Enter arrive without the modifier

cornercase asks your terminal to report these keys unambiguously, using the kitty keyboard protocol’s first level. Terminals that don’t support it can’t tell Shift+Enter from Enter. Use a terminal that supports the protocol.

Colours look wrong after changing my terminal theme

The server reads your terminal’s colours once, from the first client that attaches to it. Restart it with cornercase restart (or settings → restart) to pick up a new theme.

The merged PRs row is missing from Stats

The row shows only after gh (GitHub) or glab (GitLab) answered, and counts only repositories that an open project has as a remote. Check that gh auth status or glab auth status lists an account, that the project has a remote (git remote -v), and read Settings → Worktrees → merged PRs in stats: its note names the accounts read or says why none were. A + after a number means one account failed or a search was too large; server.log has a pr line with the reason. cornercase stats reads the row only from a running server.

Issues and agents

The GitHub tab is empty or shows an error

• this project is not in a git repository: open the repository’s folder as the project.
• An error mentioning gh: install the GitHub CLI and run gh auth login. If gh isn’t on the server’s PATH, set its path with the gh key in config.json.

GitLab, Shortcut, Linear, Jira, Plane or Asana rejects my token

Create a new one (GitLab: Edit profile → Access tokens, with the read_api scope; Shortcut: Settings → Your account → API Tokens; Linear: Settings → Security & access → Personal API keys; Jira: Security → Create and manage API tokens at id.atlassian.com; Plane: Profile settings → Personal access tokens; Asana: Settings → Apps → Developer apps) and paste it in the tracker’s tab of the issue browser. If GITLAB_TOKEN, SHORTCUT_API_TOKEN, LINEAR_API_KEY, JIRA_API_TOKEN, PLANE_API_KEY or ASANA_ACCESS_TOKEN is set, it is used instead of what you paste: fix or unset the variable, then restart the server.

For Jira, the token is sent with your site and email: check them in settings → Issues → Jira. Use a classic API token; tokens with scopes only work through Atlassian’s gateway, which cornercase doesn’t use. no Jira site at … means the site is misspelled.

For Plane, the key is checked together with your workspace: no Plane workspace named … means the workspace is misspelled (it is the part after the server’s name in Plane’s address), and a self-hosted server needs its address in settings → Issues → Plane → Plane URL.

For Asana, Asana rejected the access token means the token was revoked or mistyped. this Asana account has several workspaces (…) means the token belongs to more than one and none is chosen: set Asana workspace in settings → Issues → Asana (a name or an ID), or pick one when the issue browser asks. no Asana workspace named … means the setting names none of yours. this needs a paid Asana plan means Asana refused a request for plan reasons; the list doesn’t use Asana’s premium search, so this is unexpected. Asana rate limit reached means too many requests in a minute (150 on free plans): try again in a minute.

For GitLab, the token is checked against the server in settings → Issues → GitLab → GitLab URL (gitlab.com when empty): a token made on your company’s server is rejected by gitlab.com.

The GitLab tab finds no project

The GitLab tab lists the issues of the project the repository’s remote points to, on the server in settings → Issues → GitLab → GitLab URL.

• no remote of this repository is on …: the remotes it names are on other servers. For a self-hosted GitLab, set its address as the GitLab URL. A remote that uses a host alias from ~/.ssh/config isn’t recognised: add a remote with the server’s real name, such as git remote add gitlab git@gitlab.acme.dev:team/shop.git.
• no GitLab project … or the token cannot see it: GitLab hides private projects from tokens without access to them. Check that the token’s user is a member of the project.

The agent doesn’t start

cornercase types the agent’s command in a new shell. If the shell is still in the foreground three seconds later, it gives up and writes the agent did not start to the log. Usually the command isn’t found:

• try typing the command yourself in a new tab;
• make sure it is on the PATH of the shell inside cornercase;
• or tell cornercase where it is with agent_commands.

Usage is unavailable

The Limits tab of the Usage dialog runs claude and codex on the server’s machine and waits up to ten seconds for each answer. cornercase usage runs the same probes and prints the same text after usage unavailable: (error in --json). The message says what went wrong with that agent:

• could not run claude or could not run codex: the agent isn’t on the PATH the server started with. Tell cornercase where it is with agent_commands, or restart the server from a shell where it is found.
• did not answer in time or exited without answering: run the agent yourself in a tab and check that it starts and that you are logged in. An older version may not know how to answer; update it.
• unexpected answer: the agent answered in a shape cornercase doesn’t understand, probably after an update. Please open an issue.
• Any other message comes from the agent, or from reading its answer.

The trust question isn’t answered

By default it is left to you: answer it in the tab, and the prompt is pasted once the agent is ready. To have cornercase answer it, turn on settings → Agents → trust prompts. If it is on and your agent words the question differently, extend trust_prompt_pattern in config.json so it matches.

The prompt never shows up after the trust question

cornercase waits while the question is on screen. If your agent’s normal screen happens to match trust_prompt_pattern in its last lines, cornercase keeps waiting: narrow the pattern in config.json.

The prompt isn’t sent

By default the prompt is typed and left for you to press Enter. Turn on settings → Agents → send the prompt to have it sent for you.

The server log

The server writes one line for each thing it does: a window attaching and at what size, a command from a script and its answer, a tab or pane opening and closing (and how its shell exited), an agent starting step by step and every change of its status, a dialog opening, a git run or issue list that failed or took long, and every error and bug. Each line starts with the time (in UTC), the level and where it happened:

2026-10-07T21:09:50.112Z INFO  control: start client=12 agent=claude worktree=fix-login prompt=true wait=false focus=false
2026-10-07T21:09:51.482Z INFO  worktree: add done ms=812 project=4 branch=fix-login path=/home/me/.cornercase/worktrees/app/fix-login issue=false
2026-10-07T21:09:51.490Z INFO  app: tab opened id=31 workspace=30

It never holds what you type or paste, what programs print, the prompts and issues sent to agents, or tokens: commands that carry text log only its size. Paths and the names of projects, workspaces and tabs are in it.

cornercase logs              # the last 200 lines
cornercase logs -n 1000      # more
cornercase logs --follow     # keep printing as it writes, until Ctrl+C
cornercase logs --path       # where it is

It lives in ~/.local/state/cornercase/server.log ($XDG_STATE_HOME/cornercase/ when that is set), or next to the socket when CORNERCASE_SOCKET is set, so it survives a logout or a reboot. Past 8 MiB it moves to server.log.1 and a new one starts. To see more, such as every key name and click the server handled and every git run, restart the server with CORNERCASE_LOG=debug:

cornercase kill-server       # closes every shell
CORNERCASE_LOG=debug cornercase

Still stuck?

Open an issue with what you did, what you expected and what happened, plus the relevant lines from cornercase logs. Not sure it is a bug? Ask on Discord first. Security problems go through private vulnerability reporting instead.