Troubleshooting

An agent shows the wrong state

Run modisa debug detect <pane> to see the rule that matched and the screen it read. A new agent version may draw something the rules don't know yet: override the agent's rules in ~/.config/modisa/adapters/.

Something changed but nothing's different

A running session keeps the modisa it started with. modisa restart loads the new one (agents resume), then detach and reattach to refresh the client too.

Logs

Each session's server logs to ~/.local/state/modisa/<session>.log.

An integration says “update available”

It was installed by an older modisa, or modisa has moved. modisa integration install all brings every one up to date.

An agent in a sandbox can't reach modisa

Some agents run their commands in a sandbox that blocks modisa's socket. Their modisa commands then fail with “can't connect to its socket: a sandbox is blocking it”. You can still message that agent, but it can't send, read panes or spawn agents.

Codex on macOS blocks Unix sockets unless its commands have network access. Give them a permissions profile that allows it in ~/.codex/config.toml, then restart Codex:

default_permissions = "modisa"

[permissions.modisa]
extends = ":workspace"

[permissions.modisa.network]
enabled = true

This also lets Codex's commands reach the internet. Codex rejects a config that sets both this and sandbox_mode, so use one or the other.

No sound

Check the sound section of the settings page and your output device. Sounds are generated and played by modisa itself, so nothing else needs installing.