Shell & Code Execution

OrcBot provides powerful system-level execution capabilities including shell commands, TypeScript compilation, and Python virtual environments. All execution skills include safety guardrails and resource limits.

run_command

Execute shell commands on the host system.

Parameters

command

string

required

Shell command to execute. Uses PowerShell on Windows, bash/sh on Unix.

cwd

string

Working directory for command execution. Auto-extracted from cd /path && command patterns.

Return Value

output

string

Combined stdout + stderr. Capped at 8 KB with tail hint if truncated.

Platform Detection

The skill automatically adapts to the host platform:

Windows: Uses PowerShell via powershell -Command
Unix/Linux/macOS: Uses /bin/sh -c

Working Directory Auto-Extraction

The skill intelligently extracts working directory from common patterns:

# Pattern 1: cd /path && command
cd /home/user/project && npm test
# Extracted: cwd="/home/user/project", command="npm test"

# Pattern 2: cd /path ; command
cd /tmp ; ls -la
# Extracted: cwd="/tmp", command="ls -la"

Safety Features

Command allow/deny lists: Configured via commandAllowList / commandDenyList
Stdout capping: Output limited to 8 KB to prevent memory overflow
Process tree kill: Reliable termination on timeout (uses taskkill /T /F on Windows)
Safe mode enforcement: Disabled when safeMode: true

Example Usage

Run npm test:

{
  "skill": "run_command",
  "args": {
    "command": "npm test",
    "cwd": "/home/user/project"
  }
}

List directory:

{
  "skill": "run_command",
  "args": {
    "command": "ls -la /tmp"
  }
}

Git status:

{
  "skill": "run_command",
  "args": {
    "command": "cd /home/user/project && git status"
  }
}

Response Examples

Success:

$ npm test

> project@1.0.0 test
> vitest run

 ✓ src/utils.test.ts (3 tests) 24ms
 ✓ src/api.test.ts (5 tests) 31ms

 Test Files  2 passed (2)
      Tests  8 passed (8)
   Start at  10:30:00
   Duration  412ms

Error:

$ npm test
npm ERR! missing script: test

Exit code: 1

Truncated output:

$ npm run build
[... 8000 lines of webpack output ...]

[Output truncated at 8 KB. Full output saved to /tmp/command_output_12345.log]

Configuration Options

Allow specific commands:

commandAllowList:
  - npm
  - git
  - docker
  - python

Deny dangerous commands:

commandDenyList:
  - rm -rf /
  - format
  - dd if=/dev/zero

Disable all command execution:

safeMode: true

Metadata

isDeep: true - Commands are substantive work
isDangerous: true - Requires admin approval in autonomy mode

Command execution is powerful and dangerous. Always validate commands before running. Enable safeMode in production unless command execution is explicitly required.

execute_typescript

Write, compile, and execute TypeScript code on the fly.

Parameters

code

string

required

TypeScript code to compile and execute

filename

string

Optional filename to save/reuse the script. If omitted, saves to scratchpad.ts.

args

array

Command-line arguments to pass to the script

Return Value

output

string

Combined stdout + stderr from the compiled and executed JavaScript

Features

Persistent scratchpad: If filename is omitted, code is saved to a reusable scratchpad.ts
Named scripts: Provide filename to save for future reuse
Execute saved scripts: Call with only filename (no code) to re-run
TypeScript compilation: Automatically compiles to JavaScript via tsc
Full Node.js API access: Import any installed package

Example Usage

Execute TypeScript snippet:

{
  "skill": "execute_typescript",
  "args": {
    "code": "const sum = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0);\nconsole.log('Sum:', sum);"
  }
}

Save and execute:

{
  "skill": "execute_typescript",
  "args": {
    "code": "import fs from 'fs';\nconst data = fs.readFileSync('/tmp/data.json', 'utf-8');\nconsole.log(JSON.parse(data));",
    "filename": "read_data.ts"
  }
}

Re-run saved script:

{
  "skill": "execute_typescript",
  "args": {
    "filename": "read_data.ts"
  }
}

Pass arguments:

