{"id":30196432,"url":"https://github.com/bdmorin/eyelet","last_synced_at":"2025-10-14T06:02:10.506Z","repository":{"id":307001992,"uuid":"1027986118","full_name":"bdmorin/eyelet","owner":"bdmorin","description":"Eyelet - Claude Code Hook Orchestration Framework","archived":false,"fork":false,"pushed_at":"2025-07-28T22:34:30.000Z","size":130,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T01:29:54.137Z","etag":null,"topics":["ai-agents","claude-code","claude-hook","claude-hooks","eyelet","hook-orchestration","python-cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bdmorin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T20:59:54.000Z","updated_at":"2025-07-29T01:04:15.000Z","dependencies_parsed_at":"2025-07-28T23:27:35.671Z","dependency_job_id":"dcdd8dca-8a23-414d-9f94-efb9296e23ff","html_url":"https://github.com/bdmorin/eyelet","commit_stats":null,"previous_names":["bdmorin/rigging","bdmorin/eyelet"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bdmorin/eyelet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdmorin%2Feyelet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdmorin%2Feyelet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdmorin%2Feyelet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdmorin%2Feyelet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdmorin","download_url":"https://codeload.github.com/bdmorin/eyelet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdmorin%2Feyelet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270183894,"owners_count":24541412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","claude-hook","claude-hooks","eyelet","hook-orchestration","python-cli"],"created_at":"2025-08-13T05:21:44.229Z","updated_at":"2025-10-14T06:02:10.498Z","avatar_url":"https://github.com/bdmorin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔗 Eyelet - Hook Orchestration for AI Agents\n\n\u003e \"Thread through the eyelet!\" - A sophisticated hook management system for AI agent workflows\n\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![PyPI version](https://badge.fury.io/py/eyelet.svg)](https://badge.fury.io/py/eyelet)\n[![uv](https://img.shields.io/badge/uv-latest-green)](https://github.com/astral-sh/uv)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![CI](https://github.com/bdmorin/eyelet/actions/workflows/ci.yml/badge.svg)](https://github.com/bdmorin/eyelet/actions/workflows/ci.yml)\n[![Status](https://img.shields.io/badge/status-alpha-yellow)](https://github.com/bdmorin/eyelet)\n\n## 🎉 New in v0.3.5: TUI Exit Fix!\n\n### v0.3.4 Updates\n- **Auto-update support**: `--autoupdate` flag for install-all command\n- **Version detection**: Doctor command warns about unpinned versions\n- **Critical fix**: Execute command now supports both hook_type and hook_event_name\n- **Enhanced doctor**: Clear guidance on enabling auto-updates\n\n### v0.3.3 Updates (Hotfix)\n- Fixed missing TUI module in PyPI package\n- Added .tcss file to package data\n\n### v0.3.2 Updates\n- **Recall Feature**: Search Claude Code conversation history with `eyelet recall`\n- **TUI Framework**: Complete Textual-based UI (experimental)\n- **Test Improvements**: Better test coverage and pytest-asyncio support\n\n### v0.3.0 Features\n**SQLite database logging support!** Choose between JSON files, SQLite database, or both:\n\n```bash\n# Enable SQLite logging\nuvx eyelet configure logging --format sqlite\n\n# Use both JSON and SQLite\nuvx eyelet configure logging --format json,sqlite\n\n# Query your hook data\nuvx eyelet query search --text \"error\"\nuvx eyelet query summary --last 24h\n```\n\n## 📦 About\n\nEyelet provides comprehensive management, templating, and execution handling for AI agent hooks. Like an eyelet that securely connects hooks to fabric, Eyelet connects and orchestrates your AI agent's behavior through a reliable workflow system.\n\n## ✨ Features\n\n- 🪝 **Universal Hook Support** - Captures all Claude Code hook types ✅\n- 💾 **Flexible Logging** - JSON files, SQLite database, or both ✅\n- 🔍 **Powerful Queries** - Search, filter, and analyze your hook data ✅\n- 🏥 **Health Monitoring** - `eyelet doctor` checks your configuration ✅\n- 🚀 **Zero Config** - `eyelet configure install-all` sets up everything ✅\n- 📊 **Rich Analytics** - Session summaries, error analysis, and more ✅\n- 🔧 **Git Integration** - Automatic Git metadata enrichment ✅\n- ⚡ **High Performance** - SQLite with WAL mode for concurrent access ✅\n\n## 🚀 Quick Start\n\n```bash\n# Install universal logging for ALL hooks with auto-updates\nuvx eyelet configure install-all --autoupdate\n\n# Or install without auto-updates (manual updates required)\nuvx eyelet configure install-all\n\n# Enable SQLite logging for better performance\nuvx eyelet configure logging --format sqlite\n\n# Check your configuration health (detects unpinned versions)\nuvx eyelet doctor\n\n# Query your hook data\nuvx eyelet query summary          # Session overview\nuvx eyelet query search --help    # Search options\nuvx eyelet query errors           # Debug issues\n```\n\n### 📊 Web Dashboard\n\nThe web dashboard provides real-time monitoring of all eyelet databases. Since it requires additional dependencies, you have three options:\n\n```bash\n# Option 1: Install locally with web dependencies\nuv add eyelet[web] fastapi uvicorn[standard] jinja2\neyelet dashboard web --open-browser\n\n# Option 2: Use uvx with dependencies (one-time setup)\nuvx --with fastapi --with \"uvicorn[standard]\" --with jinja2 eyelet dashboard web -o\n\n# Option 3: Use CLI-only commands (no web dependencies required)\nuvx eyelet dashboard metrics      # Static metrics\nuvx eyelet dashboard hooks        # Recent hooks table\nuvx eyelet dashboard search \"error\"  # Search across databases\n```\n\nThe web dashboard automatically finds available ports (preferring 443) and generates sslip.io URLs for easy access.\n\n### ⚠️ Important: Keeping Eyelet Updated\n\nWhen using `uvx`, eyelet runs in an isolated environment. To ensure you're using the latest version:\n\n1. **Always use @latest tag** (recommended):\n   ```bash\n   uvx eyelet@latest [command]\n   ```\n   This fetches the latest version from PyPI every time.\n\n2. **For persistent installation with uv**:\n   ```bash\n   uv tool install eyelet@latest              # Install latest\n   uv tool install --reinstall eyelet@latest  # Force reinstall\n   ```\n\n3. **Enable auto-updates in hooks**:\n   ```bash\n   uvx eyelet configure install-all --autoupdate\n   ```\n   This configures hooks to use `uvx eyelet@latest` which always fetches the latest version.\n\n4. **Check current version**:\n   ```bash\n   uvx eyelet --version\n   ```\n\n5. **Use pipx for global installation** (auto-updatable):\n   ```bash\n   pipx install eyelet\n   pipx upgrade eyelet  # When updates are available\n   ```\n\nSee [Update Guide](docs/UPDATE_GUIDE.md) for detailed update instructions.\n\nRun `eyelet doctor` to check if your hooks are configured for auto-updates.\n\n### 🔧 Integration with mise\n\nIf you're using [mise](https://mise.jdx.dev/) for project management, add eyelet to your `.mise.toml`:\n\n```toml\n# .mise.toml or mise.toml\n[tools]\npython = \"3.11\"\n\n[tasks.hooks-install]\ndescription = \"Install eyelet hooks for Claude Code\"\nrun = \"uvx eyelet@latest configure install-all --autoupdate\"\n\n[tasks.hooks-doctor]\ndescription = \"Check eyelet configuration and version\"\nrun = \"\"\"\nuvx eyelet@latest doctor\necho \"📌 Version: $(uvx eyelet@latest --version)\"\n\"\"\"\n\n[tasks.hooks-logs]\ndescription = \"View recent hook logs\"\nrun = \"uvx eyelet@latest logs --tail 20\"\n\n# Shortcuts\n[tasks.hd]\nalias = \"hooks-doctor\"\n```\n\nThen use:\n```bash\nmise run hooks-install  # Set up eyelet hooks\nmise run hd            # Check configuration (shortcut)\nmise run hooks-logs    # View recent logs\n```\n\nSee [full example](.mise.toml) for more tasks and options.\n\n**Note:** Eyelet is designed to run via `uvx`. Local installation may require additional configuration (YMMV).\n\n## 🎯 Universal Hook Handler\n\nEyelet includes a powerful universal hook handler that logs EVERY Claude Code hook to a structured directory:\n\n```bash\n# Install logging for all hooks with one command\nuvx eyelet configure install-all\n\n# Your hooks will be logged to:\n./eyelet-hooks/\n├── PreToolUse/\n│   └── Bash/2025-07-28/\n│       └── 20250728_133300_236408_PreToolUse_Bash.json\n├── PostToolUse/\n│   └── Read/2025-07-28/\n├── UserPromptSubmit/2025-07-28/\n├── Stop/2025-07-28/\n└── PreCompact/manual/2025-07-28/\n```\n\nEach log contains:\n- Complete input data from Claude Code\n- Environment variables and context\n- Timestamps (ISO and Unix)\n- Session information\n- Tool inputs/outputs\n- Python version and platform details\n\n## 🎯 Features\n\n- **Dynamic Hook Discovery** - Automatically detects new tools and generates all valid hook combinations ✅\n- **Beautiful TUI** - Navigate with a Textual-powered interface for reliable connections ✅ \n- **Template System** - Deploy pre-configured hook patterns with a single command ✅\n- **Workflow Engine** - Chain complex behaviors with conditional logic ❌ (Not implemented - raises NotImplementedError)\n- **Comprehensive Logging** - Track every hook execution in SQLite or filesystem ✅\n- **AI Integration** - Native Claude Code SDK support for intelligent workflows ✅\n- **Real-time Monitoring** - Watch hook executions as they happen ✅ (via `eyelet logs --follow`)\n\n## 📚 Documentation\n\n- [Installation Guide](docs/installation.md)\n- [Hook Types \u0026 Matchers](docs/hooks.md)\n- [Creating Workflows](docs/workflows.md)\n- [Template Library](docs/templates.md)\n- [API Reference](docs/api.md)\n\n## 🛠️ Commands\n\n```bash\n# Core Operations\nuvx eyelet configure         # Configure hooks ✅\nuvx eyelet configure logging # Manage logging settings (JSON/SQLite) ✅\nuvx eyelet execute          # Run as hook endpoint ✅\nuvx eyelet logs             # View JSON execution logs ✅\nuvx eyelet doctor           # Health check and diagnostics ✅\nuvx eyelet recall           # Search Claude Code conversations (NEW!) ✅\n\n# Query \u0026 Analytics (SQLite)\nuvx eyelet query search     # Full-text search with filters ✅\nuvx eyelet query summary    # Session and hook statistics ✅\nuvx eyelet query errors     # Error analysis and debugging ✅\nuvx eyelet query session    # View specific session logs ✅\nuvx eyelet query grep       # Pattern matching across logs ✅\n\n# Discovery \u0026 Templates  \nuvx eyelet discover         # Find available hooks ✅\nuvx eyelet template list    # Browse templates ✅\nuvx eyelet template install # Deploy a template ✅\n```\n\n## 💾 SQLite Logging\n\nEyelet's SQLite logging provides powerful analytics and querying capabilities:\n\n```bash\n# Enable SQLite logging\nuvx eyelet configure logging --format sqlite\n\n# Search for specific patterns\nuvx eyelet query search --text \"error\" --tool Bash --last 1h\n\n# Get session summary\nuvx eyelet query summary --format json\n\n# Analyze errors\nuvx eyelet query errors --last 24h\n\n# Export specific session\nuvx eyelet query session \u003csession-id\u003e --format json \u003e session.json\n```\n\n### Why SQLite?\n- ⚡ **Fast queries** across millions of hooks\n- 🔍 **Full-text search** with advanced filters\n- 📊 **Analytics** without external dependencies\n- 🔄 **Concurrent access** with WAL mode\n- 💾 **Compact storage** compared to JSON files\n\n## 🎨 Example Hook Configuration\n\n```json\n{\n  \"hooks\": [{\n    \"type\": \"PreToolUse\",\n    \"matcher\": \"Bash\",\n    \"handler\": {\n      \"type\": \"command\", \n      \"command\": \"uvx eyelet execute --log-only\"\n    }\n  }]\n}\n```\n\n## 🔍 JSON Validation \u0026 Linting\n\nEyelet provides built-in validation for Claude settings files and VS Code integration:\n\n```bash\n# Validate your Claude settings\nuvx eyelet validate settings\n\n# Validate a specific file\nuvx eyelet validate settings ~/.claude/settings.json\n```\n\n### VS Code Integration\n\nThe project includes a JSON schema for Claude settings files. VS Code users get:\n- ✅ IntelliSense/autocomplete for hook configurations ⚠️ (Schema exists but no .vscode/settings.json in project)\n- ✅ Real-time error detection ⚠️ (Schema exists but VS Code config not set up)\n- ✅ Hover documentation ⚠️ (Schema exists but VS Code config not set up)\n\nSee [docs/vscode-json-linting.md](docs/vscode-json-linting.md) for setup instructions.\n\n## 🔗 Connection Philosophy\n\nEyelet embraces hardware connection terminology for reliable, secure attachment:\n\n- **\"Thread through the eyelet!\"** - Launch the TUI\n- **\"Secure the connection!\"** - Deploy templates  \n- **\"Check the connection log\"** - View logs\n- **\"Scan for connection points\"** - Discover new hooks\n- **\"Hold fast!\"** - Maintain current configuration\n\n## 🧪 Testing\n\nEyelet includes comprehensive testing tools to ensure your hooks are working correctly:\n\n### Testing Hook Integration\n\n```bash\n# Run the interactive hook test\nmise run test-hooks\n\n# This will generate a unique test ID and guide you through testing all tools\n# After running the test commands, verify with:\nmise run test-hooks-verify zebra-1234-flamingo-5678\n\n# View hook statistics\nmise run hook-stats\n\n# Generate a coverage report\nmise run hook-coverage\n\n# Clean old logs (older than 7 days)\nmise run hook-clean\n```\n\n### Development Testing\n\n```bash\n# Run all tests\nmise run test\n\n# Run linting\nmise run lint\n\n# Run type checking\nmise run typecheck\n\n# Run all CI checks\nmise run ci\n```\n\n### Manual Hook Testing\n\nThe `test_all_hooks.py` script provides comprehensive hook testing:\n- Generates unique test identifiers for tracking\n- Tests all Claude Code tools (Bash, Read, Write, Edit, etc.)\n- Verifies hook logs contain expected data\n- Provides coverage reports\n\n## 🤝 Contributing\n\nWe welcome contributions! Please open issues and pull requests on GitHub.\n\n## 📚 Documentation\n\n- **[Quickstart Guide](docs/QUICKSTART.md)** - Get up and running quickly\n- **[Design Documents](docs/design/)** - Architecture and design decisions\n- **[Setup Guides](docs/setup/)** - GitHub Actions and deployment setup\n\n## 📜 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\nBuilt with love for the AI development community. Special thanks to the Anthropic team for Claude Code and its powerful hook system.\n\n---\n\n*\"The strongest connections are forged under pressure.\" - Connect with Eyelet and explore the possibilities of AI agent orchestration.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdmorin%2Feyelet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdmorin%2Feyelet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdmorin%2Feyelet/lists"}