---
slug: "clawd-tavily"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/bert-builder/clawd-tavily@main/README.md"
repo: "https://github.com/bert-builder/clawd-tavily"
source_file: "README.md"
branch: "main"
---
# Tavily Search Skill for Clawdbot

AI-optimized web search integration for Clawdbot using the Tavily Search API.

## Features

- 🤖 **AI-Optimized Results**: Search results specifically formatted for LLM consumption
- ⚡ **Fast & Comprehensive Modes**: Choose between quick lookups (`basic`) or deep research (`advanced`)
- 🎯 **Domain Filtering**: Include or exclude specific domains for trusted sources
- 📰 **News Mode**: Current events search (last 7 days)
- 🖼️ **Image Search**: Include relevant images in results
- 📄 **Content Extraction**: Get raw HTML content for deeper analysis
- ✨ **AI Answer Generation**: Optional synthesized answers from search results

## Quick Start

### Installation

1. **Clone this repository**:
   ```bash
   git clone https://github.com/bert-builder/clawd-tavily.git
   cd clawd-tavily
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Get a Tavily API key**:
   - Visit https://tavily.com
   - Sign up for an account
   - Generate an API key from your dashboard

4. **Configure the skill**:
   
   **Option A**: Add to Clawdbot config (`~/.clawdbot/clawdbot.json`):
   ```json
   {
     "skills": {
       "entries": {
         "tavily": {
           "enabled": true,
           "apiKey": "tvly-YOUR_API_KEY_HERE"
         }
       }
     }
   }
   ```
   
   **Option B**: Set environment variable:
   ```bash
   export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"
   ```

### Basic Usage

```bash
# Simple search
./tavily/scripts/tavily_search.py "What is quantum computing?"

# Advanced research
./tavily/scripts/tavily_search.py "AI safety research" --depth advanced --max-results 10

# News search
./tavily/scripts/tavily_search.py "latest AI developments" --topic news

# Domain-specific search
./tavily/scripts/tavily_search.py "Python tutorials" \
  --include-domains python.org docs.python.org

# With images
./tavily/scripts/tavily_search.py "modern architecture" --images
```

## Installation for Clawdbot

### Local Installation (Testing)

1. **Install the skill**:
   ```bash
   # From the repo root
   clawdbot skills install ./tavily
   ```

2. **Verify installation**:
   ```bash
   clawdbot skills list | grep tavily
   ```

3. **Test the skill**:
   ```bash
   # In a Clawdbot session
   /skill tavily
   ```

### Publishing to ClawdHub

Once tested and ready:

1. **Package the skill**:
   ```bash
   python3 /opt/homebrew/lib/node_modules/clawdbot/skills/skill-creator/scripts/package_skill.py ./tavily
   ```

2. **Create a PR to Clawdbot**:
   - Fork https://github.com/clawdbot/clawdbot
   - Add the skill to `skills/`
   - Submit a pull request

3. **Publish to ClawdHub**:
   - Follow the ClawdHub submission guidelines
   - Share on Discord: https://discord.com/invite/clawd

## Documentation

- **SKILL.md**: Complete usage guide with examples and best practices
- **references/api-reference.md**: Detailed API documentation
- **Architecture diagram**: See SKILL.md for Mermaid flow diagram

## Testing

### Manual Testing

```bash
# Run the test suite
python3 -m pytest tests/ -v

# Test basic search
./tavily/scripts/tavily_search.py "test query" --api-key "$TAVILY_API_KEY"

# Test advanced features
./tavily/scripts/tavily_search.py "test" \
  --depth advanced \
  --topic news \
  --images \
  --max-results 10 \
  --include-domains example.com
```

### Integration Testing

```bash
# Test with Clawdbot
clawdbot chat --agent test-agent
> Search for "quantum computing" using Tavily
```

## API Key Management

### Secure Storage

**DO NOT** commit API keys to the repository!

1. Use environment variables
2. Store in Clawdbot config
3. Use `.env` files (ignored by git)
4. Use secret management services for production

### Key Format

Tavily API keys start with `tvly-` followed by the key string:
```
tvly-abc123def456ghi789...
```

## Cost & Rate Limits

- Each search consumes credits based on depth:
  - `basic`: 1 credit
  - `advanced`: ~3-5 credits (varies)
- Free tier available
- Check https://tavily.com/pricing for current plans

## Comparison with Other Search APIs

| Feature | Tavily | Brave | Perplexity |
|---------|--------|-------|------------|
| AI Answer | ✅ | ❌ | ✅ |
| Raw Content | ✅ | ❌ | ❌ |
| Domain Filter | ✅ | Limited | ❌ |
| News Mode | ✅ | ✅ | ✅ |
| Free Tier | ✅ | ✅ | Limited |
| LLM Optimized | ✅ | ❌ | ✅ |

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/clawd-tavily.git
cd clawd-tavily

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Package for testing
python3 /path/to/package_skill.py ./tavily
```

## License

MIT License - see [LICENSE](https://github.com/bert-builder/clawd-tavily/tree/HEAD/LICENSE) for details

## Support

- **Issues**: https://github.com/bert-builder/clawd-tavily/issues
- **Clawdbot Discord**: https://discord.com/invite/clawd
- **Tavily Docs**: https://docs.tavily.com

## Credits

- Built for [Clawdbot](https://github.com/clawdbot/clawdbot)
- Powered by [Tavily Search API](https://tavily.com)
- Created by [@bert-builder](https://github.com/bert-builder)

## Changelog

### v1.0.0 (2026-01-24)

- Initial release
- Basic and advanced search modes
- Domain filtering
- News topic support
- Image search
- AI answer generation
- Raw content extraction
- Comprehensive documentation
- Mermaid architecture diagram