{
  "skill": "execute_typescript",
  "args": {
    "code": "const [arg1, arg2] = process.argv.slice(2);\nconsole.log('Args:', arg1, arg2);",
    "args": ["hello", "world"]
  }
}

Response Example

Sum: 15

Use Cases

Data processing: Parse CSV, JSON, or XML files
API calls: Hit undocumented endpoints with custom logic
Calculations: Complex math or statistics
Prototyping: Test algorithms before implementing as skills
One-off tasks: Tasks that don’t warrant a full skill

Metadata

isDeep: true
isDangerous: false (sandboxed to Node.js API)

Use execute_typescript for custom logic. When standard skills can’t handle a task, TypeScript execution provides unlimited flexibility without modifying the codebase.

execute_python_code

Execute Python code in an isolated virtual environment.

Parameters

code

string

required

Python code to execute

filename

string

Optional filename to save/reuse the script (e.g., "script.py")

Return Value

output

string

Combined stdout + stderr from the Python interpreter

Features

Isolated virtual environment: Uses ~/.orcbot/python-venv/
Persistent environment: Installed packages persist across runs
Auto-activation: Virtual environment activated automatically
Named scripts: Save scripts for reuse with filename
Re-execution: Call with only filename to re-run saved scripts

Example Usage

Data analysis:

{
  "skill": "execute_python_code",
  "args": {
    "code": "import pandas as pd\ndf = pd.read_csv('/tmp/data.csv')\nprint(df.describe())"
  }
}

Math calculation:

{
  "skill": "execute_python_code",
  "args": {
    "code": "import numpy as np\nresult = np.linalg.inv([[1,2],[3,4]])\nprint(result)"
  }
}

Save script:

{
  "skill": "execute_python_code",
  "args": {
    "code": "print('Hello from Python')",
    "filename": "hello.py"
  }
}

Response Example

            A          B          C
count  100.0  100.0  100.0
mean    50.5   75.3   92.1
std     28.9   15.2   10.5
min      1.0   45.0   70.0
max    100.0  105.0  115.0

Metadata

isDeep: true
isDangerous: false

Only use Python for tasks requiring Python libraries. Prefer execute_typescript for general scripting since Node.js is already available.

install_npm_dependency

Install an NPM package for use in custom skills or TypeScript execution.

Parameters

packageName

string

required

NPM package name (e.g., "axios", "lodash", "@types/node")

Return Value

result

string

npm install output

Example Usage

{
  "skill": "install_npm_dependency",
  "args": {
    "packageName": "axios"
  }
}

Response Example

$ npm install axios
added 5 packages in 2s

Metadata

isDeep: false
isDangerous: false

install_python_package

Install a Python package via pip into the isolated virtual environment.

Parameters

package

string

required

Package name (e.g., "pandas", "numpy", "requests")

Return Value

result

string

pip install output

Example Usage

{
  "skill": "install_python_package",
  "args": {
    "package": "pandas"
  }
}

Response Example

Collecting pandas
  Downloading pandas-2.1.4-cp311-cp311-linux_x86_64.whl (12.3 MB)
Installing collected packages: pandas
Successfully installed pandas-2.1.4

Metadata

isDeep: false
isDangerous: false

Install packages on-demand as needed. The virtual environment persists, so packages only need to be installed once.

get_system_info

Get platform, OS, Node version, shell, and command guidance.

Parameters

None.

Return Value

info

object

System information:

platform: OS platform (linux, darwin, win32)
arch: CPU architecture
nodeVersion: Node.js version
shell: Default shell
timestamp: Current date/time
guidance: Platform-specific command tips

Example Usage

{
  "skill": "get_system_info",
  "args": {}
}

Response Example

{
  "platform": "linux",
  "arch": "x64",
  "nodeVersion": "v20.10.0",
  "shell": "/bin/bash",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "guidance": "Use bash commands. Package manager: apt. Path separator: /"
}

Metadata

isDeep: false

system_check

Verify that commands, shared libraries, and file paths exist.

Parameters

commands

array

Command names to check (e.g., ["node", "git", "docker"])

libraries

array

Shared library names (e.g., ["libssl.so", "libcrypto.so"])

