skydeckai/skydeckai-code

get_allowed_directory

Get the current working directory that this server is allowed to access. WHEN TO USE: When you need to understand the current workspace boundaries, determine the root directory for relative paths, or verify where file operations are permitted. Useful for commands that need to know the allowed workspace root. WHEN NOT TO USE: When you already know the current working directory or when you need to actually list files in the directory (use directory_listing instead). RETURNS: A string containing the absolute path to the current allowed working directory. This is the root directory within which all file operations must occur.

write_file

Create a new file or overwrite an existing file with new content. WHEN TO USE: When you need to save changes, create new files, or update existing ones with new content. Useful for generating reports, creating configuration files, or saving edited content. WHEN NOT TO USE: When you want to make targeted edits to parts of a file while preserving the rest (use edit_file instead), when you need to append to a file without overwriting existing content, or when you need to preserve the original file. RETURNS: A confirmation message indicating that the file was successfully written. Creates parent directories automatically if they don't exist. Use with caution as it will overwrite existing files without warning. Only works within the allowed directory. Example: Path='notes.txt', Content='Meeting notes for project X'

update_allowed_directory

Change the working directory that this server is allowed to access. WHEN TO USE: When you need to switch between different projects, change the workspace root to a different directory, or expand/modify the boundaries of allowed file operations. Useful when working with multiple projects or repositories in different locations. WHEN NOT TO USE: When you only need to create a subdirectory within the current workspace (use create_directory instead), or when you just want to list files in a different directory (use directory_listing instead). RETURNS: A confirmation message indicating that the allowed directory has been successfully updated to the new path.

create_directory

Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation. WHEN TO USE: When you need to set up project structure, organize files, create output directories before saving files, or establish a directory hierarchy. WHEN NOT TO USE: When you only want to check if a directory exists (use get_file_info instead), or when trying to create directories outside the allowed workspace. RETURNS: Text message confirming either that the directory was successfully created or that it already exists. The operation succeeds silently if the directory already exists. Only works within the allowed directory. Example: Enter 'src/components' to create nested directories.

edit_file

Make line-based edits to a text file. WHEN TO USE: When you need to make selective changes to specific parts of a file while preserving the rest of the content. Useful for modifying configuration values, updating text while maintaining file structure, or making targeted code changes. IMPORTANT: For multiple edits to the same file, use a single tool call with multiple edits in the 'edits' array rather than multiple tool calls. This is more efficient and ensures all edits are applied atomically. WHEN NOT TO USE: When you want to completely replace a file's contents (use write_file instead), when you need to create a new file (use write_file instead), or when you want to apply highly complex edits with context. RETURNS: A git-style diff showing the changes made, along with information about any failed matches. The response includes sections for failed matches (if any) and the unified diff output. Only works within the allowed directory. EXAMPLES: For a single edit: {"path": "config.js", "edits": [{"oldText": "port: 3000", "newText": "port: 8080"}]}. For multiple edits: {"path": "app.py", "edits": [{"oldText": "debug=False", "newText": "debug=True"}, {"oldText": "version='1.0'", "newText": "version='2.0'"}]}

list_directory

Get a detailed listing of files and directories in the specified path, including type, size, and modification date. WHEN TO USE: When you need to explore the contents of a directory, understand what files are available, check file sizes or modification dates, or locate specific files by name. WHEN NOT TO USE: When you need to read the contents of files (use read_file instead), when you need a recursive listing of all subdirectories (use directory_tree instead), or when searching for files by name pattern (use search_files instead). RETURNS: Text with each line containing file type ([DIR]/[FILE]), name, size (in B/KB/MB), and modification date. Only works within the allowed directory. Example: Enter 'src' to list contents of the src directory, or '.' for current directory.

read_file

Read the contents of one or more files from the file system. WHEN TO USE: When you need to examine the actual content of one or more files, view source code, check configuration files, or analyze text data. This is the primary tool for accessing file contents directly. WHEN NOT TO USE: When you only need file metadata like size or modification date (use get_file_info instead), when you need to list directory contents (use directory_listing instead). RETURNS: The complete text content of the specified file(s) or the requested portion if offset/limit are specified. Binary files or files with unknown encodings will return an error message. Each file's content is preceded by a header showing the file path (==> path/to/file <==). Handles various text encodings and provides detailed error messages if a file cannot be read. Only works within the allowed directory. Example: Use 'files: [{"path": "src/main.py"}]' to read a Python file, or add offset/limit to read specific line ranges. For multiple files, use 'files: [{"path": "file1.txt"}, {"path": "file2.txt"}]' with optional offset/limit for each file.

