Troubleshooting¶

Common issues and solutions when using AgentSentinel.

tmux Issues¶

Install tmux via Homebrew:

brew install tmux

Start a tmux session first:

tmux new-session -s agents

Then run AgentSentinel.

Check that tmux is running and has panes:

# List all tmux sessions
tmux list-sessions

# List all panes
tmux list-panes -a

If no panes are listed, start a tmux session first.

Enable verbose logging
```
agentsentinel watch -v
```
Check the prompt is in the visible area

AgentSentinel captures the last 30 lines by default. If the prompt scrolled up:
```
agentsentinel watch --lines 50
```
Run the test command
```
agentsentinel test
```
Check the exact prompt format

The prompt may use a different format than expected. Run agentsentinel status and manually inspect the pane content:
```
tmux capture-pane -t %1 -p | tail -30
```
Add a custom pattern

If the prompt format isn't covered by built-in patterns:
```
# ~/.agentsentinel.yaml
patterns:
  - "(?i)my-custom-prompt"
```

Use dry-run mode to see what's being detected:

agentsentinel watch --dry-run -v

If unwanted prompts are being matched, the built-in patterns may be too broad for your use case. Consider filing an issue.

Verify the pane ID
```
agentsentinel status
```
Test manually

Send a keystroke directly to verify tmux can interact with the pane:
```
tmux send-keys -t %1 y Enter
```
Check CLI focus

Some CLIs may require focus or specific terminal state. Ensure the CLI is waiting for input.
Check for duplicate prevention

If you recently approved the same pane, AgentSentinel waits 5 seconds before re-approving. Wait and try again.

This shouldn't happen with the default duplicate prevention. If it does:

Check the path
```
agentsentinel config path
```
Verify YAML syntax
```
agentsentinel config show
```
If this errors, there's a syntax issue in your config file.
Common YAML mistakes
- Missing spaces after colons: interval:1s → interval: 1s
- Incorrect indentation (use spaces, not tabs)
- Unescaped special characters in patterns

Check YAML escaping

Backslashes must be doubled in YAML:

patterns:
  - "(?i)deploy\\s+to\\s+production\\?"  # Correct
  - "(?i)deploy\s+to\s+production\?"     # Wrong

Reduce scan frequency:

agentsentinel watch --interval 2s

If approvals seem delayed:

Check System Preferences

Go to System Preferences → Notifications and ensure "Script Editor" or terminal app has notification permissions.

Test osascript directly

osascript -e 'display notification "Test" with title "AgentSentinel"'

If none of these solutions work:

Check existing issues

GitHub Issues
File a new issue

Include:
- AgentSentinel version: agentsentinel version
- macOS version
- tmux version: tmux -V
- Verbose log output: agentsentinel watch -v
- The exact prompt text you're trying to detect