From a38b4d5c57f3dea9a32bb33c19326f6f3599a190 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:02:01 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + SKILL.md | 277 ++++++++++++++++++++ plugin.lock.json | 61 +++++ references/agent-specific-commands.md | 260 ++++++++++++++++++ references/api_reference.md | 34 +++ references/use-case-examples.md | 363 ++++++++++++++++++++++++++ scripts/validate-agent-setup.py | 270 +++++++++++++++++++ 8 files changed, 1280 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 plugin.lock.json create mode 100644 references/agent-specific-commands.md create mode 100644 references/api_reference.md create mode 100644 references/use-case-examples.md create mode 100755 scripts/validate-agent-setup.py diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..c632925 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "headless-cli-agents", + "description": "Comprehensive guide for running AI coding agents in non-interactive mode for automation, CI/CD pipelines, and scripting", + "version": "1.0.0", + "author": { + "name": "Timur Khakhalev", + "email": "timur.khakhalev@gmail.com" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b2ff5cc --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# headless-cli-agents + +Comprehensive guide for running AI coding agents in non-interactive mode for automation, CI/CD pipelines, and scripting diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..a8a7300 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,277 @@ +--- +name: headless-cli-agents +description: This skill provides comprehensive guidance for running AI coding agents in non-interactive (headless) mode for automation, CI/CD pipelines, and scripting. Use when integrating Claude Code, Codex, Gemini, OpenCode, Qwen, or Droid CLI into automated workflows where human interaction is not desired. +--- + +# Headless CLI Agents + +## Overview + +This skill enables the use of AI coding agents in non-interactive mode for automation scenarios. It provides command references, safety considerations, and practical examples for integrating AI agents into CI/CD pipelines, shell scripts, and other automated workflows. + +## Quick Reference + +| Agent | Basic Command | Automation Flag | Best For | +|-------|--------------|----------------|----------| +| Claude Code | `claude -p "prompt"` | Auto-approved by default | General coding tasks | +| OpenAI Codex | `codex exec "prompt"` | `--full-auto` | Complex refactoring | +| Google Gemini | `gemini -p "prompt"` | `--yolo` (if available) | Analysis tasks | +| OpenCode | `opencode -p "prompt"` | Auto-approved by default | Multi-provider support | +| Qwen Code | `qwen -p "prompt"` | `--yolo` | Local model support | +| Factory Droid | `droid exec "prompt"` | `--auto ` | Controlled automation | + +## When to Use Headless Mode + +Use this skill when: +- **CI/CD Pipelines**: Automated code reviews, test generation, documentation +- **Shell Scripts**: Repetitive coding tasks, bulk operations +- **Cron Jobs**: Scheduled maintenance, analysis tasks +- **Git Hooks**: Pre-commit validation, post-commit analysis +- **DevOps Automation**: Infrastructure as code, deployment preparation + +## Core Concepts + +### 1. Agent Selection + +Choose the appropriate agent based on your requirements: + +**Claude Code CLI** - Best for general-purpose coding with excellent code understanding +```bash +# Basic usage +claude -p "Review this code for security issues" + +# With additional context +claude -p "Generate tests for authentication module" --add-dir ./tests +``` + +**OpenAI Codex CLI** - Best for complex refactoring and code transformation +```bash +# Automated refactoring +codex exec --full-auto "Refactor this module to use async/await" + +# Outside git repos +codex exec --skip-git-repo-check --full-auto "Create API documentation" +``` + +**Google Gemini CLI** - Best for analysis and documentation tasks +```bash +# Analysis with structured output +gemini -p "Analyze codebase architecture" --output-format json + +# Documentation generation +cat src/ | gemini -p "Generate comprehensive API documentation" +``` + +### 2. Safety and Autonomy Levels + +Different agents provide varying levels of automation control: + +**Read-Only Mode (Safest)** +```bash +# Analysis without changes +droid exec "Analyze security vulnerabilities" +gemini -p "Review code quality metrics" +``` + +**Low-Risk Changes** +```bash +# Documentation and comments +droid exec "Add docstrings to all functions" --auto low +codex exec --full-auto "Update README with installation instructions" +``` + +**Development Operations** +```bash +# Package installation, test running +droid exec "Install dependencies and run tests" --auto medium +codex exec --full-auto "Fix failing unit tests" +``` + +**High-Risk Changes (Use Carefully)** +```bash +# Production deployments, major refactoring +droid exec "Implement OAuth2 migration" --auto high +# Only in isolated environments +codex exec --yolo "Complete system refactoring" +``` + +### 3. Input/Output Patterns + +**Piping Content** +```bash +# Analyze git diff +git diff | claude -p "Review these changes for bugs" + +# Process error logs +cat error.log | qwen -p "Categorize and summarize these errors" + +# Multiple files +find . -name "*.py" | xargs claude -p "Check for anti-patterns" +``` + +**File-based Prompts** +```bash +# Read from prompt file +droid exec -f migration_prompt.md + +# JSON output for parsing +gemini -p "List all API endpoints" --output-format json +``` + +**Structured Output** +```bash +# Machine-readable output +opencode -p "Count lines of code" -f json +claude -p "Generate test coverage report" > coverage_report.md +``` + +## Common Workflows + +### Code Review Automation +```bash +# Quick security scan +find . -name "*.py" | xargs claude -p "Check for security vulnerabilities" + +# Performance analysis +git diff | codex exec --full-auto "Analyze performance impact of changes" + +# Documentation consistency +droid exec "Verify all functions have docstrings" --auto low +``` + +### Test Generation +```bash +# Unit tests for specific module +claude -p "Generate comprehensive unit tests for auth.py using pytest" + +# Integration tests +codex exec --full-auto "Create API integration tests with realistic data" + +# Test coverage analysis +qwen -p "Analyze test coverage and suggest missing test cases" +``` + +### Documentation Automation +```bash +# API documentation +find src/ -name "*.py" | gemini -p "Generate OpenAPI specification" + +# README generation +claude -p "Create comprehensive README with setup, usage, and examples" + +# Changelog from commits +git log --oneline | qwen -p "Generate changelog from commit history" +``` + +## Integration Patterns + +### CI/CD Integration + +**GitHub Actions** +```yaml +- name: AI Code Review + run: | + git diff origin/main...HEAD | claude -p "Review for security and performance issues" +``` + +**GitLab CI** +```yaml +script: + - gemini -p "Generate test suite for new features" --output-format json > test_plan.json +``` + +### Pre-commit Hooks +```bash +#!/bin/sh +# .git/hooks/pre-commit +git diff --cached | claude -p "Check staged changes for obvious bugs" +if [ $? -ne 0 ]; then exit 1; fi +``` + +### Monitoring and Alerts +```bash +# Daily code quality report +claude -p "Generate daily code quality report" | mail -s "Code Quality" team@example.com +``` + +## Best Practices + +### Security +- Never use `--yolo` or equivalent flags in production environments +- Validate AI-generated code before deployment +- Use read-only mode for security-sensitive analysis +- Implement human review for high-risk changes + +### Performance +- Limit the scope of analysis (specific files vs entire codebase) +- Use structured output formats for programmatic processing +- Cache results when appropriate +- Monitor API usage and costs + +### Reliability +- Include fallback mechanisms for AI agent failures +- Validate generated code with linters and tests +- Use specific, well-defined prompts for consistent results +- Implement retry logic for network issues + +### Error Handling +```bash +# Robust script pattern +if ! claude -p "Generate tests" > tests.py; then + echo "AI generation failed, using fallback" + cp fallback_tests.py tests.py +fi +``` + +## Troubleshooting + +### Common Issues + +**Agent not found**: Ensure CLI tools are installed and in PATH +```bash +which claude codex gemini opencode qwen droid +``` + +**Authentication errors**: Verify API keys and tokens +```bash +claude auth status +codex auth verify +``` + +**Permission denied**: Check file permissions and working directory +```bash +ls -la +pwd +``` + +**Context limit exceeded**: Reduce analysis scope or use specific files +```bash +# Instead of entire codebase +claude -p "Analyze main.py only" + +# Or use specific patterns +find src/ -name "*.py" -maxdepth 2 | claude -p "Review these files" +``` + +### Debug Mode +Most agents support verbose output: +```bash +claude --verbose -p "Debug prompt" +codex exec --debug "Debug task" +``` + +## Resources + +### references/ + +**agent-specific-commands.md** - Detailed command documentation for all six CLI agents including flags, options, and specific usage patterns. Load this when you need comprehensive syntax reference for a particular agent. + +**use-case-examples.md** - Practical examples for CI/CD pipelines, shell scripts, and automation workflows. Load this when implementing specific automation scenarios or need concrete implementation patterns. + +### scripts/ + +**validate-agent-setup.py** - Optional helper script to verify agent installations, API authentication, and basic functionality. Execute this to check if the required CLI agents are properly configured before using them in automation. + +--- + +**References contain detailed command documentation and practical examples that complement this guide.** diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..13928a9 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,61 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:timurkhakhalev/cc-plugins:headless-cli-agents", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "87c67967a1cc2c9b76bf166118b8a371a0e25b0f", + "treeHash": "d4a3d8dea3696e472573ae6682853d892a39935b4b59cf07e2563eebb8c498da", + "generatedAt": "2025-11-28T10:28:41.738773Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "headless-cli-agents", + "description": "Comprehensive guide for running AI coding agents in non-interactive mode for automation, CI/CD pipelines, and scripting", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "f1c8f2e76cbe34a301a2682222bf0749e43236567dafe1b01a50fb23f36b8533" + }, + { + "path": "SKILL.md", + "sha256": "7ce88f695ee1d3db69400b6848cf3eb125ee06327d825730f8c38400c5606411" + }, + { + "path": "references/api_reference.md", + "sha256": "96126526510569488ab86e78bdd24d543a7b046489d3f6c34041a9d732ae0606" + }, + { + "path": "references/agent-specific-commands.md", + "sha256": "63d7eb2a993feb9f00f24b92e3d500310020ce6dcc3bb7fed1c7c542003318ae" + }, + { + "path": "references/use-case-examples.md", + "sha256": "874f19b33226f5ea4f741c89b55a87b172911a9c6d227b6b1bee122ff23b3b78" + }, + { + "path": "scripts/validate-agent-setup.py", + "sha256": "21280b2006a793f3cfba0f2f51a6ac9db4d6f38dd414d85c9040f1902c322914" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "fe3e6d3ca4013e30cd72937ee15023d466486f8a9e0d656688941fb561cb1ed0" + } + ], + "dirSha256": "d4a3d8dea3696e472573ae6682853d892a39935b4b59cf07e2563eebb8c498da" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/agent-specific-commands.md b/references/agent-specific-commands.md new file mode 100644 index 0000000..eef0846 --- /dev/null +++ b/references/agent-specific-commands.md @@ -0,0 +1,260 @@ +# CLI Agent Commands Reference + +## Claude Code CLI (Anthropic) + +### Basic Headless Usage +```bash +claude -p "Your prompt here" +``` + +### Key Flags +- `-p` or `--prompt`: Execute one-shot prompt and exit +- `--add-dir `: Add additional directory to workspace context +- `--model `: Specify model (optional) + +### Examples +```bash +# Basic one-shot query +claude -p "Explain this function" + +# Pipe input to Claude +cat error.log | claude -p "Summarize these errors" + +# Multiple directory context +claude -p "Review the API design" --add-dir ../api-specs +``` + +### Authentication +Requires configured API key or OAuth token. Run `claude --help` for setup options. + +--- + +## OpenAI Codex CLI + +### Basic Headless Usage +```bash +codex exec "Your prompt here" +codex e "Your prompt here" # Short alias +``` + +### Key Flags +- `--full-auto`: Unattended operation with workspace-write sandbox +- `--dangerously-bypass-approvals-and-sandbox` or `--yolo`: Complete hands-off mode (use carefully) +- `--skip-git-repo-check`: Allow execution outside Git repositories +- `--cd `: Set working directory +- `--model ` or `-m`: Specify model (e.g., `-m gpt-5-codex`) + +### Examples +```bash +# Automated refactoring +codex exec --full-auto "Update all README links to HTTPS" + +# Outside Git repo +codex exec --skip-git-repo-check --full-auto "Create hello world HTML" + +# Different working directory +codex exec --cd /path/to/project "Fix failing tests" +``` + +### Input Methods +```bash +# Pipe prompt from file +codex exec - < prompt.txt + +# Standard input +echo "Review this code" | codex exec - +``` + +--- + +## Google Gemini CLI + +### Basic Headless Usage +```bash +gemini --prompt "Your prompt here" +gemini -p "Your prompt here" # Short form +``` + +### Key Flags +- `--prompt` or `-p`: Execute prompt and exit +- `--output-format `: Output format (json, stream-json) +- `--model `: Specify model variant + +### Examples +```bash +# Basic query +gemini -p "Summarize API design in this repo" + +# Pipe input with prompt +echo "List TODO comments" | gemini -p "-" + +# JSON output +gemini -p "Analyze code structure" --output-format json + +# Process file with instruction +cat DESIGN.md | gemini -p "Improve this design document" +``` + +### Authentication +Requires Google account authentication or API key setup. + +--- + +## OpenCode CLI + +### Basic Headless Usage +```bash +opencode -p "Your prompt here" +opencode --prompt "Your prompt here" +``` + +### Key Flags +- `-p` or `--prompt`: Execute single prompt and exit +- `-f ` or `--format`: Output format (json) +- `-q` or `--quiet`: Suppress loading spinner +- `--cwd `: Set working directory + +### Examples +```bash +# Basic query +opencode -p "Explain Go context usage" + +# JSON output +opencode -p "How many files in project?" -f json + +# Quiet mode for scripting +opencode -p "Review code" -q + +# Different working directory +opencode -p "Analyze this project" --cwd /path/to/project +``` + +### Environment Setup +Requires API keys for providers (OpenAI, Anthropic, etc.) in environment variables. + +--- + +## Alibaba Qwen Code CLI + +### Basic Headless Usage +```bash +qwen -p "Your prompt here" +``` + +### Key Flags +- `-p` or `--prompt`: Execute one-shot prompt +- `--output-format `: Output format (json) +- `--model `: Specify Qwen model variant +- `--yolo`: Bypass confirmations (similar to other agents) + +### Examples +```bash +# Code review +qwen -p "Review this code for potential bugs" + +# Generate tests +qwen -p "Generate unit tests for utils.py" + +# Pipe diff for review +git diff | qwen -p "Review this diff for errors" + +# JSON output +qwen -p "List project files" --output-format json +``` + +### Authentication +- First-time setup: Run `qwen` interactively to login with Qwen.ai OAuth +- Cached credentials: Used automatically for subsequent `-p` calls +- Local models: Set OPENAI_API_KEY and related env vars for local LLM servers + +--- + +## Factory Droid CLI + +### Basic Headless Usage +```bash +droid exec "Your prompt here" +``` + +### Key Flags +- `--auto `: Set autonomy level (low, medium, high) +- `--skip-permissions-unsafe`: Bypass all permission checks (use carefully) +- `--cwd `: Set working directory +- `-f `: Read prompt from file +- `-o `: Output format (json) + +### Autonomy Levels +- **Default (no flag)**: Read-only mode, safe for analysis +- `--auto low`: Allow low-risk file edits (documentation, simple refactors) +- `--auto medium`: Allow development operations (install packages, run tests) +- `--auto high`: Permit production-level changes (full access) + +### Examples +```bash +# Read-only analysis +droid exec "List all TODO comments across the project" + +# Low-risk edits +droid exec "Fix typos in README.md" --auto low + +# Development operations +droid exec "Fix failing unit tests" --auto medium + +# High-risk changes +droid exec "Implement OAuth2 migration" --auto high + +# Read prompt from file +droid exec -f prompt.md + +# JSON output +droid exec "Analyze codebase" -o json + +# Different working directory +droid exec "Review this code" --cwd /path/to/project +``` + +### Safety Notes +- Default mode is read-only for safety +- Use `--skip-permissions-unsafe` only in sandboxed environments +- Consider autonomy levels carefully based on use case + +--- + +## Common Patterns + +### piping Input +Most agents support piping input: +```bash +# Pipe file content +cat file.txt | agent -p "Process this" + +# Pipe command output +git log --oneline | agent -p "Summarize commits" +``` + +### Reading from Files +```bash +# Direct file reading (if supported) +agent -f prompt.txt + +# Using cat and pipe +cat prompt.txt | agent -p "-" +``` + +### JSON Output +For scripting and automation: +```bash +# JSON output format +agent -p "Query" --output-format json +agent -p "Query" -f json +agent -p "Query" -o json +``` + +### Automation Flags +For completely unattended operation: +```bash +# Various automation flags per agent +codex --full-auto "Task" +droid --auto medium "Task" +gemini --yolo "Task" # if available +``` \ No newline at end of file diff --git a/references/api_reference.md b/references/api_reference.md new file mode 100644 index 0000000..557692e --- /dev/null +++ b/references/api_reference.md @@ -0,0 +1,34 @@ +# Reference Documentation for Headless Cli Agents + +This is a placeholder for detailed reference documentation. +Replace with actual reference content or delete if not needed. + +Example real reference docs from other skills: +- product-management/references/communication.md - Comprehensive guide for status updates +- product-management/references/context_building.md - Deep-dive on gathering context +- bigquery/references/ - API references and query examples + +## When Reference Docs Are Useful + +Reference docs are ideal for: +- Comprehensive API documentation +- Detailed workflow guides +- Complex multi-step processes +- Information too lengthy for main SKILL.md +- Content that's only needed for specific use cases + +## Structure Suggestions + +### API Reference Example +- Overview +- Authentication +- Endpoints with examples +- Error codes +- Rate limits + +### Workflow Guide Example +- Prerequisites +- Step-by-step instructions +- Common patterns +- Troubleshooting +- Best practices diff --git a/references/use-case-examples.md b/references/use-case-examples.md new file mode 100644 index 0000000..bd7b4a7 --- /dev/null +++ b/references/use-case-examples.md @@ -0,0 +1,363 @@ +# CLI Agents Use Case Examples + +## CI/CD Pipeline Examples + +### GitHub Actions - Code Review + +```yaml +name: AI Code Review +on: + pull_request: + branches: [main] + +jobs: + ai-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Claude Code CLI + run: | + curl -fsSL https://claude.ai/install.sh | sh + echo "$CLAUDE_API_KEY" | claude auth login + env: + CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }} + + - name: Review PR Changes + run: | + git diff origin/main...HEAD | claude -p "Review these changes for potential bugs, security issues, and best practices. Focus on: 1) Error handling 2) Performance 3) Security 4) Code quality" + + - name: Check for TODO Comments + run: | + find . -name "*.py" -o -name "*.js" -o -name "*.ts" | xargs grep -l "TODO\|FIXME" | claude -p "Review these files containing TODO/FIXME comments and suggest implementation approaches" +``` + +### GitLab CI - Documentation Generation + +```yaml +stages: + - analyze + - build + +code-analysis: + stage: analyze + image: node:18 + before_script: + - npm install -g @anthropic-ai/claude-cli + script: + - | + claude -p "Generate comprehensive API documentation for this codebase. Focus on: 1) Endpoints 2) Request/response formats 3) Authentication 4) Error codes" > API_DOCUMENTATION.md + claude -p "Create a README with setup instructions, usage examples, and contribution guidelines" > README_ENHANCED.md + artifacts: + paths: + - API_DOCUMENTATION.md + - README_ENHANCED.md +``` + +### Jenkins Pipeline - Test Generation + +```groovy +pipeline { + agent any + + stages { + stage('AI Test Generation') { + steps { + script { + sh ''' + # Generate unit tests for untested functions + find src -name "*.py" -exec grep -L "def test_" {} \\; | codex exec --full-auto --skip-git-repo-check "Generate comprehensive unit tests for these files using pytest framework. Include edge cases and error handling." + + # Generate integration tests + codex exec --full-auto "Create integration tests for the main API endpoints. Test authentication, data flow, and error scenarios." + ''' + } + } + } + + stage('Run Tests') { + steps { + sh 'python -m pytest' + } + } + } +} +``` + +## Shell Scripting Examples + +### Code Quality Check Script + +```bash +#!/bin/bash + +# quality-check.sh - Automated code quality analysis + +set -e + +echo "๐Ÿ” Running AI-powered code quality checks..." + +# Check for security vulnerabilities +echo "๐Ÿ”’ Checking for security issues..." +find . -name "*.py" -o -name "*.js" -o -name "*.ts" | \ + xargs grep -l "password\|secret\|token\|key" | \ + claude -p "Analyze these files for potential security vulnerabilities. Look for: 1) Hardcoded credentials 2) Insecure data handling 3) Missing input validation 4) Authentication bypasses" + +# Check for performance issues +echo "โšก Analyzing performance patterns..." +find . -name "*.py" | head -10 | \ + claude -p "Review these files for performance bottlenecks. Focus on: 1) Database queries 2) Loops and recursion 3) Memory usage 4) Async operations" + +# Generate quality report +echo "๐Ÿ“‹ Generating quality report..." +claude -p "Create a comprehensive code quality report summarizing: 1) Security findings 2) Performance issues 3) Code style violations 4) Recommendations for improvement" > QUALITY_REPORT.md + +echo "โœ… Quality check completed. See QUALITY_REPORT.md" +``` + +### Automated Refactoring Script + +```bash +#!/bin/bash + +# refactor.sh - Automated code refactoring + +PROJECT_DIR=${1:-.} +REFACTOR_TYPE=${2:-"general"} + +echo "๐Ÿ”ง Starting automated refactoring in $PROJECT_DIR..." + +cd "$PROJECT_DIR" + +case "$REFACTOR_TYPE" in + "security") + codex exec --full-auto "Review all files for security issues and implement fixes: 1) Input sanitization 2) Output encoding 3) Authentication improvements 4) Secure headers" + ;; + "performance") + codex exec --full-auto "Optimize code for performance: 1) Database query optimization 2) Caching strategies 3) Async/await patterns 4) Resource cleanup" + ;; + "documentation") + codex exec --full-auto "Add comprehensive documentation: 1) Function docstrings 2) Type hints 3) Usage examples 4) README updates" + ;; + *) + codex exec --full-auto "General code refactoring: 1) Improve naming conventions 2) Reduce complexity 3) Add error handling 4) Code organization" + ;; +esac + +echo "โœ… Refactoring completed" +``` + +### Dependency Update Script + +```bash +#!/bin/bash + +# update-dependencies.sh - Smart dependency management + +echo "๐Ÿ“ฆ Analyzing and updating dependencies..." + +# Check for security updates +gemini -p "Analyze package.json/requirements.txt for security vulnerabilities and outdated dependencies. Suggest specific version updates with migration notes." > DEPENDENCY_ANALYSIS.md + +# Update packages (if safe) +if [ "$1" = "--auto" ]; then + echo "๐Ÿš€ Auto-updating dependencies..." + droid exec "Update all dependencies to latest safe versions. Create migration plan for breaking changes." --auto medium +fi + +# Generate changelog +claude -p "Create a changelog entry documenting dependency updates, security improvements, and potential breaking changes." > CHANGELOG.md + +echo "โœ… Dependency analysis completed" +``` + +## Automation Workflow Examples + +### Pre-commit Hook + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +echo "๐Ÿค– Running AI pre-commit checks..." + +# Check commit message +commit_msg=$(git log -1 --pretty=%B) +echo "$commit_msg" | claude -p "Validate this commit message. Check for: 1) Clear description 2) Proper format 3) Issue references 4) Breaking change indicators" + +if [ $? -ne 0 ]; then + echo "โŒ Commit message validation failed" + exit 1 +fi + +# Quick code review of staged changes +git diff --cached | claude -p "Quick review of staged changes. Check for: 1) Obvious bugs 2) Syntax errors 3) Missing tests 4) Security issues" + +if [ $? -ne 0 ]; then + echo "โŒ Code review found issues" + exit 1 +fi + +echo "โœ… Pre-commit checks passed" +``` + +### Release Preparation Script + +```bash +#!/bin/bash + +# prepare-release.sh - Automated release preparation + +VERSION=${1:-"patch"} +RELEASE_BRANCH=${2:-"release"} + +echo "๐Ÿš€ Preparing release for version bump: $VERSION" + +# Create release branch +git checkout -b "$RELEASE_BRANCH" + +# Update version numbers +codex exec --full-auto "Update all version numbers in the project for a $VERSION release: 1) package.json 2) __init__.py files 3) Docker files 4) Documentation" + +# Generate release notes +git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ + qwen -p "Create comprehensive release notes from these commits. Categorize by: 1) Features 2) Bug fixes 3) Breaking changes 4) Security improvements" > RELEASE_NOTES.md + +# Update documentation +droid exec "Update all documentation for new release: 1) API docs 2) README 3) Installation guides 4) Migration guides" --auto low + +echo "โœ… Release preparation completed" +echo "๐Ÿ“‹ Review RELEASE_NOTES.md and commit changes" +``` + +### Database Migration Helper + +```bash +#!/bin/bash + +# migrate-db.sh - AI-assisted database migrations + +MIGRATION_NAME=${1:-"auto_migration"} + +echo "๐Ÿ—„๏ธ Generating migration: $MIGRATION_NAME" + +# Analyze schema changes +find models/ -name "*.py" | \ + claude -p "Analyze these model files for schema changes since last migration. Identify: 1) New tables 2) Column changes 3) Index changes 4) Relationship updates" + +# Generate migration file +codex exec --full-auto "Create a database migration file named ${MIGRATION_NAME}.py. Include: 1) Forward migration 2) Rollback migration 3) Data transformations 4) Safety checks" + +# Generate test data +gemini -p "Generate test data and validation queries for the new migration. Include: 1) Sample records 2) Constraint tests 3) Performance test queries" + +echo "โœ… Migration generated. Review and run: python manage.py migrate" +``` + +## Monitoring and Maintenance Examples + +### Log Analysis Script + +```bash +#!/bin/bash + +# analyze-logs.sh - AI-powered log analysis + +LOG_FILE=${1:-"app.log"} +TIMEFRAME=${2:-"24h"} + +echo "๐Ÿ“Š Analyzing logs from $LOG_FILE (last $TIMEFRAME)..." + +# Extract errors and warnings +grep -E "(ERROR|WARN|CRITICAL)" "$LOG_FILE" | \ + qwen -p "Analyze these log entries for: 1) Error patterns 2) Root causes 3) Frequency analysis 4) Recommended fixes" > ERROR_ANALYSIS.md + +# Performance analysis +grep -E "(slow|timeout|memory|performance)" "$LOG_FILE" | \ + claude -p "Identify performance issues from these logs. Focus on: 1) Slow queries 2) Memory leaks 3) Timeout patterns 4) Resource bottlenecks" > PERFORMANCE_ISSUES.md + +# Generate summary +gemini -p "Create an executive summary of log analysis including: 1) Critical issues 2) Performance impact 3) Security concerns 4) Action items" > LOG_SUMMARY.md + +echo "โœ… Log analysis completed. Check *.md files" +``` + +### Health Check Automation + +```bash +#!/bin/bash + +# health-check.sh - Automated system health analysis + +echo "๐Ÿฅ Running AI-powered health checks..." + +# Code health +find . -name "*.py" | head -20 | \ + droid exec "Analyze code health indicators: 1) Code complexity 2) Test coverage gaps 3) Dead code 4) Anti-patterns" --auto low > CODE_HEALTH.md + +# Dependency health +claude -p "Analyze project dependencies for: 1) Security vulnerabilities 2) License compliance 3) Version conflicts 4) Maintenance status" > DEPENDENCY_HEALTH.md + +# Architecture health +gemini -p "Review project architecture for: 1) Design patterns 2) Coupling issues 3) Scalability concerns 4) Technical debt" > ARCHITECTURE_HEALTH.md + +# Generate actionable report +claude -p "Create a prioritized action plan based on health checks. Include: 1) Critical fixes 2) Improvements 3) Technical debt roadmap 4) Resource allocation" > HEALTH_ACTION_PLAN.md + +echo "โœ… Health check completed. Review generated reports" +``` + +## Integration Examples + +### Slack Integration + +```bash +#!/bin/bash + +# slack-ai-notify.sh - Send AI analysis to Slack + +WEBHOOK_URL=${SLACK_WEBHOOK_URL} +PROJECT_DIR=${1:-"."} + +cd "$PROJECT_DIR" + +# Analyze recent changes +git diff HEAD~1 | \ + claude -p "Analyze recent changes and create a concise summary for team notification. Include: 1) Key changes 2) Impact 3) Any action needed" > CHANGE_SUMMARY.txt + +# Send to Slack +curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"$(cat CHANGE_SUMMARY.txt)\"}" \ + "$WEBHOOK_URL" + +echo "๐Ÿ“ข AI summary sent to Slack" +``` + +### Email Reports + +```bash +#!/bin/bash + +# email-ai-report.sh - Generate and email AI reports + +EMAIL=${1:-"team@example.com"} +REPORT_TYPE=${2:-"weekly"} + +echo "๐Ÿ“ง Generating $REPORT_TYPE report..." + +case "$REPORT_TYPE" in + "weekly") + git log --since="1 week ago" --oneline | \ + qwen -p "Create a weekly development report. Include: 1) Features completed 2) Bugs fixed 3) Code quality metrics 4) Team achievements" > weekly_report.md + ;; + "security") + find . -name "*.py" -o -name "*.js" | \ + claude -p "Generate a security audit report. Include: 1) Vulnerabilities found 2) Risk assessment 3) Remediation steps 4) Best practices" > security_report.md + ;; +esac + +# Send email (using mail command or your preferred method) +mail -s "AI-generated $REPORT_TYPE report" "$EMAIL" < "${REPORT_TYPE}_report.md" + +echo "โœ… Report emailed to $EMAIL" +``` \ No newline at end of file diff --git a/scripts/validate-agent-setup.py b/scripts/validate-agent-setup.py new file mode 100755 index 0000000..f871c3e --- /dev/null +++ b/scripts/validate-agent-setup.py @@ -0,0 +1,270 @@ +#!/usr/bin/env python3 +""" +CLI Agent Setup Validation Script + +This script checks if various AI coding CLI agents are properly installed, +configured, and authenticated for headless operation. + +Usage: + python validate-agent-setup.py [agent_name] + +If agent_name is provided, only that agent will be checked. +Otherwise, all available agents will be validated. +""" + +import subprocess +import sys +import json +import os +from typing import Dict, List, Tuple, Optional + +# Agent configuration +AGENTS = { + "claude": { + "commands": ["claude", "claude -p 'test'"], + "install_url": "https://claude.ai/install", + "auth_check": "claude auth status", + "description": "Anthropic Claude Code CLI" + }, + "codex": { + "commands": ["codex", "codex exec 'test'"], + "install_url": "https://platform.openai.com/docs/cli", + "auth_check": "codex auth verify", + "description": "OpenAI Codex CLI" + }, + "gemini": { + "commands": ["gemini", "gemini -p 'test'"], + "install_url": "https://geminicli.com/docs/installation", + "auth_check": "gemini auth status", + "description": "Google Gemini CLI" + }, + "opencode": { + "commands": ["opencode", "opencode -p 'test'"], + "install_url": "https://github.com/opencode-ai/opencode", + "auth_check": "echo 'Check environment variables for API keys'", + "description": "OpenCode CLI (multi-provider)" + }, + "qwen": { + "commands": ["qwen", "qwen -p 'test'"], + "install_url": "https://github.com/QwenLM/qwen-code", + "auth_check": "qwen auth status", + "description": "Alibaba Qwen Code CLI" + }, + "droid": { + "commands": ["droid", "droid exec 'test'"], + "install_url": "https://docs.factory.ai/cli/installation", + "auth_check": "droid auth status", + "description": "Factory Droid CLI" + } +} + +def run_command(cmd: str, timeout: int = 30) -> Tuple[int, str, str]: + """Run a command and return exit code, stdout, stderr""" + try: + result = subprocess.run( + cmd.split() if isinstance(cmd, str) else cmd, + capture_output=True, + text=True, + timeout=timeout + ) + return result.returncode, result.stdout, result.stderr + except subprocess.TimeoutExpired: + return -1, "", "Command timed out" + except Exception as e: + return -1, "", str(e) + +def check_agent_installation(agent_name: str, config: Dict) -> Dict: + """Check if an agent is properly installed""" + results = { + "agent": agent_name, + "description": config["description"], + "installed": False, + "version": None, + "auth_status": "unknown", + "basic_test": False, + "errors": [], + "recommendations": [] + } + + # Check if command exists + cmd = config["commands"][0] + exit_code, stdout, stderr = run_command(f"which {cmd}") + + if exit_code != 0: + results["errors"].append(f"Command '{cmd}' not found in PATH") + results["recommendations"].append(f"Install from: {config['install_url']}") + return results + + results["installed"] = True + results["version"] = stdout.strip() or "Unknown version" + + # Check authentication + if "auth_check" in config: + exit_code, auth_stdout, auth_stderr = run_command(config["auth_check"]) + if exit_code == 0: + results["auth_status"] = "authenticated" + else: + results["auth_status"] = "not_authenticated" + results["errors"].append(f"Authentication check failed: {auth_stderr}") + results["recommendations"].append("Run authentication command for this agent") + + # Basic functionality test (try to get help) + exit_code, help_stdout, help_stderr = run_command(f"{cmd} --help", timeout=10) + if exit_code == 0: + results["basic_test"] = True + + return results + +def check_environment_requirements() -> Dict: + """Check general environment requirements""" + results = { + "python_version": sys.version, + "working_directory": os.getcwd(), + "environment_variables": {}, + "recommendations": [] + } + + # Check for common environment variables + env_vars = [ + "ANTHROPIC_API_KEY", + "OPENAI_API_KEY", + "GOOGLE_API_KEY", + "OPENAI_BASE_URL", + "CLAUDE_API_KEY" + ] + + for var in env_vars: + value = os.environ.get(var) + results["environment_variables"][var] = "SET" if value else "NOT_SET" + + # Check git availability + exit_code, stdout, stderr = run_command("git --version") + if exit_code != 0: + results["recommendations"].append("Install git for better agent integration") + + return results + +def print_results(results: List[Dict], env_info: Dict, format_type: str = "table"): + """Print validation results in specified format""" + + if format_type == "json": + output = { + "environment": env_info, + "agents": results + } + print(json.dumps(output, indent=2)) + return + + # Table format + print("\n" + "="*80) + print("๐Ÿค– CLI AGENT SETUP VALIDATION") + print("="*80) + + print(f"\n๐Ÿ“ Working Directory: {env_info['working_directory']}") + print(f"๐Ÿ Python Version: {env_info['python_version'].split()[0]}") + + print("\n๐Ÿ”‘ Environment Variables:") + for var, status in env_info["environment_variables"].items(): + status_icon = "โœ…" if status == "SET" else "โŒ" + print(f" {status_icon} {var}: {status}") + + print("\n" + "="*80) + print("AGENT STATUS") + print("="*80) + + for result in results: + agent = result["agent"] + description = result["description"] + + # Status icons + install_icon = "โœ…" if result["installed"] else "โŒ" + auth_icon = "โœ…" if result["auth_status"] == "authenticated" else "โŒ" if result["auth_status"] == "not_authenticated" else "โš ๏ธ" + test_icon = "โœ…" if result["basic_test"] else "โŒ" + + print(f"\n{install_icon} {agent.upper()}: {description}") + print(f" ๐Ÿ“ฆ Installed: {'Yes' if result['installed'] else 'No'}") + print(f" ๐Ÿ” Auth Status: {result['auth_status']}") + print(f" ๐Ÿงช Basic Test: {'Pass' if result['basic_test'] else 'Fail'}") + + if result["version"]: + print(f" ๐Ÿ“‹ Version: {result['version']}") + + if result["errors"]: + print(" โŒ Errors:") + for error in result["errors"]: + print(f" โ€ข {error}") + + if result["recommendations"]: + print(" ๐Ÿ’ก Recommendations:") + for rec in result["recommendations"]: + print(f" โ€ข {rec}") + + print("\n" + "="*80) + print("SUMMARY") + print("="*80) + + installed_count = sum(1 for r in results if r["installed"]) + auth_count = sum(1 for r in results if r["auth_status"] == "authenticated") + + print(f"๐Ÿ“ฆ Agents Installed: {installed_count}/{len(results)}") + print(f"๐Ÿ” Agents Authenticated: {auth_count}/{len(results)}") + + if env_info["recommendations"]: + print("\n๐Ÿ’ก General Recommendations:") + for rec in env_info["recommendations"]: + print(f" โ€ข {rec}") + +def main(): + """Main validation function""" + import argparse + + parser = argparse.ArgumentParser(description="Validate CLI agent setup") + parser.add_argument("agent", nargs="?", choices=list(AGENTS.keys()), + help="Specific agent to check (default: all)") + parser.add_argument("--format", choices=["table", "json"], default="table", + help="Output format (default: table)") + parser.add_argument("--quiet", action="store_true", + help="Only show summary") + + args = parser.parse_args() + + # Check environment + env_info = check_environment_requirements() + + # Check agents + if args.agent: + agents_to_check = {args.agent: AGENTS[args.agent]} + else: + agents_to_check = AGENTS + + results = [] + for agent_name, config in agents_to_check.items(): + result = check_agent_installation(agent_name, config) + results.append(result) + + if not args.quiet: + print(f"Checking {agent_name}...", end=" ") + if result["installed"]: + print("โœ… Found") + else: + print("โŒ Not found") + + # Print results + if not args.quiet: + print_results(results, env_info, args.format) + else: + # Quiet summary + installed = sum(1 for r in results if r["installed"]) + authenticated = sum(1 for r in results if r["auth_status"] == "authenticated") + print(f"Installed: {installed}/{len(results)} | Authenticated: {authenticated}/{len(results)}") + + # Exit code based on results + if not any(r["installed"] for r in results): + sys.exit(2) # No agents installed + elif not all(r["installed"] for r in results): + sys.exit(1) # Some agents missing + else: + sys.exit(0) # All good + +if __name__ == "__main__": + main() \ No newline at end of file