move_file

Move or rename a file or directory to a new location. WHEN TO USE: When you need to reorganize files or directories, rename files or folders, or move items to a different location within the allowed workspace. Useful for organizing project files, restructuring directories, or for simple renaming operations. WHEN NOT TO USE: When you want to copy a file while keeping the original (copying functionality is not available in this tool set), when destination already exists (the operation will fail), or when either source or destination is outside the allowed workspace. RETURNS: A confirmation message indicating that the file or directory was successfully moved. Parent directories of the destination will be created automatically if they don't exist. Both source and destination must be within the allowed directory. Example: source='old.txt', destination='new/path/new.txt'

copy_file

Copy a file or directory to a new location. WHEN TO USE: When you need to duplicate files or directories while keeping the original intact, create backups, or replicate configuration files for different environments. Useful for testing changes without risking original files, creating template files, or duplicating project structures. WHEN NOT TO USE: When you want to move a file without keeping the original (use move_file instead), when the destination already exists (the operation will fail), or when either source or destination is outside the allowed workspace. RETURNS: A confirmation message indicating that the file or directory was successfully copied. For directories, the entire directory structure is copied recursively. Parent directories of the destination will be created automatically if they don't exist. Both source and destination must be within the allowed directory. Example: source='config.json', destination='config.backup.json'

search_files

Search for files and directories matching a pattern in their names. WHEN TO USE: When you need to find files or directories by name pattern across a directory tree, locate files with specific extensions, or find items containing certain text in their names. Useful for locating configuration files, finding all files of a certain type, or gathering files related to a specific feature. WHEN NOT TO USE: When searching for content within files (use search_code tool for that), when you need a flat listing of a single directory (use list_directory instead), or when you need to analyze code structure (use codebase_mapper instead). RETURNS: A list of matching files and directories with their types ([FILE] or [DIR]) and relative paths. For Git repositories, only shows tracked files and directories by default. The search is recursive and case-insensitive. Only searches within the allowed directory. Example: pattern='.py' finds all Python files, pattern='test' finds all items with 'test' in the name.

delete_file

Delete a file or empty directory from the file system. WHEN TO USE: When you need to remove unwanted files, clean up temporary files, or delete empty directories. Useful for cleaning up workspaces, removing intermediate build artifacts, or deleting temporary files. WHEN NOT TO USE: When you need to delete non-empty directories (the operation will fail), when you want to move files instead of deleting them (use move_file instead), or when you need to preserve the file for later use. RETURNS: A confirmation message indicating that the file or empty directory was successfully deleted. For safety, this tool will not delete non-empty directories. Use with caution as this operation cannot be undone. Only works within the allowed directory. Example: path='old_file.txt' removes the specified file.

get_file_info

Get detailed information about a file or directory. WHEN TO USE: When you need to check file metadata like size, timestamps, permissions, or file type without reading the contents. Useful for determining when files were modified, checking file sizes, verifying file existence, or distinguishing between files and directories. WHEN NOT TO USE: When you need to read the actual content of a file (use read_file instead), or when you need to list all files in a directory (use directory_listing instead). RETURNS: Text with information about the file or directory including type (file/directory), size in bytes, creation time, modification time, access time (all in ISO 8601 format), and permissions. Only works within the allowed directory. Example: path='src/main.py' returns details about main.py

directory_tree

Get a recursive tree view of files and directories in the specified path as a JSON structure. WHEN TO USE: When you need to understand the complete structure of a directory tree, visualize the hierarchy of files and directories, or get a comprehensive overview of a project's organization. Particularly useful for large projects where you need to see nested relationships. WHEN NOT TO USE: When you only need a flat list of files in a single directory (use directory_listing instead), or when you're only interested in specific file types (use search_files instead). RETURNS: JSON structure where each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. For Git repositories, shows tracked files only. Only works within the allowed directory and only for non-hidden files, or files that are not inside hidden directory. If you want to show the hidden files also, use commands like execute_shell_script. Example: Enter '.' for current directory, or 'src' for a specific directory.

execute_code

