@qodo/sdk 0.13.4 → 2.0.0-next.0

package/.claude/skills/qodo-agent/references/builtin-tools.md

@@ -1,342 +0,0 @@
-# Built-in Tools Reference
-
-This guide covers the built-in MCP tools available in `@qodo/sdk` and when to use each one.
-
-## Overview
-
-| Tool | Purpose | Use Cases |
-|------|---------|-----------|
-| `filesystem` | File operations | Read/write/edit files, navigate directories |
-| `git` | Version control | Check status, diff, commit, branch operations |
-| `ripgrep` | Code search | Find patterns in files, search across codebase |
-| `shell` | Command execution | Run system commands, scripts, build tools |
-
----
-
-## filesystem
-
-File system operations with sandboxed access to allowed directories.
-
-### When to Use
-
-- Reading file contents (single or multiple files)
-- Writing or creating new files
-- Making targeted edits to existing files
-- Navigating and exploring directory structures
-- Moving, renaming, or deleting files
-
-### Available Operations
-
-| Operation | Description | Auto-Approved |
-|-----------|-------------|---------------|
-| `read_files` | Read one or more files with optional line ranges | No |
-| `write_file` | Create or overwrite a file | No |
-| `edit_file` | Make precise text replacements | No |
-| `create_directory` | Create directories (recursive) | No |
-| `list_files_in_directories` | List immediate children of directories | Yes |
-| `directory_tree` | Get recursive directory structure (folders only) | Yes |
-| `move_file` | Move or rename files/directories | No |
-| `get_file_info` | Get file metadata (size, dates, permissions) | Yes |
-| `list_allowed_directories` | Show accessible directories | Yes |
-| `delete_files` | Delete files or directories | No |
-
-### Example Usage
-
-```typescript
-// Agent that analyzes and refactors code needs filesystem access
-const agent = sdkAgent({
-  commands: {
-    analyze: sdkCommand({
-      name: 'analyze',
-      description: 'Analyze code quality',
-      available_tools: ['filesystem'],  // Read files, navigate directories
-      // ...
-    }),
-    refactor: sdkCommand({
-      name: 'refactor',
-      description: 'Refactor code',
-      available_tools: ['filesystem'],  // Read AND write files
-      // ...
-    }),
-  },
-});
-```
-
-### Key Features
-
-- **Line ranges**: Read specific portions of files with `startLine`/`endLine`, `head`, or `tail`
-- **Batch operations**: Read multiple files in one call
-- **Git-style diffs**: `edit_file` returns a diff showing changes made
-- **Safe by default**: Operations are sandboxed to allowed directories
-
----
-
-## git
-
-Git version control operations.
-
-### When to Use
-
-- Checking repository status and changes
-- Viewing diffs (staged, unstaged, between branches)
-- Staging and committing changes
-- Creating and switching branches
-- Viewing commit history
-
-### Available Operations
-
-| Operation | Description | Auto-Approved |
-|-----------|-------------|---------------|
-| `git_status` | Show working tree status | Yes |
-| `git_diff_unstaged` | Show unstaged changes | Yes |
-| `git_diff_staged` | Show staged changes | Yes |
-| `git_diff` | Diff between branches/commits | Yes |
-| `git_diff_files` | Get file contents before/after changes | Yes |
-| `git_log` | Show commit history | Yes |
-| `git_show` | Show commit contents | Yes |
-| `git_add` | Stage files | No |
-| `git_reset` | Unstage all changes | No |
-| `git_commit` | Create a commit | No |
-| `git_init` | Initialize a repository | No |
-| `git_create_branch` | Create a new branch | No |
-| `git_checkout` | Switch branches | No |
-
-### Example Usage
-
-```typescript
-// Code review agent that examines changes
-const agent = sdkAgent({
-  commands: {
-    review: sdkCommand({
-      name: 'review',
-      description: 'Review code changes',
-      available_tools: ['git', 'filesystem'],  // Read diffs AND file contents
-      // ...
-    }),
-  },
-});
-```
-
-### Key Features
-
-- **Comprehensive diffs**: View changes at file, staged, or branch level
-- **File content access**: `git_diff_files` returns full before/after content for changed files
-- **Safe reads**: All read operations are auto-approved
-- **Branch operations**: Create, checkout, and manage branches
-
----
-
-## ripgrep
-
-Fast code search using ripgrep (rg).
-
-### When to Use
-
-- Searching for patterns across a codebase
-- Finding function/class definitions
-- Locating usages of variables or imports
-- Searching with regex patterns
-- Filtering by file type
-
-### Available Operations
-
-| Operation | Description | Auto-Approved |
-|-----------|-------------|---------------|
-| `ripgrep_search` | Search for patterns in files | Yes |
-| `ripgrep_file_types` | List supported file types | Yes |
-
-### Example Usage
-
-```typescript
-// Agent that needs to find and understand code
-const agent = sdkAgent({
-  commands: {
-    findUsages: sdkCommand({
-      name: 'findUsages',
-      description: 'Find all usages of a function or variable',
-      available_tools: ['ripgrep', 'filesystem'],  // Search + read
-      // ...
-    }),
-  },
-});
-```
-
-### Search Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `pattern` | Search pattern (regex supported) | Required |
-| `fileTypes` | File extensions to search (e.g., `['ts', 'js']`) | Required |
-| `path` | Directory or file to search | `.` |
-| `caseSensitive` | Case-sensitive matching | `false` |
-| `wholeWord` | Match whole words only | `false` |
-| `fixedStrings` | Treat pattern as literal (not regex) | `false` |
-| `excludePatterns` | Patterns to exclude | `[]` |
-| `maxResults` | Maximum results to return | `100` |
-| `contextLines` | Lines of context around matches | `0` |
-| `includeHidden` | Include hidden files | `false` |
-
-### Key Features
-
-- **Fast**: Uses ripgrep for blazing-fast searches
-- **Regex support**: Full regex pattern matching
-- **File type filtering**: Required to focus searches and improve performance
-- **Context**: Optionally show surrounding lines
-
-### Tips
-
-1. **Always specify fileTypes** - This is required and improves search performance
-2. **Use `fixedStrings: true`** for literal searches with special characters
-3. **Combine with filesystem** - Search finds locations, then read for full context
-
----
-
-## shell
-
-Execute shell commands with optional sandboxing.
-
-### When to Use
-
-- Running build tools (npm, cargo, make)
-- Executing scripts
-- System commands (with appropriate permissions)
-- Any command not covered by other tools
-
-### Available Operations
-
-| Operation | Description | Auto-Approved |
-|-----------|-------------|---------------|
-| `shell_execute` | Execute a command | Depends on command |
-
-### Auto-Approved Commands
-
-These read-only commands run without user confirmation:
-
-**Unix/Linux/macOS:**
-- `ls`, `pwd`, `whoami`, `date`, `echo`
-- `cat`, `head`, `tail`, `grep`, `find`
-- `wc`, `env`, `printenv`, `which`
-- `ps`, `df`, `du`, `hostname`, `uname`, `id`, `groups`
-
-**Windows:**
-- `dir`, `echo`, `ver`, `where`, `whoami`, `hostname`
-
-### Example Usage
-
-```typescript
-// Build agent that runs npm commands
-const agent = sdkAgent({
-  commands: {
-    build: sdkCommand({
-      name: 'build',
-      description: 'Build the project',
-      available_tools: ['shell', 'filesystem'],
-      // ...
-    }),
-    test: sdkCommand({
-      name: 'test',
-      description: 'Run tests',
-      available_tools: ['shell'],
-      // ...
-    }),
-  },
-});
-```
-
-### Execute Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `command` | Command to execute | Required |
-| `args` | Command arguments array | `[]` |
-| `cwd` | Working directory | Current directory |
-| `timeout` | Timeout in milliseconds | `30000` |
-| `use_shell` | Execute through shell (enables pipes, redirects) | `false` |
-
-### Key Features
-
-- **Shell mode**: Set `use_shell: true` for piping, redirection, etc.
-- **Timeout protection**: Commands are killed after timeout
-- **Cross-platform**: Works on macOS, Linux, and Windows
-- **Optional sandboxing**: macOS supports sandbox-exec profiles
-
-### Tips
-
-1. **Prefer direct execution** (`use_shell: false`) for better security
-2. **Use `use_shell: true`** only when you need shell features (pipes, redirects)
-3. **Set appropriate timeouts** for long-running commands
-
----
-
-## Tool Combinations
-
-Common tool combinations for different tasks:
-
-### Code Analysis
-
-```typescript
-available_tools: ['filesystem', 'ripgrep']
-```
-Search for patterns, then read full file contents for context.
-
-### Code Modification
-
-```typescript
-available_tools: ['filesystem', 'git']
-```
-Read/edit files, then check status and create commits.
-
-### Full Development Workflow
-
-```typescript
-available_tools: ['filesystem', 'git', 'ripgrep', 'shell']
-```
-Complete access for complex development tasks.
-
-### Code Review
-
-```typescript
-available_tools: ['git', 'filesystem']
-```
-View diffs and read changed files for review.
-
-### Build & Test
-
-```typescript
-available_tools: ['shell', 'filesystem']
-```
-Run build commands and check output files.
-
----
-
-## Security Considerations
-
-1. **Sandboxed Access**: filesystem operations are limited to allowed directories
-2. **Auto-Approval**: Read-only operations are generally auto-approved; write operations require approval
-3. **Shell Safety**: Direct execution is preferred over shell mode for security
-4. **Timeout Protection**: All shell commands have enforced timeouts
-
----
-
-## Troubleshooting
-
-### Tool Not Available
-
-If a tool isn't working, check:
-
-1. **Tool in `available_tools`**: Ensure the tool is listed in your command config
-2. **Not in `ignore_tools`**: Make sure it's not accidentally ignored
-3. **Dependencies installed**: ripgrep requires `rg` to be installed (or `@vscode/ripgrep` package)
-
-### Permission Denied
-
-For filesystem operations:
-- Check that the path is within allowed directories
-- Use `list_allowed_directories` to see accessible paths
-
-### Shell Commands Failing
-
-- Check the command exists on the system
-- Verify the working directory exists
-- Use `use_shell: true` if you need shell features
-- Increase timeout for long-running commands