AgentSentinel

Auto-approve tool requests for AI coding CLIs running in tmux.

AgentSentinel monitors tmux panes for tool approval prompts from AI coding assistants and automatically responds with y to approve them. Designed for macOS with iTerm2 and tmux.

Supported AI CLIs

AWS Kiro CLI - tool use read requires approval, press 'y' to approve
Claude Code - Allow? (Y/n)
Codex CLI - Proceed? (Y/n)
Gemini CLI - (Y/n) prompts

Requirements

macOS
tmux 3.0+
Go 1.21+ (for building)

Installation

Option 1: Install to PATH (recommended)

# Install to ~/go/bin (make sure ~/go/bin is in your PATH)
go install github.com/plexusone/agentsentinel@latest

# Verify installation
agentsentinel version

Option 2: Build locally

git clone https://github.com/plexusone/agentsentinel.git
cd agentsentinel
go build -o agentsentinel .

# Run from current directory
./agentsentinel version

Quick Start

Step 1: Start tmux first

# In iTerm2, start tmux
tmux new-session -s agents

Step 2: Run your AI CLI inside tmux

# You're now inside tmux, start your AI CLI
kiro
# or: claude
# or: codex

Step 3: Run AgentSentinel (3 options)

Option A: In another tmux pane (recommended)

# Split the tmux window
# Press: Ctrl+b "  (horizontal split)
# or:    Ctrl+b %  (vertical split)

# In the new pane, run:
agentsentinel watch -v

Option B: In a separate iTerm2 tab (outside tmux)

# Open new iTerm2 tab (Cmd+T)
# Don't start tmux, just run directly:
agentsentinel watch -v

Option C: Background tmux session

# From anywhere, create a detached session:
tmux new-session -d -s sentinel 'agentsentinel watch -v'

Step 4: Watch it work

┌─────────────────────────────────────┐
│ tmux pane 1: kiro                   │
│                                     │
│ > tool use read requires approval,  │
│   press 'y' to approve              │  ← AgentSentinel detects this
│                                     │
├─────────────────────────────────────┤
│ tmux pane 2: agentsentinel watch -v │
│                                     │
│ INFO prompt detected pane=%1        │
│ INFO approved pane=%1               │  ← Sends 'y' to pane 1
└─────────────────────────────────────┘

Key Point

AgentSentinel monitors tmux from the outside - it uses tmux commands to read pane contents and send keystrokes. It doesn't run "inside" your AI CLI. It runs separately and watches all tmux panes.

Quick Test

# Check AgentSentinel can see your tmux panes
agentsentinel status

# Dry run to see what it would approve (without actually approving)
agentsentinel watch --dry-run -v

Advanced Usage

Where to Run AgentSentinel

AgentSentinel communicates with tmux via commands (tmux list-panes, tmux send-keys), so it works from anywhere:

Location	Pros	Cons
Tmux pane	See logs alongside agents	Uses a pane
Separate iTerm2 tab	Doesn't use tmux space	Switch tabs to see logs
Background session	Out of the way	Need to attach to see logs

Multi-Agent Layout (3 panes)

Running multiple AI agents with AgentSentinel in a dedicated pane:

┌────────────────────────────────────────────────────────┐
│ iTerm2                                                 │
│ ┌─────────────────────┬─────────────────────┐          │
│ │ tmux pane 1         │ tmux pane 2         │          │
│ │ $ kiro              │ $ claude            │          │
│ │                     │                     │          │
│ │ Agent working...    │ Agent working...    │          │
│ │ tool use requires   │ Allow? (Y/n)        │          │
│ │ approval, press 'y' │        ↑            │          │
│ │        ↑            │        │            │          │
│ │        │            │        │            │          │
│ │        └────────────┴────────┘            │          │
│ │                     │                     │          │
│ ├─────────────────────┴─────────────────────┤          │
│ │ tmux pane 3                               │          │
│ │ $ agentsentinel watch -v                  │          │
│ │ INFO starting watcher session="all"       │          │
│ │ INFO prompt detected pane=%1 type=Approve │          │
│ │ INFO approved pane=%1                     │          │
│ └───────────────────────────────────────────┘          │
└────────────────────────────────────────────────────────┘