Execute arbitrary code in various programming languages on the user's local machine within the current working directory. WHEN TO USE: When you need to run small code snippets to test functionality, compute values, process data, or demonstrate how code works. Useful for quick prototyping, data transformations, or explaining programming concepts with running examples. WHEN NOT TO USE: When you need to modify files (use write_file or edit_file instead), when running potentially harmful operations, or when you need to install external dependencies. RETURNS: Text output including stdout, stderr, and exit code of the execution. The output sections are clearly labeled with '=== stdout ===' and '=== stderr ==='. Supported languages: python, javascript, ruby, php, go, rust. Always review the code carefully before execution to prevent unintended consequences. Examples: - Python: code='print(sum(range(10)))'. - JavaScript: code='console.log(Array.from({length: 5}, (_, i) => i*2))'. - Ruby: code='puts (1..5).reduce(:+)'.

execute_shell_script

Execute a shell script (bash/sh) on the user's local machine within the current working directory. WHEN TO USE: When you need to automate system tasks, run shell commands, interact with the operating system, or perform operations that are best expressed as shell commands. Useful for file system operations, system configuration, or running system utilities. Also ideal when you need to run code linters to check for style issues or potential bugs in the codebase, or when you need to perform version control operations such as initializing git repositories, checking status, committing changes, cloning repositories, and other git commands without dedicated tools. WHEN NOT TO USE: When you need more structured programming (use execute_code instead), when you need to execute potentially dangerous system operations, or when you want to run commands outside the allowed directory. RETURNS: Text output including stdout, stderr, and exit code of the execution. The output sections are clearly labeled with '=== stdout ===' and '=== stderr ==='. This tool can execute shell commands and scripts for system automation and management tasks. It is designed to perform tasks on the user's local environment, such as opening applications, installing packages and more. Always review the script carefully before execution to prevent unintended consequences. Examples: - script='echo "Current directory:" && pwd'. - script='for i in {1..5}; do echo $i; done'. - script='eslint src/ --format stylish' (for linting). - script='git init && git add . && git commit -m "Initial commit"' (for git operations).

codebase_mapper

Build a structural map of source code files in a directory. This tool analyzes code structure to identify classes, functions, and methods. WHEN TO USE: When you need to understand the structure of a codebase, discover classes and functions across multiple files, identify inheritance relationships, or get a high-level overview of code organization without reading every file individually. WHEN NOT TO USE: When you need to search for specific text patterns (use search_files instead), when you need to analyze a single known file (use read_file instead), or when you're working with non-code files. SUPPORTED LANGUAGES: Python (.py), JavaScript (.js/.jsx), TypeScript (.ts/.tsx), Java (.java), C++ (.cpp), Ruby (.rb), Go (.go), Rust (.rs), PHP (.php), C# (.cs), Kotlin (.kt). RETURNS: A text-based tree structure showing classes and functions in the codebase, along with statistics about found elements. Only analyzes files within the allowed directory. Example: Enter '.' to analyze all source files in current directory, or 'src' to analyze all files in the src directory.

search_code

Fast content search tool using regular expressions. WHEN TO USE: When you need to search for specific patterns within file contents across a codebase. Useful for finding function definitions, variable usages, import statements, or any text pattern in source code files. WHEN NOT TO USE: When you need to find files by name (use search_files instead), when you need semantic code understanding (use codebase_mapper instead), or when analyzing individual file structure. RETURNS: Lines of code matching the specified patterns, grouped by file with line numbers. Results are sorted by file modification time with newest files first. Respects file filtering and ignores binary files. Search is restricted to the allowed directory.

batch_tools

Execute multiple tool invocations in parallel or serially. WHEN TO USE: When you need to run multiple operations efficiently in a single request, combine related operations, or gather results from different tools. Useful for bulk operations, coordinated tasks, or performing multiple queries simultaneously. WHEN NOT TO USE: When operations need to be performed strictly in sequence where each step depends on the previous step's result, when performing simple operations that don't benefit from batching, or when you need fine-grained error handling. RETURNS: Results from all tool invocations grouped together. Each result includes the tool name and its output. If any individual tool fails, its error is included but other tools continue execution. Parallelizable tools are executed concurrently for performance. Each tool's output is presented in a structured format along with the description you provided. IMPORTANT NOTE: All tools in the batch execute in the same working directory context. If a tool creates a directory and a subsequent tool needs to work inside that directory, you must either use paths relative to the current working directory or include an explicit tool invocation to change directories (e.g., update_allowed_directory).

