322 lines
8.8 KiB
Markdown
322 lines
8.8 KiB
Markdown
# 📁 Filesystem Management
|
|
|
|
Advanced filesystem operations for AI agents. Comprehensive file and directory operations with intelligent filtering, searching, and batch processing capabilities.
|
|
|
|
[](https://clawdhub.com/unknown/clawdbot-filesystem)
|
|
[](LICENSE)
|
|
[](https://nodejs.org/)
|
|
|
|
## 🚀 Features
|
|
|
|
### 📋 **Smart File Listing**
|
|
- **Advanced Filtering** - Filter by file types, patterns, size, and date
|
|
- **Recursive Traversal** - Deep directory scanning with depth control
|
|
- **Rich Formatting** - Table, tree, and JSON output formats
|
|
- **Sort Options** - By name, size, date, or type
|
|
|
|
### 🔍 **Powerful Search**
|
|
- **Pattern Matching** - Glob patterns and regex support
|
|
- **Content Search** - Full-text search within files
|
|
- **Multi-criteria** - Combine filename and content searches
|
|
- **Context Display** - Show matching lines with context
|
|
|
|
### 🔄 **Batch Operations**
|
|
- **Safe Copying** - Pattern-based file copying with validation
|
|
- **Dry Run Mode** - Preview operations before execution
|
|
- **Progress Tracking** - Real-time operation progress
|
|
- **Error Handling** - Graceful failure recovery
|
|
|
|
### 🌳 **Directory Analysis**
|
|
- **Tree Visualization** - ASCII tree structure display
|
|
- **Statistics** - File counts, size distribution, type analysis
|
|
- **Space Analysis** - Identify large files and directories
|
|
- **Performance Metrics** - Operation timing and optimization
|
|
|
|
## 📦 Installation
|
|
|
|
### Via ClawdHub (Recommended)
|
|
|
|
```bash
|
|
clawdhub install filesystem
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
```bash
|
|
# Clone the skill
|
|
git clone https://github.com/gtrusler/clawdbot-filesystem.git
|
|
cd clawdbot-filesystem
|
|
|
|
# Make executable
|
|
chmod +x filesystem
|
|
|
|
# Optional: Install globally
|
|
npm install -g .
|
|
```
|
|
|
|
## 🛠️ Usage
|
|
|
|
### Basic Commands
|
|
|
|
```bash
|
|
# List files in current directory
|
|
filesystem list
|
|
|
|
# List with details and filtering
|
|
filesystem list --path ./src --recursive --filter "*.js" --details
|
|
|
|
# Search for content
|
|
filesystem search --pattern "TODO" --path ./src --content
|
|
|
|
# Copy files safely
|
|
filesystem copy --pattern "*.log" --to ./backup/ --dry-run
|
|
|
|
# Show directory tree
|
|
filesystem tree --path ./ --depth 3
|
|
|
|
# Analyze directory
|
|
filesystem analyze --path ./logs --stats --largest 10
|
|
```
|
|
|
|
### Advanced Examples
|
|
|
|
#### Development Workflow
|
|
```bash
|
|
# Find all JavaScript files in project
|
|
filesystem list --path ./src --recursive --filter "*.js" --sort size
|
|
|
|
# Search for TODO comments with context
|
|
filesystem search --pattern "TODO|FIXME|HACK" --content --context 3
|
|
|
|
# Copy all configuration files
|
|
filesystem copy --pattern "*.config.*" --to ./backup/configs/ --preserve
|
|
|
|
# Analyze project structure
|
|
filesystem tree --depth 2 --size
|
|
```
|
|
|
|
#### System Administration
|
|
```bash
|
|
# Find large log files
|
|
filesystem analyze --path /var/log --sizes --largest 15
|
|
|
|
# Search for error patterns in logs
|
|
filesystem search --pattern "ERROR|FATAL" --path /var/log --content --include "*.log"
|
|
|
|
# List recent files
|
|
filesystem list --path /tmp --sort date --details
|
|
|
|
# Clean analysis before deletion
|
|
filesystem list --path /tmp --filter "*.tmp" --details
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
The skill uses a `config.json` file for default settings:
|
|
|
|
```json
|
|
{
|
|
"defaultPath": "./",
|
|
"maxDepth": 10,
|
|
"excludePatterns": ["node_modules", ".git", ".DS_Store"],
|
|
"outputFormat": "table",
|
|
"colorOutput": true,
|
|
"performance": {
|
|
"maxFileSize": 52428800,
|
|
"maxFiles": 10000
|
|
},
|
|
"safety": {
|
|
"requireConfirmation": true,
|
|
"preventSystemPaths": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## 📖 Command Reference
|
|
|
|
### `filesystem list`
|
|
List files and directories with advanced filtering.
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--path, -p` | Target directory | Current directory |
|
|
| `--recursive, -r` | Include subdirectories | false |
|
|
| `--filter, -f` | Filter by pattern | `*` |
|
|
| `--details, -d` | Show file details | false |
|
|
| `--sort, -s` | Sort by field | name |
|
|
| `--format` | Output format | table |
|
|
|
|
### `filesystem search`
|
|
Search files by name patterns or content.
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--pattern` | Search pattern | Required |
|
|
| `--path, -p` | Search directory | Current directory |
|
|
| `--content, -c` | Search file contents | false |
|
|
| `--context` | Context lines | 2 |
|
|
| `--include` | Include patterns | All files |
|
|
| `--exclude` | Exclude patterns | None |
|
|
|
|
### `filesystem copy`
|
|
Batch copy files with pattern matching.
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--pattern` | Source pattern | `*` |
|
|
| `--to` | Destination directory | Required |
|
|
| `--dry-run` | Preview only | false |
|
|
| `--overwrite` | Allow overwrites | false |
|
|
| `--preserve` | Preserve timestamps | false |
|
|
|
|
### `filesystem tree`
|
|
Display directory structure as a tree.
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--path, -p` | Root directory | Current directory |
|
|
| `--depth, -d` | Maximum depth | 3 |
|
|
| `--dirs-only` | Show directories only | false |
|
|
| `--size` | Show file sizes | false |
|
|
| `--no-color` | Disable colors | false |
|
|
|
|
### `filesystem analyze`
|
|
Analyze directory structure and statistics.
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--path, -p` | Target directory | Current directory |
|
|
| `--stats` | Show statistics | true |
|
|
| `--types` | Analyze file types | false |
|
|
| `--sizes` | Size distribution | false |
|
|
| `--largest` | Show N largest files | 10 |
|
|
|
|
## 🛡️ Safety Features
|
|
|
|
- **Path Validation** - Prevents directory traversal attacks
|
|
- **Permission Checks** - Verifies access before operations
|
|
- **Dry Run Mode** - Preview destructive operations
|
|
- **Protected Paths** - Blocks system directory access
|
|
- **Size Limits** - Prevents processing huge files
|
|
- **Timeout Protection** - Prevents infinite operations
|
|
|
|
## 🔧 Integration
|
|
|
|
### With Other Clawdbot Skills
|
|
|
|
```bash
|
|
# Use with security skill
|
|
security validate-command "filesystem list --path /etc"
|
|
|
|
# Pipe to analysis tools
|
|
filesystem list --format json | jq '.[] | select(.size > 1000000)'
|
|
|
|
# Integration with Git workflows
|
|
filesystem list --filter "*.js" --format json | git-analyze-changes
|
|
```
|
|
|
|
### Automation Examples
|
|
|
|
```bash
|
|
# Daily log analysis
|
|
filesystem analyze --path /var/log --stats --largest 5
|
|
|
|
# Code quality checks
|
|
filesystem search --pattern "TODO|FIXME" --content --path ./src
|
|
|
|
# Backup preparation
|
|
filesystem copy --pattern "*.config*" --to ./backup/$(date +%Y%m%d)/
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
Test the installation:
|
|
|
|
```bash
|
|
# Basic functionality
|
|
filesystem help
|
|
filesystem list --path . --details
|
|
|
|
# Search capabilities
|
|
echo "TODO: Test this function" > test.txt
|
|
filesystem search --pattern "TODO" --content
|
|
|
|
# Tree visualization
|
|
filesystem tree --depth 2 --size
|
|
|
|
# Analysis features
|
|
filesystem analyze --stats --types
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Permission Denied**
|
|
```bash
|
|
# Check file permissions
|
|
ls -la filesystem
|
|
chmod +x filesystem
|
|
```
|
|
|
|
**Large Directory Performance**
|
|
```bash
|
|
# Use filtering to narrow scope
|
|
filesystem list --filter "*.log" --exclude "node_modules/*"
|
|
|
|
# Limit depth for tree operations
|
|
filesystem tree --depth 2
|
|
```
|
|
|
|
**Memory Issues with Large Files**
|
|
```bash
|
|
# Files larger than 50MB are skipped by default
|
|
# Check current limits
|
|
node -e "console.log(require('./config.json').performance)"
|
|
```
|
|
|
|
## 📈 Performance Tips
|
|
|
|
- Use `--filter` to narrow file scope
|
|
- Set appropriate `--depth` limits for tree operations
|
|
- Enable exclusion patterns for common build directories
|
|
- Use `--dry-run` first for batch operations
|
|
- Monitor output with `--stats` for large directories
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. **Report Issues** - Submit bugs and feature requests
|
|
2. **Add Patterns** - Contribute common file patterns
|
|
3. **Performance** - Submit optimization improvements
|
|
4. **Documentation** - Help improve examples and guides
|
|
|
|
## 📄 License
|
|
|
|
MIT License - Free for personal and commercial use.
|
|
|
|
See [LICENSE](LICENSE) file for details.
|
|
|
|
## 🔗 Links
|
|
|
|
- **ClawdHub** - [clawdhub.com/unknown/clawdbot-filesystem](https://clawdhub.com/unknown/clawdbot-filesystem)
|
|
- **Issues** - [GitHub Issues](https://github.com/gtrusler/clawdbot-filesystem/issues)
|
|
- **Documentation** - [Clawdbot Docs](https://docs.clawd.bot)
|
|
|
|
## 📢 Updates & Community
|
|
|
|
**Stay informed about the latest Clawdbot skills and filesystem tools:**
|
|
|
|
- 🐦 **Follow [@LexpertAI](https://x.com/LexpertAI)** on X for skill updates and releases
|
|
- 🛠️ **New filesystem features** and enhancements
|
|
- 📋 **Best practices** for file management automation
|
|
- 💡 **Tips and tricks** for productivity workflows
|
|
|
|
Get early access to new skills and improvements by following @LexpertAI for:
|
|
- **Skill announcements** and new releases
|
|
- **Performance optimizations** and feature updates
|
|
- **Integration examples** and workflow automation
|
|
- **Community discussions** on productivity tools
|
|
|
|
---
|
|
|
|
**Built with ❤️ for the Clawdbot community** |