eyelet 0.2.0

Hook orchestration system for AI agents - Thread through the eyelet!

🔗 Eyelet - Hook Orchestration for AI Agents

"Connect your workflows!" - A sophisticated hook management system for AI agent workflows

Eyelet provides comprehensive management, templating, and execution handling for AI agent hooks. Like hardware eyelets that provide strong, reliable connection points, Eyelet creates secure attachment points for your AI agent workflows and orchestrations.

🚀 Quick Start

Note: All commands use the simple uvx eyelet format as the package is published as eyelet on PyPI.

# Install with uvx (recommended)
uvx eyelet

# Install universal logging for ALL hooks (recommended!)
uvx eyelet configure install-all

# Connect to the TUI
uvx eyelet

# Configure hooks for your project
uvx eyelet configure --scope project

# Install a template
uvx eyelet template install observability

🎯 Universal Hook Handler

Eyelet includes a powerful universal hook handler that logs EVERY Claude Code hook to a structured directory:

# Install logging for all hooks with one command
uvx eyelet configure install-all

# Your hooks will be logged to:
./eyelet-hooks/
├── PreToolUse/
│   └── Bash/2025-07-28/
│       └── 20250728_133300_236408_PreToolUse_Bash.json
├── PostToolUse/
│   └── Read/2025-07-28/
├── UserPromptSubmit/2025-07-28/
├── Stop/2025-07-28/
└── PreCompact/manual/2025-07-28/

Each log contains:

• Complete input data from Claude Code
• Environment variables and context
• Timestamps (ISO and Unix)
• Session information
• Tool inputs/outputs
• Python version and platform details

🎯 Features

• Dynamic Hook Discovery - Automatically detects new tools and generates all valid hook combinations
• Beautiful TUI - Navigate with a Textual-powered interface worthy of a ship's bridge
• Template System - Deploy pre-configured hook patterns with a single command
• Workflow Engine - Chain complex behaviors with conditional logic
• Comprehensive Logging - Track every hook execution in SQLite or filesystem
• AI Integration - Native Claude Code SDK support for intelligent workflows
• Real-time Monitoring - Watch hook executions as they happen

📚 Documentation

• Installation Guide
• Hook Types & Matchers
• Creating Workflows
• Template Library
• API Reference

🛠️ Commands

# Core Operations
uvx eyelet configure    # Configure hooks
uvx eyelet execute      # Run as hook endpoint
uvx eyelet logs         # View execution logs

# Discovery & Generation  
uvx eyelet discover     # Find available hooks
uvx eyelet generate     # Create hook combinations
uvx eyelet update       # Check for updates

# Templates & Workflows
uvx eyelet template list      # Browse available templates
uvx eyelet template install   # Deploy a template
uvx eyelet workflow create    # Build custom workflows

🎨 Example Hook Configuration

{
  "hooks": [{
    "type": "PreToolUse",
    "matcher": "Bash",
    "handler": {
      "type": "command", 
      "command": "uvx eyelet execute --workflow bash-validator"
    }
  }]
}

🔍 JSON Validation & Linting

Eyelet provides built-in validation for Claude settings files and VS Code integration:

# Validate your Claude settings
uvx eyelet validate settings

# Validate a specific file
uvx eyelet validate settings ~/.claude/settings.json

VS Code Integration

The project includes a JSON schema for Claude settings files. VS Code users get:

• ✅ IntelliSense/autocomplete for hook configurations
• ✅ Real-time error detection
• ✅ Hover documentation

See docs/vscode-json-linting.md for setup instructions.

🔗 Connection Point Philosophy

Eyelet embraces hardware connection terminology, providing strong, reliable attachment points:

• "Thread through the eyelet!" - Launch the TUI
• "Secure the connection!" - Deploy templates
• "Check the connection log" - View logs
• "Scan for connection points" - Discover new hooks
• "Maintain the connections" - Keep current configuration stable

🤝 Contributing

We welcome contributions! Please open issues and pull requests on GitHub.

📚 Documentation

• Quickstart Guide - Get up and running quickly
• Design Documents - Architecture and design decisions
• Setup Guides - GitHub Actions and deployment setup

📜 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with love for the AI development community. Special thanks to the Anthropic team for Claude Code and its powerful hook system.

---

"Strong connections enable great possibilities." - Thread through Eyelet and explore the potential of AI agent orchestration.