File system and command execution tools for Ellie agents
npm install @ellie-ai/agent-fs-tools-pluginFile system and command execution tools for Ellie agents.
This plugin provides agents with the ability to:
- Read files - Read file contents in UTF-8 or base64 encoding
- Write files - Create or overwrite files with content
- Edit files - Make precise string replacements in files
- Execute commands - Run shell commands via bash
- Find files - Use glob patterns to locate files
- Search content - Search file contents with regex patterns
``bash`
bun add @ellie-ai/agent-fs-tools-plugin
`typescript
import { createRuntime } from "@ellie-ai/runtime";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import { fsToolsPlugin } from "@ellie-ai/agent-fs-tools-plugin";
import { openAI } from "@ellie-ai/model-providers";
const runtime = createRuntime({
plugins: [
agentPlugin({
model: openAI(),
toolPlugins: [fsToolsPlugin()],
}),
],
});
`
Read file contents from the file system.
Parameters:
- path (string, required): Absolute or relative file pathencoding
- (string, optional): "utf8" (default) or "base64"
Example:
`json`
{
"path": "/path/to/file.txt",
"encoding": "utf8"
}
Create or overwrite a file with content.
Parameters:
- path (string, required): File path to write tocontent
- (string, required): Content to writeencoding
- (string, optional): "utf8" (default) or "base64"
Example:
`json`
{
"path": "/path/to/file.txt",
"content": "Hello world"
}
Make precise edits by replacing old_string with new_string.
Parameters:
- path (string, required): File path to editold_string
- (string, required): Exact text to findnew_string
- (string, required): Text to replace withreplace_all
- (boolean, optional): Replace all occurrences (default: false)
Example:
`json`
{
"path": "/path/to/file.txt",
"old_string": "Hello",
"new_string": "Hi",
"replace_all": true
}
Execute shell commands.
Parameters:
- command (string, required): Shell command to executecwd
- (string, optional): Working directorytimeout
- (number, optional): Timeout in milliseconds (default: 30000)
Example:
`json`
{
"command": "ls -la",
"cwd": "/tmp"
}
Returns: JSON with exitCode, stdout, and stderr
Find files matching a pattern.
Parameters:
- pattern (string, required): Glob pattern (e.g., "*/.ts")cwd
- (string, optional): Directory to search in
Example:
`json`
{
"pattern": "src/*/.ts",
"cwd": "/path/to/project"
}
Returns: JSON array of matching file paths, sorted by modification time
Search file contents with regex.
Parameters:
- pattern (string, required): Regular expression patternpath
- (string, optional): File or directory to search inglob
- (string, optional): File filter pattern (default: "*/")context
- (number, optional): Number of context lines (default: 0)
Example:
`json`
{
"pattern": "function.*test",
"path": "/path/to/project",
"glob": "*/.ts",
"context": 2
}
`typescript`
fsToolsPlugin({
tools: {
read: true,
write: true,
edit: true,
bash: true,
glob: true,
grep: false, // Disable grep tool
},
});
Restrict which paths and commands agents can access:
`typescript
fsToolsPlugin({
permissions: {
// Allow access to specific paths (glob patterns)
allowedPaths: ["/tmp/", "/home/user/projects/"],
// Deny access to specific paths (takes precedence)
deniedPaths: ["/etc/", "/home/user/.ssh/"],
// Restrict bash commands to specific prefixes
allowedCommands: ["ls", "cat", "grep", "find"],
// Maximum file size for read operations (in bytes)
maxFileSize: 1024 * 1024, // 1MB
},
});
`
Allow only project directory:
`typescript`
fsToolsPlugin({
permissions: {
allowedPaths: ["/home/user/my-project/**"],
},
});
Deny sensitive files:
`typescript`
fsToolsPlugin({
permissions: {
deniedPaths: [
"/etc/**",
"/home/user/.ssh/**",
"/home/user/.aws/**",
"**/.env",
],
},
});
Restrict bash to read-only commands:
`typescript`
fsToolsPlugin({
permissions: {
allowedCommands: ["ls", "cat", "grep", "find", "head", "tail"],
},
});
⚠️ File System Access: This plugin gives agents full file system access by default. Always configure permissions in production environments.
⚠️ Command Execution: The bash tool can execute arbitrary commands. Consider:allowedCommands
- Disabling bash entirely in untrusted environments
- Using to restrict to safe read-only commands
- Running agents in sandboxed environments
⚠️ Path Traversal: Permission checks use glob patterns. Test your patterns carefully to avoid unintended access.
`typescript``
fsToolsPlugin({
tools: {
bash: false, // Disable command execution
},
permissions: {
allowedPaths: ["/var/app/data/", "/tmp/agent-workspace/"],
deniedPaths: ["/.env", "/.git/", "/node_modules/**"],
maxFileSize: 10 1024 1024, // 10MB limit
},
});
MIT