Multi-Agent Workflows

AgentSentinel handles multiple concurrent agents across different panes. It also supports Kiro's multi-subagent TUI where multiple subagents run in the same pane with a navigable approval list.

When Kiro runs 4 concurrent subagents, AgentSentinel automatically:

Detects multiple pending approval prompts in the same pane
Cycles through all items using y (approve) + j (navigate down)
Covers all pending approvals regardless of cursor starting position

# Watch all tmux sessions and panes
agentsentinel watch

# Watch a specific tmux session
agentsentinel watch --session my-agents

# Faster scanning for responsive approval (default: 1s)
agentsentinel watch --interval 500ms

Background with Logging

# Run in background, log to file
agentsentinel watch -v > ~/agentsentinel.log 2>&1 &

# Check logs
tail -f ~/agentsentinel.log

# Stop it
pkill agentsentinel

Commands

watch

Monitor tmux panes and auto-approve tool requests.

agentsentinel watch [flags]

Flags:
  -i, --interval duration   Scan interval (default 1s)
  -s, --session string      Watch specific tmux session only
      --dry-run             Detect but don't approve
      --block-danger        Block dangerous commands (default true)
      --lines int           Lines to capture per pane (default 30)
      --stats               Enable statistics tracking
      --notify              Enable macOS notifications
  -v, --verbose             Verbose output

status

Show tmux environment and available panes.

agentsentinel status

Example output:

AgentSentinel Status
====================

tmux: installed
tmux server: running
current session: dev

Panes (4 total):

  %1 (session: $0, window: @0, index: 0)
  %2 (session: $0, window: @0, index: 1)
  %3 (session: $0, window: @1, index: 0)
  %4 (session: $1, window: @2, index: 0)

Run 'agentsentinel watch' to start monitoring for tool prompts.

test

Verify prompt detection is working.

agentsentinel test

version

agentsentinel version

config

Manage configuration file.

# Show config file path
agentsentinel config path

# Show current configuration
agentsentinel config show

# Create example config file
agentsentinel config init

# Print example configuration
agentsentinel config example

completion

Generate shell completion scripts.

# Bash
agentsentinel completion bash > /usr/local/etc/bash_completion.d/agentsentinel

# Zsh
agentsentinel completion zsh > "${fpath[1]}/_agentsentinel"

# Fish
agentsentinel completion fish > ~/.config/fish/completions/agentsentinel.fish

Configuration

AgentSentinel can be configured via ~/.agentsentinel.yaml:

watch:
  interval: 1s
  session: ""
  lines: 30
  block_danger: true

# Custom patterns to detect
patterns:
  - "my-custom-prompt"

# Custom dangerous command patterns
danger_patterns:
  - "drop database"

notifications:
  enabled: true
  sound: true
  title: "AgentSentinel"

stats:
  enabled: true
  log_file: ~/agentsentinel-approvals.log

Run agentsentinel config example for a full example with comments.

Safety Features

Dangerous Command Blocking

By default, AgentSentinel blocks auto-approval for dangerous commands:

rm -rf
sudo rm
mkfs
dd if=
curl ... | bash
wget ... | sh
chmod -R 777 /

When detected, you'll see:

WARN dangerous command detected, skipping auto-approval pane=%3

To disable (not recommended):

agentsentinel watch --block-danger=false

Dry Run Mode

Always test with --dry-run first to see what would be approved:

agentsentinel watch --dry-run -v

Duplicate Prevention

AgentSentinel tracks recently approved panes to prevent sending multiple approvals to the same prompt.

Notifications (macOS)

Enable macOS notifications to see when approvals happen:

agentsentinel watch --notify