paths

array

File paths to verify (e.g., ["/etc/hosts", "/usr/bin/python3"])

Return Value

results

object

Verification results for each category with pass/fail status

Example Usage

{
  "skill": "system_check",
  "args": {
    "commands": ["node", "npm", "git"],
    "paths": ["/etc/hosts"]
  }
}

Response Example

{
  "commands": {
    "node": "found at /usr/bin/node",
    "npm": "found at /usr/bin/npm",
    "git": "found at /usr/bin/git"
  },
  "paths": {
    "/etc/hosts": "exists"
  }
}

Metadata

isDeep: false

Best Practices

Execution skill priority:

Use run_command for existing CLI tools (npm, git, docker)
Use execute_typescript for custom JavaScript/TypeScript logic
Use execute_python_code for data science (pandas, numpy) or Python-specific libs
Consider creating a custom skill for frequently-used operations

Security considerations:

Never pass untrusted user input directly to run_command
Enable commandDenyList to block dangerous operations
Set safeMode: true in production to disable command execution
Use execute_typescript / execute_python_code for sandboxed logic

Common Workflows

Git Operations

// Check git status
run_command("git status")

// Create branch and commit
run_command("cd /project && git checkout -b feature && git add . && git commit -m 'Add feature'")

NPM Project Management

// Install dependencies
run_command("npm install")

// Run tests
run_command("npm test")

// Build project
run_command("npm run build")

Data Processing Pipeline

// 1. Download data
download_file("https://example.com/data.csv")

// 2. Process with Python
execute_python_code(`
import pandas as pd
df = pd.read_csv('~/.orcbot/downloads/data.csv')
result = df.groupby('category').sum()
result.to_json('output.json')
`)

// 3. Read and deliver
read_file("output.json")
send_file(chatId, "output.json")

Troubleshooting

”Command not found”

Cause: Command not installed or not in PATH
Fix: Use system_check to verify, then install missing command or use absolute path

”Permission denied”

Cause: Insufficient file permissions
Fix: Use chmod +x or run with appropriate user permissions

”Timeout”

Cause: Command took too long
Fix: Increase timeout in config or split into smaller operations

”Output truncated”

Cause: Command output exceeded 8 KB
Fix: Redirect output to file, then read file in chunks

File Operations

Read, write, and process files

Configuration

Manage system settings

CLI Commands

Core Skills

Configuration

​Shell & Code Execution

​run_command

​Parameters

​Return Value

​Platform Detection

​Working Directory Auto-Extraction

​Safety Features

​Example Usage

​Response Examples

​Configuration Options

​Metadata

​execute_typescript

​Parameters

​Return Value

​Features

​Example Usage

​Response Example

​Use Cases

​Metadata

​execute_python_code

​Parameters

​Return Value

​Features

​Example Usage

​Response Example

​Metadata

​install_npm_dependency

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​install_python_package

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​get_system_info

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​system_check

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​Best Practices

​Common Workflows

​Git Operations

​NPM Project Management

​Data Processing Pipeline

​Troubleshooting

​”Command not found”

​”Permission denied”

​”Timeout”

​”Output truncated”

​Related Skills

File Operations

Configuration

Shell & Code Execution

run_command

Parameters

Return Value

Platform Detection

Working Directory Auto-Extraction

Safety Features

Example Usage

Response Examples

Configuration Options

Metadata

execute_typescript

Parameters

Return Value

Features

Example Usage

Response Example

Use Cases

Metadata

execute_python_code

Parameters

Return Value

Features

Example Usage

Response Example

Metadata

install_npm_dependency

Parameters

Return Value

Example Usage

Response Example

Metadata

install_python_package

Parameters

Return Value

Example Usage

Response Example

Metadata

get_system_info

Parameters

Return Value

Example Usage

Response Example

Metadata

system_check

Parameters

Return Value

Example Usage

Response Example

Metadata

Best Practices

Common Workflows

Git Operations

NPM Project Management

Data Processing Pipeline

Troubleshooting

”Command not found”

”Permission denied”

”Timeout”

”Output truncated”

Related Skills