Skill: gtrusler/clawdbot-filesystem (version 1.0.2)

--- name: filesystem description: Advanced filesystem operations - listing, searching, batch processing, and directory analysis for Clawdbot homepage: https://github.com/gtrusler/clawdbot-filesystem metadata: {"clawdbot":{"emoji":"📁","requires":{"bins":["node"]}}} --- # 📁 Filesystem Management Advanced filesystem operations for AI agents. Comprehensive file and directory operations with intelligent filtering, searching, and batch processing capabilities. ## 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 ## Quick Start ```bash # List files with filtering filesystem list --path ./src --recursive --filter "*.js" # Search for content filesystem search --pattern "TODO" --path ./src --content # Batch copy with safety filesystem copy --pattern "*.log" --to ./backup/ --dry-run # Show directory tree filesystem tree --path ./ --depth 3 # Analyze directory structure filesystem analyze --path ./logs --stats ``` ## Command Reference ### `filesystem list` Advanced file and directory listing with filtering options. **Options:** - `--path, -p <dir>` - Target directory (default: current) - `--recursive, -r` - Include subdirectories - `--filter, -f <pattern>` - Filter files by pattern - `--details, -d` - Show detailed information - `--sort, -s <field>` - Sort by name|size|date - `--format <type>` - Output format: table|json|list ### `filesystem search` Search files by name patterns or content. **Options:** - `--pattern <pattern>` - Search pattern (glob or regex) - `--path, -p <dir>` - Search directory - `--content, -c` - Search file contents - `--context <lines>` - Show context lines - `--include <pattern>` - Include file patterns - `--exclude <pattern>` - Exclude file patterns ### `filesystem copy` Batch copy files with pattern matching and safety checks. **Options:** - `--pattern <glob>` - Source file pattern - `--to <dir>` - Destination directory - `--dry-run` - Preview without executing - `--overwrite` - Allow file overwrites - `--preserve` - Preserve timestamps and permissions ### `filesystem tree` Display directory structure as a tree. **Options:** - `--path, -p <dir>` - Root directory - `--depth, -d <num>` - Maximum depth - `--dirs-only` - Show directories only - `--size` - Include file sizes - `--no-color` - Disable colored output ### `filesystem analyze` Analyze directory structure and generate statistics. **Options:** - `--path, -p <dir>` - Target directory - `--stats` - Show detailed statistics - `--types` - Analyze file types - `--sizes` - Show size distribution - `--largest <num>` - Show N largest files ## Installation ```bash # Clone or install the skill cd ~/.clawdbot/skills git clone <filesystem-skill-repo> # Or install via ClawdHub clawdhub install filesystem # Make executable chmod +x filesystem/filesystem ``` ## Configuration Customize behavior via `config.json`: ```json { "defaultPath": "./", "maxDepth": 10, "defaultFilters": ["*"], "excludePatterns": ["node_modules", ".git", ".DS_Store"], "outputFormat": "table", "dateFormat": "YYYY-MM-DD HH:mm:ss", "sizeFormat": "human", "colorOutput": true } ``` ## Examples ### Development Workflow ```bash # Find all JavaScript files in src filesystem list --path ./src --recursive --filter "*.js" --details # Search for TODO comments filesystem search --pattern "TODO|FIXME" --path ./src --content --context 2 # Copy all logs to backup filesystem copy --pattern "*.log" --to ./backup/logs/ --preserve # Analyze project structure filesystem tree --path ./ --depth 2 --size ``` ### System Administration ```bash # Find large files filesystem analyze --path /var/log --sizes --largest 10 # List recent files filesystem list --path /tmp --sort date --details # Clean old temp files filesystem list --path /tmp --filter "*.tmp" --older-than 7d ``` ## Safety Features - **Path Validation** - Prevents directory traversal attacks - **Permission Checks** - Verifies read/write access before operations - **Dry Run Mode** - Preview destructive operations - **Backup Prompts** - Suggests backups before overwrites - **Error Recovery** - Graceful handling of permission errors ## Integration Works seamlessly with other Clawdbot tools: - **Security Skill** - Validates all filesystem operations - **Git Operations** - Respects .gitignore patterns - **Backup Tools** - Integrates with backup workflows - **Log Analysis** - Perfect for log file management ## 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 ## License MIT License - Free for personal and commercial use. --- **Remember**: Great filesystem management starts with the right tools. This skill provides comprehensive operations while maintaining safety and performance.

path: LICENSE.md
content: MIT License

Copyright (c) 2026 Clawdbot Community

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

path: README.md
content: # 📁 Filesystem Management

Advanced filesystem operations for AI agents. Comprehensive file and directory operations with intelligent filtering, searching, and batch processing capabilities.

[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://clawdhub.com/unknown/clawdbot-filesystem)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](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**

path: config.json
content: {
  "name": "clawdbot-filesystem",
  "version": "1.0.0",
  "description": "Advanced filesystem operations for Clawdbot",
  "defaultPath": "./",
  "maxDepth": 10,
  "defaultFilters": ["*"],
  "excludePatterns": [
    "node_modules",
    ".git",
    ".DS_Store",
    "*.tmp",
    "*.swp",
    "*.log~",
    ".cache",
    "dist",
    "build"
  ],
  "outputFormat": "table",
  "dateFormat": "YYYY-MM-DD HH:mm:ss",
  "sizeFormat": "human",
  "colorOutput": true,
  "performance": {
    "maxFileSize": 52428800,
    "maxFiles": 10000,
    "timeoutMs": 30000
  },
  "safety": {
    "requireConfirmation": true,
    "preventSystemPaths": true,
    "allowedOperations": ["read", "copy", "analyze"],
    "protectedPaths": [
      "/etc",
      "/var/lib",
      "/usr/bin",
      "/system",
      "C:\\Windows",
      "C:\\Program Files"
    ]
  }
}

path: package.json
content: {
  "name": "clawdbot-filesystem",
  "version": "1.0.2",
  "description": "Advanced filesystem operations - listing, searching, batch processing, and analysis",
  "main": "filesystem",
  "bin": {
    "filesystem": "./filesystem"
  },
  "scripts": {
    "start": "node filesystem",
    "test": "node filesystem help",
    "install-global": "npm link",
    "uninstall-global": "npm unlink"
  },
  "keywords": [
    "clawdbot",
    "filesystem",
    "files",
    "directories",
    "search",
    "batch-operations",
    "file-management",
    "cli-tool",
    "ai-agent",
    "automation"
  ],
  "author": "Clawdbot Community",
  "license": "MIT",
  "homepage": "https://clawdhub.com/unknown/clawdbot-filesystem",
  "repository": {
    "type": "git",
    "url": "https://github.com/gtrusler/clawdbot-filesystem"
  },
  "bugs": {
    "url": "https://github.com/gtrusler/clawdbot-filesystem/issues"
  },
  "engines": {
    "node": ">=14.0.0"
  },
  "os": ["darwin", "linux", "win32"],
  "preferGlobal": true,
  "files": [
    "filesystem",
    "config.json",
    "SKILL.md",
    "README.md",
    "LICENSE.md"
  ],
  "clawdbot": {
    "skill": true,
    "emoji": "📁",
    "category": "System Tools",
    "requires": {
      "bins": ["node"]
    },
    "permissions": {
      "filesystem": "read-write",
      "network": "none",
      "system": "none"
    },
    "tags": [
      "filesystem",
      "files",
      "search",
      "batch-ops",
      "productivity"
    ]
  }
}

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)