Or in config:

notifications:
  enabled: true
  sound: true

Statistics

Track approval statistics during a session:

agentsentinel watch --stats

Stats are printed on shutdown (Ctrl+C). Enable logging to file:

stats:
  enabled: true
  log_file: ~/agentsentinel-approvals.log

Architecture

How It Works

Pane Discovery - Lists all tmux panes via tmux list-panes
Content Capture - Reads each pane's visible content via tmux capture-pane
Pattern Matching - Scans for approval prompts using regex patterns
Keystroke Injection - Sends y + Enter via tmux send-keys

For Kiro multi-subagent TUI, the workflow is different:

Multi-Prompt Detection - Counts concurrent tool use ... requires approval prompts
TUI Navigation - Sends y (approve) + j (down) to cycle through all items
Full Coverage - Performs count+1 iterations to ensure all items are approved regardless of cursor position

Pattern Reference

Built-in Detection Patterns

AgentSentinel includes 19 built-in regex patterns for detecting approval prompts:

Category	Pattern	Matches
Generic Y/N	`(?i)$y/n$\s*$`	`Allow? (Y/n)`
	`(?i)\[y/n\]\s*$`	`Continue? [y/n]`
	`(?i)$yes/no$\s*$`	`Confirm? (yes/no)`
	`(?i)\[yes/no\]\s*$`	`Proceed? [yes/no]`
Tool Requests	`(?i)allow\s\?\s$y/n$`	`Allow? (Y/n)`
	`(?i)allow\s+tool`	`Allow tool execution`
	`(?i)tool\s+request`	`Tool request pending`
	`(?i)approve\s+tool`	`Approve tool use`
	`(?i)proceed\s*\?`	`Proceed?`
	`(?i)continue\s\?\s$y/n$`	`Continue? (Y/n)`
	`(?i)execute\s\?\s$y/n$`	`Execute? (Y/n)`
	`(?i)run\s+command\s*\?`	`Run command?`
Claude Code	`(?i)allow\s+once`	`Allow once`
	`(?i)allow\s+always`	`Allow always`
Codex CLI	`(?i)sandbox\s+execution`	`Sandbox execution`
AWS Kiro	`(?i)tool\s+use\s+\w+\s+requires\s+approval`	`tool use read requires approval`
	`(?i)press\s+'y'\s+to\s+approve`	`press 'y' to approve`
Generic	`(?i)permission\s+required`	`Permission required`
	`(?i)confirm\s+action`	`Confirm action`

Built-in Danger Patterns

These patterns block auto-approval when detected (13 patterns):

Category	Pattern	Blocks
Destructive	`(?i)rm\s+-rf`	`rm -rf /path`
	`(?i)rm\s+-r\s+/`	`rm -r /`
	`(?i)sudo\s+rm`	`sudo rm -rf`
	`(?i)mkfs`	`mkfs.ext4 /dev/sda`
	`(?i)dd\s+if=`	`dd if=/dev/zero of=/dev/sda`
