tools.md

Agent Tools: Lightweight bash tools for common operations

Location: Tools symlinked to ~/.local/bin/ after running ./install.sh

Directory Structure

tools/
├── core/         # Database, monitoring, credentials, Beads review (17 tools)
├── mail/         # Agent Mail coordination (14 tools)
├── browser/      # Browser automation via CDP (12 tools)
├── media/        # Image generation with Gemini (7 tools)
├── scripts/      # Installation and setup (33 scripts)
└── signal/       # JAT signal emission (3 tools)

---

Agent Mail (14 tools)

Tool	Purpose	Key Options
am-register	Create agent identity	--name X --program claude-code
am-inbox	Check messages	--unread, --hide-acked, --thread X
am-send	Send message	--from X --to Y --thread Z
am-reply	Reply to message	am-reply MSG_ID "text" --agent X
am-ack	Acknowledge message	am-ack MSG_ID --agent X
am-reserve	Lock files	"glob/**" --agent X --ttl 3600 --reason "task-id"
am-release	Unlock files	"glob/**" --agent X
am-reservations	List locks	--agent X
am-search	Search messages	"query" --thread X
am-agents	List agents	(no args)
am-whoami	Current identity	--agent X

Broadcast recipients: @active (last 60min), @recent (24h), @all, @project:name

Example:

am-send "Subject" "Body" --from Me --to @active --importance high --thread task-123

---

Core Tools (tools/core/)

Database, monitoring, credentials, and Beads review tools.

Tool	Purpose
jat-secret	Retrieve secrets from credentials store
db-query	Run SQL, returns JSON
db-sessions	List database connections
db-schema	Show table structure
db-connection-test	Test database connectivity
edge-logs	Stream Supabase edge function logs
lint-staged	Lint staged git files
bd-check-review	Check if task needs human review
bd-review-rules	Display review rules for project
bd-review-rules-loader	Load/parse review rules from config
bd-set-review-override	Set review override for a task
backup-beads.sh	Backup Beads database
rollback-beads.sh	Rollback Beads to backup
beads-migrate-prefix.sh	Migrate task ID prefixes

jat-secret usage:

jat-secret <name>       # Get secret value
jat-secret --list       # List all secrets
jat-secret --export     # Output export statements
jat-secret --env <name> # Get env var name for a key

---

Browser Automation (tools/browser/)

Chrome DevTools Protocol (CDP) based browser control via Node.js.

Tool	Purpose	Example
browser-start.js	Launch Chrome with CDP	--headless
browser-nav.js	Navigate to URL	browser-nav.js URL
browser-eval.js	Execute JS in page	"document.title"
browser-screenshot.js	Capture screenshot	--output /tmp/x.png
browser-pick.js	Click element by selector	--selector "button"
browser-cookies.js	Get/set cookies	--set "name=value"
browser-wait.js	Wait for condition	--text "loaded"
browser-console.js	Capture console logs	(streams output)
browser-network.js	Monitor network requests	(streams output)
browser-snapshot.js	Capture DOM snapshot	(returns HTML)
browser-hn-scraper.js	Hacker News scraper example	(demo)

browser-eval quirk: Supports multi-statement code with return:

browser-eval.js "const x = 5; const y = 10; return x + y"

---

Media / Image Generation (tools/media/)

AI image generation via Google Gemini API.

Tool	Purpose
gemini-image	Generate image from text prompt
gemini-edit	Edit existing image with prompt
gemini-compose	Combine 2-14 images into one
avatar-generate	Generate agent avatar image
avatar-to-ansi	Convert avatar to terminal ANSI art
gemini-lib.sh	Shared Gemini API helper functions

Requires: GEMINI_API_KEY environment variable

---

Signal Tools (tools/signal/)

JAT signal emission for IDE state updates.

Tool	Purpose
jat-signal	Emit status signals to IDE
jat-signal-validate	Validate signal JSON against schema
jat-signal-schema.json	JSON schema for signal payloads

Signal types: starting, working, needs_input, review, completing, complete

Example:

jat-signal working '{"taskId":"jat-abc","taskTitle":"Add feature","approach":"..."}'

---

Scripts (tools/scripts/)

Installation, setup, and utility scripts.

Installation:

Script	Purpose
symlink-tools.sh	Create symlinks in ~/.local/bin/
setup-repos.sh	Initialize project repositories
setup-bash-functions.sh	Generate shell launcher functions
setup-statusline-and-hooks.sh	Install Claude Code hooks
setup-tmux.sh	Configure tmux for JAT
setup-global-claude-md.sh	Setup global CLAUDE.md
install-agent-mail.sh	Initialize Agent Mail database
install-beads.sh	Install Beads CLI
install-hooks.sh	Install Claude Code hooks
install-whisper.sh	Install whisper.cpp for voice input

JAT Workflow:

Script	Purpose
jat-step	Execute completion step with signal emission
jat-complete-bundle	Generate structured completion bundle via LLM
jat-doctor	Diagnose JAT installation issues
bd-epic-child	Set epic→child dependency correctly

Agent Management:

Script	Purpose
get-current-session-id	Get Claude Code session ID
get-agents-by-state	List agents by status
get-recent-agents	List recently active agents
get-agent-task.sh	Get agent's current task
check-agent-active	Check if agent is active
list-agents-simple	Simple agent list
log-agent-activity	Log agent activity events

Utilities:

Script	Purpose
time-ago	Format timestamp as "X minutes ago"
record-gif	Record terminal session as GIF
cleanup-jsonl.sh	Clean up old JSONL files
cleanup-jsonl-cron.sh	Cron wrapper for cleanup
extract-har-timings.sh	Extract timings from HAR files
test-statusline.sh	Test statusline display
test-themes.sh	Test IDE themes
fix-hook-stdin.sh	Fix hook stdin issues
update-signal-hooks.sh	Update signal hook scripts
import-bashrc-config.sh	Import bashrc configuration
migrate-jomarchy-agent-tools-to-jat.sh	Migration helper
migrate-task-images.sh	Migrate task image paths

jat-step usage:

jat-step <step> --task <id> --title <title> --agent <name> [--type <type>]

Step	Action	Signal
verifying	Emit only (agent does verification)	completing (0%)
committing	git add + commit	completing (20%)
closing	bd close	completing (40%)
releasing	am-release all	completing (60%)
announcing	am-send completion	completing (80%)
complete	Generate bundle + emit complete signal	complete (100%)

Requires: ANTHROPIC_API_KEY environment variable (for complete step)

---

Quick Patterns

Reserve → Work → Release:

am-reserve "src/**/*.ts" --agent $AGENT_NAME --ttl 3600 --reason "task-123"
# ... work ...
am-release "src/**/*.ts" --agent $AGENT_NAME

Broadcast to active agents:

am-send "Alert" "Message" --from Me --to @active --importance high

Check inbox:

am-inbox $AGENT_NAME --unread --hide-acked

More Info

Every tool has --help:

am-send --help
browser-eval.js --help