think

Use the tool to methodically think through a complex problem step-by-step. WHEN TO USE: When tackling complex reasoning tasks that benefit from breaking down problems, exploring multiple perspectives, or reasoning through chains of consequences. Ideal for planning system architecture, debugging complex issues, anticipating edge cases, weighing tradeoffs, or making implementation decisions. WHEN NOT TO USE: For simple explanations, direct code writing, retrieving information, or when immediate action is needed. RETURNS: Your structured thinking process formatted as markdown. This tool helps you methodically document your reasoning without making repository changes. Structuring your thoughts with this tool can lead to more reliable reasoning and better decision-making, especially for complex problems where it's easy to overlook important considerations.

capture_screenshot

Capture a screenshot of the current screen and save it to a file. This tool allows capturing the entire screen, the active window, or a specific named window. The screenshot will be saved to the specified output path or to a default location if not provided. WHEN TO USE: When you need to visually document what's on screen, capture a specific application window, create visual references for troubleshooting, or gather visual information about the user's environment. Useful for documenting issues, creating tutorials, or assisting with visual tasks. WHEN NOT TO USE: When you need information about windows without capturing them (use get_available_windows instead). RETURNS: A JSON object containing success status, file path where the screenshot was saved, and a message. On failure, includes a detailed error message. If debug mode is enabled, also includes debug information about the attempted capture. Windows can be captured in the background without bringing them to the front. Works on macOS, Windows, and Linux with platform-specific implementations.

get_active_apps

Get a list of currently active applications running on the user's system. WHEN TO USE: When you need to understand what software the user is currently working with, gain context about their active applications, provide application-specific assistance, or troubleshoot issues related to running programs. Especially useful for providing targeted help based on what the user is actively using. WHEN NOT TO USE: When you need information about specific windows rather than applications (use get_available_windows instead), when you need a screenshot of what's on screen (use capture_screenshot instead), or when application context isn't relevant to the task at hand. RETURNS: JSON object containing platform information, success status, count of applications, and an array of application objects. Each application object includes name, has_windows flag, and when details are requested, information about visible windows. Works on macOS, Windows, and Linux, with platform-specific implementation details.

get_available_windows

Get detailed information about all available windows currently displayed on the user's screen. WHEN TO USE: When you need to know exactly what windows are visible to the user, find a specific window by title, provide guidance related to something the user is viewing, or need window-level context that's more detailed than application-level information. Useful for referencing specific content the user can see on their screen. WHEN NOT TO USE: When application-level information is sufficient (use get_active_apps instead), when you need to capture what's on screen (use capture_screenshot instead), or when window context isn't relevant to the task at hand. RETURNS: JSON object containing platform information, success status, count of windows, and an array of window objects. Each window object includes title, application owner, visibility status, and platform-specific details like window IDs. Works on macOS, Windows, and Linux, with platform-specific implementation details.

read_image_file

Read an image file from the file system and return its contents as a base64-encoded string. WHEN TO USE: When you need to view or process image files, include images in responses, analyze image content, or convert images to a format that can be transmitted as text. Useful for examining screenshots, diagrams, photos, or any visual content stored in the file system. WHEN NOT TO USE: When you only need information about the image file without its contents (use get_file_info instead), when working with extremely large images (over 100MB), or when you need to read text files (use read_file instead). RETURNS: A base64-encoded data URI string prefixed with the appropriate MIME type (e.g., 'data:image/png;base64,...'). Images that are very small or very large will be automatically resized to between 20-800 pixels wide while maintaining aspect ratio. This tool supports common image formats like PNG, JPEG, GIF, and WebP. Only works within the allowed directory.

web_fetch

Fetches content from a URL. WHEN TO USE: When you need to retrieve data from web APIs, download documentation, check external resources, or gather information from websites. Useful for getting real-time data, documentation, or referencing external content. WHEN NOT TO USE: When you need to interact with complex websites requiring authentication or session management, when the data needs to be processed in a specific format not supported, or when you need to make authenticated API calls with OAuth. TIP: Use 'web_search' first to find relevant URLs, then use this tool to fetch detailed content. RETURNS: The content of the URL as text. For HTML pages, returns the raw HTML content. For JSON endpoints, returns the JSON content as a string. Successful response includes HTTP status code. Failed requests include error details. Maximum request size enforced for safety.