Fork Bomb	`(?i):\s\{\s:\|:\s&\s\}`	`:(){ :
Device Write	`(?i)>\s*/dev/sd`	`> /dev/sda`
Permissions	`(?i)chmod\s+-R\s+777\s+/`	`chmod -R 777 /`
	`(?i)chown\s+-R.*\s+/`	`chown -R root /`
Remote Execute	`(?i)curl.\|\ssh`	`curl url \| sh`
	`(?i)curl.\|\sbash`	`curl url \| bash`
	`(?i)wget.\|\ssh`	`wget url \| sh`
	`(?i)wget.\|\sbash`	`wget url \| bash`

Custom Patterns

Add custom patterns in ~/.agentsentinel.yaml:

# Custom approval patterns (Go regex syntax)
patterns:
  - "(?i)deploy\\s+to\\s+production\\?"
  - "(?i)apply\\s+changes\\?"
  - "my-tool-prompt"

# Custom danger patterns
danger_patterns:
  - "(?i)drop\\s+database"
  - "(?i)truncate\\s+table"
  - "(?i)delete\\s+from.*where\\s+1=1"

Pattern Syntax:

Uses Go's regexp package (RE2 syntax)
(?i) makes the pattern case-insensitive
\s+ matches one or more whitespace characters
\s* matches zero or more whitespace characters
$ anchors to end of line
\w+ matches one or more word characters
Escape special characters: \?, $, $, \.

Testing Patterns:

# Test your patterns with the built-in test command
agentsentinel test

# Or test in dry-run mode with verbose output
agentsentinel watch --dry-run -v

Troubleshooting

"tmux is not installed"

brew install tmux

"tmux server is not running"

Start a tmux session first:

tmux new-session

Prompts not being detected

Run with verbose logging: agentsentinel watch -v
Check if the prompt appears in the last 30 lines of the pane
Run agentsentinel test to verify detection patterns
The prompt may use a different format - open an issue with the exact prompt text

Approvals not working

Verify the pane ID with agentsentinel status
Test manually: tmux send-keys -t %1 y Enter
Some CLIs may require focus - check if the CLI is waiting for input

Development

# Run tests
go test -v ./...

# Lint
golangci-lint run

# Build
go build -o agentsentinel .

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github		.github
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.json		CHANGELOG.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TASKS.md		TASKS.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
mkdocs.yml		mkdocs.yml

Category	Pattern	Matches
Generic Y/N	`(?i)\(y/n\)\s*$`	`Allow? (Y/n)`
	`(?i)\[y/n\]\s*$`	`Continue? [y/n]`
	`(?i)\(yes/no\)\s*$`	`Confirm? (yes/no)`
	`(?i)\[yes/no\]\s*$`	`Proceed? [yes/no]`
Tool Requests	`(?i)allow\s\?\s\(y/n\)`	`Allow? (Y/n)`
	`(?i)allow\s+tool`	`Allow tool execution`
	`(?i)tool\s+request`	`Tool request pending`
	`(?i)approve\s+tool`	`Approve tool use`
	`(?i)proceed\s*\?`	`Proceed?`
	`(?i)continue\s\?\s\(y/n\)`	`Continue? (Y/n)`
	`(?i)execute\s\?\s\(y/n\)`	`Execute? (Y/n)`
	`(?i)run\s+command\s*\?`	`Run command?`
Claude Code	`(?i)allow\s+once`	`Allow once`
	`(?i)allow\s+always`	`Allow always`
Codex CLI	`(?i)sandbox\s+execution`	`Sandbox execution`
AWS Kiro	`(?i)tool\s+use\s+\w+\s+requires\s+approval`	`tool use read requires approval`
	`(?i)press\s+'y'\s+to\s+approve`	`press 'y' to approve`
Generic	`(?i)permission\s+required`	`Permission required`
	`(?i)confirm\s+action`	`Confirm action`

Folders and files

Latest commit

History

Repository files navigation

AgentSentinel

Supported AI CLIs

Requirements

Installation

Option 1: Install to PATH (recommended)

Option 2: Build locally

Quick Start

Step 1: Start tmux first

Step 2: Run your AI CLI inside tmux

Step 3: Run AgentSentinel (3 options)

Step 4: Watch it work

Key Point

Quick Test

Advanced Usage

Where to Run AgentSentinel

Multi-Agent Layout (3 panes)

Multi-Agent Workflows

Background with Logging

Commands

watch

status

test

version

config

completion

Configuration

Safety Features

Dangerous Command Blocking

Dry Run Mode

Duplicate Prevention

Notifications (macOS)

Statistics

Architecture

How It Works

Pattern Reference

Built-in Detection Patterns

Built-in Danger Patterns

Custom Patterns

Troubleshooting

"tmux is not installed"

"tmux server is not running"

Prompts not being detected

Approvals not working

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Contributors

Uh oh!

Languages