cAI-tools

A collection of Claude Code plugins containing custom agents, skills, and notification hooks.

Tested with macOS Claude Code v2.0.76+.

The plugin is made conservative in context usage by keeping concise and precise writing.

Needed tools:

1. Codex should work. run codex -V to check. (0.153.0+; --full-auto was removed, the skill uses --approve-for-me)
2. Gemini should work. run gemini -v to check. (0.23.0+)
3. jq should work. run jq -V to check. (1.8.1+). brew install jq will install jq.
4. Mathpix API for paper review OCR. Get credentials from Mathpix Console. Save MATHPIX_APP_ID and MATHPIX_APP_KEY to your environment. This is optional, but strongly encouraged for paper review skill.

Plugins

Plugin	Description
awesome-agent	Collection of useful prompted subagents for code review, API docs, QA, and more. Variant from: awesome-claude-code-subagents
AI-skill	Skills for interacting with other AI tools - Codex, Gemini CLI, and collaboration fixes. Codex is a variant from Skill Codex
pushover	Pushover notification hooks - get notified when tasks complete or permissions are needed
mac	macOS integration - speak, send iMessages, emails, manage calendar, and display stickies
science-skill	Paper review copilot with a local web UI for decisions, image analysis, sentence-level paper revision, and research-figure slides

Example:

1. AI-skill:

Use codex and gemini-cli to review uncommitted changes.

Check this with codex

Use the AI-skill:collab-fix skill to fix the bug showing here as ### Bug 3

2. mac:

after you finish, use mac to say "All done" and a brief summary of what you did.

Use imessage to send me (my email address/phone number) a message "Task complete" with the summary.

Can you add this to my stikies?

Use mac to generate today's calendar schedule with the information on my stikies.

Known Issues:

1. Pushover: Claude Code does not have a hook that fires specifically when a user rejects a permission prompt. The system relies on subsequent activity (like Stop or UserPromptSubmit) to cancel escalations(a daemon that send notification by timing). I believe this is a limitation of Claude Code's current hook system, and should be addressed in future versions. We now use a simple session-level tracking to manage escalations. The Pushover is now very annoying because of the 60s, but it is a good push for me. You can change it here escalation service
2. mac: The ical.sh script reads all calendars but only writes to a calendar named "Agent". If your calendar contains sensitive information, be cautious when using this skill.
3. All email/message/calendar features depend on the respective macOS apps being properly configured with accounts. First run of osascript may prompt for permissions.

Installation

Add the Marketplace

claude plugin marketplace add /path/to/cAI-tools

Install Plugins

You can enter claude interface and use /plugin to navigate to my marketplace and install each plugin.

# Install all plugins
claude plugin install awesome-agent@cAI-tools
claude plugin install AI-skill@cAI-tools
claude plugin install pushover@cAI-tools
claude plugin install mac@cAI-tools
claude plugin install science-skill@cAI-tools

Pushover Setup (for pushover plugin)

Run the one-time setup to store your Pushover credentials in macOS Keychain:

./setup-service.sh

Get your credentials from pushover.net.

Alternative: Let an LLM Agent do it

Paste this into a fresh Claude Code session:

Install and configure by following the instructions here https://raw.githubusercontent.com/caidish/cAI-tools/refs/heads/main/README.md

For LLM Agents

Instructions for LLM Agents

If you're an LLM Agent helping set up cAI-tools, Welcome! You'll help your user install a collection of useful Claude Code plugins. Greet them with: Your dish of cAI is served!

Follow these steps:

1. Clone the repository:

   git clone https://github.com/caidish/cAI-tools.git ~/cAI-tools
   

2. Add the marketplace:

   claude plugin marketplace add ~/cAI-tools
   

3. Ask user which plugins to install:

   • awesome-agent - Specialized subagents for code review, QA, API docs, etc.
   • AI-skill - Integration with Codex and Gemini CLI
   • pushover - Push notifications when tasks complete or need approval (requires Pushover account - ask user if they want this)
   • mac - macOS integration (iMessage, email, calendar, stickies, TTS)

4. Install selected plugins:

   claude plugin install awesome-agent@cAI-tools
   claude plugin install AI-skill@cAI-tools
   claude plugin install pushover@cAI-tools
   claude plugin install mac@cAI-tools
   

5. For pushover plugin only: Run the setup script to configure Pushover credentials:

   ~/cAI-tools/setup-service.sh
   

   User needs credentials from pushover.net.

6. Optional but recommended: Add bash timeout settings to ~/.claude/settings.json:

   {
     "env": {
       "BASH_DEFAULT_TIMEOUT_MS": "600000",
       "BASH_MAX_TIMEOUT_MS": "3600000"
     }
   }
   

7. Verify installation: Run claude plugin list to confirm plugins are installed.

Tell the user installation is complete and give a brief overview of what they can now do!

Plugin Details

awesome-agent

Specialized task agents for various workflows:

• api-documenter - API documentation generation
• code-reviewer - Code review and suggestions
• llm-architect - LLM system design
• mcp-developer - MCP server development
• performance-engineer - Performance optimization
• qa-expert - Quality assurance
• qcodes-specialist - QCodes instrumentation
• quantum-device-specialist - Quantum device control
• test-automator - Test automation
• tooling-engineer - Developer tooling
• typescript-pro - TypeScript expertise

AI-skill

Skills for AI tool integration:

Skill	Description
codex	OpenAI Codex CLI integration (models: gpt-6-astra default, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna; effort low…max)
gemini-cli	Google Gemini CLI integration
collab-fix	Collaborative multi-agent fix workflow (codex + gemini-cli + subagent)
TDD-debug	Test-Driven Development debug workflow with multi-agent collab-fix

pushover

Push notifications via Pushover with automatic escalation system.

Skill: notification - Send on-demand push notifications to your phone

Hooks: Automatic permission escalation - get notified when Claude is waiting for approval (60s normal, 1hr emergency)

See pushover/README.md for architecture details and configuration.

mac

macOS native app integration:

Feature	Command	Description
Text-to-Speech	say	Speak messages aloud
iMessage	imessage.sh	Send iMessages
Email	imail.sh	Send emails via Mail.app
Calendar	ical.sh	List/add events (reads all, writes to "Agent" calendar)
Stickies	iStickies.sh	Read and write notes with markdown support

science-skill

Skill	Description
paper-review-helper	Section-by-section paper review driven from a local web UI (see below)
hardworking-paper-writer	Sentence-by-sentence revision that strips AI tells while keeping the author's voice, driven from a local web UI (see below)
vision	Analyze or describe an image (figures, plots, setups)
research-slide	Turn a research figure or result into an editable python-pptx defense/report slide in the house research-highlight style

paper-review-helper web UI. Claude does not ask review questions in the terminal. It starts a local server (scripts/review_ui.py start --workspace <paper-folder>, stdlib only, bound to 127.0.0.1) and opens a browser page with three panes: the section outline, the current section rendered with KaTeX math, figures and colored issue markers, and a conversation pane with decision cards, chat and an issue log. Claude posts sections and questions through the CLI and blocks until you submit a card or send a message; issues you log in the browser are delivered back to Claude with your next reply. State is saved in <paper-folder>/artifact/ui-state.json, so restarting the server resumes the review. The page loads marked and KaTeX from cdnjs, so it needs network access once. Optional: MATHPIX_APP_ID / MATHPIX_API_KEY for PDF → LaTeX conversion.

/science-skill:paper-review-helper ~/papers/manuscript.pdf

hardworking-paper-writer web UI. Same architecture, different loop. Claude starts scripts/writer_ui.py start --workspace <paper-stem>-revision (port 8766, so it can run beside a review) and the page shows your paper as running prose with the sentence under discussion highlighted in amber, edited sentences in green and kept ones underlined. For each sentence Claude posts a card with the original, three rewrites (Light / Medium / Bold, each with a note on what it fixes), "Keep original" and a free-text box: type a full sentence and it is applied verbatim, type an instruction ("shorter", "keep 'we'") and Claude regenerates the options. Keys 1–4 pick, ⌘/Ctrl+Enter submits. A Changes tab lists every edit (original → final → fixes) and a Style tab shows the voice profile Claude is learning from your choices. scripts/segment.py splits .tex / .md / .txt into sentences with stable ids; PDFs go through Mathpix first. State is saved in <paper-stem>-revision/artifact/ui-state.json, so restarting resumes.

/science-skill:hardworking-paper-writer ~/papers/draft.tex

Uninstallation

claude plugin uninstall awesome-agent@cAI-tools
claude plugin uninstall AI-skill@cAI-tools
claude plugin uninstall pushover@cAI-tools
claude plugin uninstall mac@cAI-tools
claude plugin uninstall science-skill@cAI-tools

Bash Timeout Settings

For best experience with long-running tasks:

Add to ~/.claude/settings.json to extend bash timeouts:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "BASH_MAX_TIMEOUT_MS": "3600000"
  }
}

Setting	Value	Description
BASH_DEFAULT_TIMEOUT_MS	600000	Default timeout: 10 min
BASH_MAX_TIMEOUT_MS	3600000	Max timeout: 1 hour

Version Control

A TUI tool for managing plugin versions across marketplace.json, plugin.json, and Claude CLI.

Setup for human

Install gum for the best TUI experience (optional):

brew install gum

Interactive TUI mode:

./tools/plugin-version.sh

AI Usage

Examples:

# CLI commands
./tools/plugin-version.sh status              # View version status
./tools/plugin-version.sh update              # Update plugins in Claude
./tools/plugin-version.sh update mac          # Update specific plugin
./tools/plugin-version.sh bump mac patch      # Bump version (patch/minor/major)
./tools/plugin-version.sh bump-all minor      # Bump all plugins
./tools/plugin-version.sh set mac 2.0.0       # Set specific version
./tools/plugin-version.sh sync                # Sync plugin.json to marketplace.json

AI Workflow

If changes are made to a plugin

1. Run ./tools/plugin-version.sh bump <plugin> patch to increment version
2. Run ./tools/plugin-version.sh status to see status and update Claude