web_search

Performs a web search and returns the search results. WHEN TO USE: When you need to find information on the web, get up-to-date data, or research a topic. This provides more current information than your training data. WHEN NOT TO USE: For queries requiring complex authentication, accessing private data, or when you want to browse interactive websites. TIP: For best results, use this tool to find relevant URLs, then use 'web_fetch' to get the full content of specific pages. RETURNS: A list of search results including titles, URLs, and snippets for each result.

get_system_info

Get detailed system information about the host computer. WHEN TO USE: When you need to understand the system environment, diagnose performance issues, verify hardware specifications, check resource availability, or determine the operating environment for compatibility reasons. Useful for system analysis, troubleshooting, environment verification, and providing context-aware assistance. WHEN NOT TO USE: When you only need the current working directory (use get_allowed_directory instead), when specific file information is needed (use get_file_info instead), or when you need to interact with applications rather than system information (use get_active_apps instead). RETURNS: A JSON object containing comprehensive system details including: working directory path, OS details (name, version, architecture), Python version, WiFi network name, CPU information (cores, usage), memory statistics (total, available, usage percentage), disk information (total, free, usage percentage), and on macOS, additional hardware details (model, chip, serial number).

todo_read

Read the current task list from the workspace-specific todo storage. MANDATORY: This tool MUST be called FIRST before ANY workspace operations including file reads, code analysis, development tasks, project creation, or directory manipulation. WORKSPACE-FIRST RULE: Every LLM interaction with workspaces, directories, projects, or repositories requires todo management. WHEN TO USE: Always when starting workspace operations - check task status, review pending/completed work, understand project context, pick up previous progress. Essential for: Project initialization, code development, file operations, debugging, testing, deployment, refactoring. WHEN NOT TO USE: Pure informational queries unrelated to workspace development. RETURNS: Sequential task list with status and metadata. Tasks execute in order - no priority system. Each workspace maintains isolated todo lists for project organization. CRITICAL: Bypassing this tool for workspace operations violates mandatory protocol. EXAMPLES:

• Creating new projects: Read todos to check existing project structure tasks
• Code development: Check current development phase and next sequential steps
• File modifications: Understand task context before making changes
• Project analysis: Review completed analysis and next investigation steps

todo_write

Update the entire task list (complete replacement) for the current workspace. MANDATORY: This tool MUST be called when planning, adding, or reorganizing tasks during ANY workspace operations. WORKSPACE-FIRST RULE: All workspace development requires structured task management through sequential execution. WHEN TO USE: Task planning for new projects, adding development phases, reorganizing workflow, batch status updates. Sequential execution model: Tasks are completed in order, building upon previous work. No priority system - order determines execution. Essential for: Project planning, development workflows, feature implementation, debugging sequences, deployment phases. WHEN NOT TO USE: Single task updates (use todo_update), pure reading (use todo_read). RETURNS: Success status and task count. Enforces sequential execution (only one in-progress task). CRITICAL: Sequential task management is mandatory for all workspace development activities. EXAMPLES:

• New project setup: Create sequential tasks for initialization, structure, dependencies
• Feature development: Plan design, implementation, testing, documentation phases
• Bug fixing: Create investigation, fix, test, validation sequence
• Code refactoring: Plan analysis, changes, testing, cleanup steps

todo_update

Update a specific todo item by ID for sequential workflow management. MANDATORY: This tool MUST be called when progressing through tasks during workspace operations. WORKSPACE-FIRST RULE: Task progress updates are required for all workspace development activities. WHEN TO USE: Mark tasks in-progress when starting, completed when finished, update content for clarification. Sequential workflow: Progress through tasks in order, maintaining single active task constraint. Essential for: Task status transitions, progress tracking, workflow advancement, content updates. WHEN NOT TO USE: Multiple task updates (use todo_write), adding new tasks (use todo_write). RETURNS: Updated todo with status counts showing workflow progress. Enforces sequential execution - only one task can be in-progress at any time. CRITICAL: Sequential progress tracking is mandatory for workspace development workflows. EXAMPLES:

• Starting work: Update task from 'pending' to 'in_progress'
• Completing work: Update task from 'in_progress' to 'completed'
• Task refinement: Update content for better clarity
• Workflow progression: Move to next sequential task