# 🔗 Eyelet - Hook Orchestration for AI Agents
> "Thread through the eyelet!" - A sophisticated hook management system for AI agent workflows
[](https://www.python.org/)
[](https://badge.fury.io/py/eyelet)
[](https://github.com/astral-sh/uv)
[](LICENSE)
[](https://github.com/bdmorin/eyelet/actions/workflows/ci.yml)
[](https://github.com/bdmorin/eyelet)
## 🎉 New in v0.3.5: TUI Exit Fix!
### v0.3.4 Updates
- **Auto-update support**: `--autoupdate` flag for install-all command
- **Version detection**: Doctor command warns about unpinned versions
- **Critical fix**: Execute command now supports both hook_type and hook_event_name
- **Enhanced doctor**: Clear guidance on enabling auto-updates
### v0.3.3 Updates (Hotfix)
- Fixed missing TUI module in PyPI package
- Added .tcss file to package data
### v0.3.2 Updates
- **Recall Feature**: Search Claude Code conversation history with `eyelet recall`
- **TUI Framework**: Complete Textual-based UI (experimental)
- **Test Improvements**: Better test coverage and pytest-asyncio support
### v0.3.0 Features
**SQLite database logging support!** Choose between JSON files, SQLite database, or both:
```bash
# Enable SQLite logging
uvx eyelet configure logging --format sqlite
# Use both JSON and SQLite
uvx eyelet configure logging --format json,sqlite
# Query your hook data
uvx eyelet query search --text "error"
uvx eyelet query summary --last 24h
```
## 📦 About
Eyelet 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.
## ✨ Features
- 🪝 **Universal Hook Support** - Captures all Claude Code hook types ✅
- 💾 **Flexible Logging** - JSON files, SQLite database, or both ✅
- 🔍 **Powerful Queries** - Search, filter, and analyze your hook data ✅
- 🏥 **Health Monitoring** - `eyelet doctor` checks your configuration ✅
- 🚀 **Zero Config** - `eyelet configure install-all` sets up everything ✅
- 📊 **Rich Analytics** - Session summaries, error analysis, and more ✅
- 🔧 **Git Integration** - Automatic Git metadata enrichment ✅
- ⚡ **High Performance** - SQLite with WAL mode for concurrent access ✅
## 🚀 Quick Start
```bash
# Install universal logging for ALL hooks with auto-updates
uvx eyelet configure install-all --autoupdate
# Or install without auto-updates (manual updates required)
uvx eyelet configure install-all
# Enable SQLite logging for better performance
uvx eyelet configure logging --format sqlite
# Check your configuration health (detects unpinned versions)
uvx eyelet doctor
# Query your hook data
uvx eyelet query summary # Session overview
uvx eyelet query search --help # Search options
uvx eyelet query errors # Debug issues
```
### ⚠️ Important: Version Updates
By default, `uvx eyelet` caches the package and won't auto-update. You have three options:
1. **Enable auto-updates** (recommended):
```bash
uvx eyelet configure install-all --autoupdate
```
This uses `uvx eyelet@latest` which always fetches the latest version.
2. **Manual update** when needed:
```bash
uvx --reinstall eyelet@latest execute --log-only
```
3. **Use pipx** for global installation:
```bash
pipx install eyelet
pipx upgrade eyelet # When updates are available
```
Run `eyelet doctor` to check if your hooks are configured for auto-updates.
## 🎯 Universal Hook Handler
Eyelet includes a powerful universal hook handler that logs EVERY Claude Code hook to a structured directory:
```bash
# 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 for reliable connections ✅
- **Template System** - Deploy pre-configured hook patterns with a single command ✅
- **Workflow Engine** - Chain complex behaviors with conditional logic ❌ (Not implemented - raises NotImplementedError)
- **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 ✅ (via `eyelet logs --follow`)
## 📚 Documentation
- [Installation Guide](docs/installation.md)
- [Hook Types & Matchers](docs/hooks.md)
- [Creating Workflows](docs/workflows.md)
- [Template Library](docs/templates.md)
- [API Reference](docs/api.md)
## 🛠️ Commands
```bash
# Core Operations
uvx eyelet configure # Configure hooks ✅
uvx eyelet configure logging # Manage logging settings (JSON/SQLite) ✅
uvx eyelet execute # Run as hook endpoint ✅
uvx eyelet logs # View JSON execution logs ✅
uvx eyelet doctor # Health check and diagnostics ✅
uvx eyelet recall # Search Claude Code conversations (NEW!) ✅
# Query & Analytics (SQLite)
uvx eyelet query search # Full-text search with filters ✅
uvx eyelet query summary # Session and hook statistics ✅
uvx eyelet query errors # Error analysis and debugging ✅
uvx eyelet query session # View specific session logs ✅
uvx eyelet query grep # Pattern matching across logs ✅
# Discovery & Templates
uvx eyelet discover # Find available hooks ✅
uvx eyelet template list # Browse templates ✅
uvx eyelet template install # Deploy a template ✅
```
## 💾 SQLite Logging
Eyelet's SQLite logging provides powerful analytics and querying capabilities:
```bash
# Enable SQLite logging
uvx eyelet configure logging --format sqlite
# Search for specific patterns
uvx eyelet query search --text "error" --tool Bash --last 1h
# Get session summary
uvx eyelet query summary --format json
# Analyze errors
uvx eyelet query errors --last 24h
# Export specific session
uvx eyelet query session <session-id> --format json > session.json
```
### Why SQLite?
- ⚡ **Fast queries** across millions of hooks
- 🔍 **Full-text search** with advanced filters
- 📊 **Analytics** without external dependencies
- 🔄 **Concurrent access** with WAL mode
- 💾 **Compact storage** compared to JSON files
## 🎨 Example Hook Configuration
```json
{
"hooks": [{
"type": "PreToolUse",
"matcher": "Bash",
"handler": {
"type": "command",
"command": "uvx eyelet execute --log-only"
}
}]
}
```
## 🔍 JSON Validation & Linting
Eyelet provides built-in validation for Claude settings files and VS Code integration:
```bash
# 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 ⚠️ (Schema exists but no .vscode/settings.json in project)
- ✅ Real-time error detection ⚠️ (Schema exists but VS Code config not set up)
- ✅ Hover documentation ⚠️ (Schema exists but VS Code config not set up)
See [docs/vscode-json-linting.md](docs/vscode-json-linting.md) for setup instructions.
## 🔗 Connection Philosophy
Eyelet embraces hardware connection terminology for reliable, secure attachment:
- **"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
- **"Hold fast!"** - Maintain current configuration
## 🧪 Testing
Eyelet includes comprehensive testing tools to ensure your hooks are working correctly:
### Testing Hook Integration
```bash
# Run the interactive hook test
mise run test-hooks
# This will generate a unique test ID and guide you through testing all tools
# After running the test commands, verify with:
mise run test-hooks-verify zebra-1234-flamingo-5678
# View hook statistics
mise run hook-stats
# Generate a coverage report
mise run hook-coverage
# Clean old logs (older than 7 days)
mise run hook-clean
```
### Development Testing
```bash
# Run all tests
mise run test
# Run linting
mise run lint
# Run type checking
mise run typecheck
# Run all CI checks
mise run ci
```
### Manual Hook Testing
The `test_all_hooks.py` script provides comprehensive hook testing:
- Generates unique test identifiers for tracking
- Tests all Claude Code tools (Bash, Read, Write, Edit, etc.)
- Verifies hook logs contain expected data
- Provides coverage reports
## 🤝 Contributing
We welcome contributions! Please open issues and pull requests on GitHub.
## 📚 Documentation
- **[Quickstart Guide](docs/QUICKSTART.md)** - Get up and running quickly
- **[Design Documents](docs/design/)** - Architecture and design decisions
- **[Setup Guides](docs/setup/)** - GitHub Actions and deployment setup
## 📜 License
MIT License - see [LICENSE](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.
---
*"The strongest connections are forged under pressure." - Connect with Eyelet and explore the possibilities of AI agent orchestration.*
Raw data
{
"_id": null,
"home_page": null,
"name": "eyelet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "hooks, ai, automation, orchestration, claude-code, eyelet",
"author": "Brian Morin",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d8/64/e7dab606089261c7ef7e33dcbfaab96d16f0d22d25020124d1d340f4bdf9/eyelet-0.3.5.tar.gz",
"platform": null,
"description": "# \ud83d\udd17 Eyelet - Hook Orchestration for AI Agents\n\n> \"Thread through the eyelet!\" - A sophisticated hook management system for AI agent workflows\n\n[](https://www.python.org/)\n[](https://badge.fury.io/py/eyelet)\n[](https://github.com/astral-sh/uv)\n[](LICENSE)\n[](https://github.com/bdmorin/eyelet/actions/workflows/ci.yml)\n[](https://github.com/bdmorin/eyelet)\n\n## \ud83c\udf89 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## \ud83d\udce6 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## \u2728 Features\n\n- \ud83e\ude9d **Universal Hook Support** - Captures all Claude Code hook types \u2705\n- \ud83d\udcbe **Flexible Logging** - JSON files, SQLite database, or both \u2705\n- \ud83d\udd0d **Powerful Queries** - Search, filter, and analyze your hook data \u2705\n- \ud83c\udfe5 **Health Monitoring** - `eyelet doctor` checks your configuration \u2705\n- \ud83d\ude80 **Zero Config** - `eyelet configure install-all` sets up everything \u2705\n- \ud83d\udcca **Rich Analytics** - Session summaries, error analysis, and more \u2705\n- \ud83d\udd27 **Git Integration** - Automatic Git metadata enrichment \u2705\n- \u26a1 **High Performance** - SQLite with WAL mode for concurrent access \u2705\n\n## \ud83d\ude80 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### \u26a0\ufe0f Important: Version Updates\n\nBy default, `uvx eyelet` caches the package and won't auto-update. You have three options:\n\n1. **Enable auto-updates** (recommended):\n ```bash\n uvx eyelet configure install-all --autoupdate\n ```\n This uses `uvx eyelet@latest` which always fetches the latest version.\n\n2. **Manual update** when needed:\n ```bash\n uvx --reinstall eyelet@latest execute --log-only\n ```\n\n3. **Use pipx** for global installation:\n ```bash\n pipx install eyelet\n pipx upgrade eyelet # When updates are available\n ```\n\nRun `eyelet doctor` to check if your hooks are configured for auto-updates.\n\n## \ud83c\udfaf 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\u251c\u2500\u2500 PreToolUse/\n\u2502 \u2514\u2500\u2500 Bash/2025-07-28/\n\u2502 \u2514\u2500\u2500 20250728_133300_236408_PreToolUse_Bash.json\n\u251c\u2500\u2500 PostToolUse/\n\u2502 \u2514\u2500\u2500 Read/2025-07-28/\n\u251c\u2500\u2500 UserPromptSubmit/2025-07-28/\n\u251c\u2500\u2500 Stop/2025-07-28/\n\u2514\u2500\u2500 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## \ud83c\udfaf Features\n\n- **Dynamic Hook Discovery** - Automatically detects new tools and generates all valid hook combinations \u2705\n- **Beautiful TUI** - Navigate with a Textual-powered interface for reliable connections \u2705 \n- **Template System** - Deploy pre-configured hook patterns with a single command \u2705\n- **Workflow Engine** - Chain complex behaviors with conditional logic \u274c (Not implemented - raises NotImplementedError)\n- **Comprehensive Logging** - Track every hook execution in SQLite or filesystem \u2705\n- **AI Integration** - Native Claude Code SDK support for intelligent workflows \u2705\n- **Real-time Monitoring** - Watch hook executions as they happen \u2705 (via `eyelet logs --follow`)\n\n## \ud83d\udcda Documentation\n\n- [Installation Guide](docs/installation.md)\n- [Hook Types & Matchers](docs/hooks.md)\n- [Creating Workflows](docs/workflows.md)\n- [Template Library](docs/templates.md)\n- [API Reference](docs/api.md)\n\n## \ud83d\udee0\ufe0f Commands\n\n```bash\n# Core Operations\nuvx eyelet configure # Configure hooks \u2705\nuvx eyelet configure logging # Manage logging settings (JSON/SQLite) \u2705\nuvx eyelet execute # Run as hook endpoint \u2705\nuvx eyelet logs # View JSON execution logs \u2705\nuvx eyelet doctor # Health check and diagnostics \u2705\nuvx eyelet recall # Search Claude Code conversations (NEW!) \u2705\n\n# Query & Analytics (SQLite)\nuvx eyelet query search # Full-text search with filters \u2705\nuvx eyelet query summary # Session and hook statistics \u2705\nuvx eyelet query errors # Error analysis and debugging \u2705\nuvx eyelet query session # View specific session logs \u2705\nuvx eyelet query grep # Pattern matching across logs \u2705\n\n# Discovery & Templates \nuvx eyelet discover # Find available hooks \u2705\nuvx eyelet template list # Browse templates \u2705\nuvx eyelet template install # Deploy a template \u2705\n```\n\n## \ud83d\udcbe 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 <session-id> --format json > session.json\n```\n\n### Why SQLite?\n- \u26a1 **Fast queries** across millions of hooks\n- \ud83d\udd0d **Full-text search** with advanced filters\n- \ud83d\udcca **Analytics** without external dependencies\n- \ud83d\udd04 **Concurrent access** with WAL mode\n- \ud83d\udcbe **Compact storage** compared to JSON files\n\n## \ud83c\udfa8 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## \ud83d\udd0d JSON Validation & 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- \u2705 IntelliSense/autocomplete for hook configurations \u26a0\ufe0f (Schema exists but no .vscode/settings.json in project)\n- \u2705 Real-time error detection \u26a0\ufe0f (Schema exists but VS Code config not set up)\n- \u2705 Hover documentation \u26a0\ufe0f (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## \ud83d\udd17 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## \ud83e\uddea 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## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please open issues and pull requests on GitHub.\n\n## \ud83d\udcda 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## \ud83d\udcdc License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83d\ude4f 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.*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Hook orchestration system for AI agents with SQLite logging and powerful analytics",
"version": "0.3.5",
"project_urls": {
"Documentation": "https://github.com/bdmorin/eyelet#readme",
"Homepage": "https://github.com/bdmorin/eyelet",
"Issues": "https://github.com/bdmorin/eyelet/issues",
"Repository": "https://github.com/bdmorin/eyelet"
},
"split_keywords": [
"hooks",
" ai",
" automation",
" orchestration",
" claude-code",
" eyelet"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "402fd961c4423076221cdafc22b54499581a3de04d0eb5eac973e5faec27fe87",
"md5": "713ebdaed1985d034fcf69dad18b28e0",
"sha256": "384107ce68ff420fe187ebbd076db0d9f9306fd669db0fbe2ff5986ef6f3197f"
},
"downloads": -1,
"filename": "eyelet-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "713ebdaed1985d034fcf69dad18b28e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 114182,
"upload_time": "2025-09-06T20:02:43",
"upload_time_iso_8601": "2025-09-06T20:02:43.542219Z",
"url": "https://files.pythonhosted.org/packages/40/2f/d961c4423076221cdafc22b54499581a3de04d0eb5eac973e5faec27fe87/eyelet-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d864e7dab606089261c7ef7e33dcbfaab96d16f0d22d25020124d1d340f4bdf9",
"md5": "51ac3798279895c1be164fdec49f52ff",
"sha256": "7d5c187c9cd7b5f5627f565873bf5bdef0ddafdba54ef78a5766cb25c5b948b8"
},
"downloads": -1,
"filename": "eyelet-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "51ac3798279895c1be164fdec49f52ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 148873,
"upload_time": "2025-09-06T20:02:44",
"upload_time_iso_8601": "2025-09-06T20:02:44.929454Z",
"url": "https://files.pythonhosted.org/packages/d8/64/e7dab606089261c7ef7e33dcbfaab96d16f0d22d25020124d1d340f4bdf9/eyelet-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 20:02:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bdmorin",
"github_project": "eyelet#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eyelet"
}
JSON
