Skip to content

Available Tools

Jump to bottom
andershsueh edited this page Feb 10, 2026 · 2 revisions

Available Tools

📖 Languages: English only | 中文翻译征集中 | 日本語翻訳募集中

Complete reference for all 7 builtin tools in ALICE.

📄 readFile

Read the contents of a file.

Parameters

Parameter Type Required Description
path string ✅ File path (relative or absolute)
encoding string ❌ File encoding (default: utf-8)

Supported Encodings

  • utf-8 / utf8 (default)
  • ascii
  • base64

Examples

# Simple file read
> You: What's in package.json?
[📄 readFile] Reading package.json...
[✅ readFile] Success (1024 bytes)

# Specific file with path
> You: Show me the README
[📄 readFile] Reading README.md...
[✅ readFile] Success (5000 bytes)

Return Data

{
  "success": true,
  "data": {
    "path": "package.json",
    "content": "{ \"name\": \"alice-cli\" ... }",
    "size": 1024,
    "encoding": "utf-8"
  }
}

Errors

  • File not found
  • Permission denied
  • Invalid encoding

📁 listFiles

List files and directories in a directory.

Parameters

Parameter Type Required Description
directory string ❌ Directory path (default: .)
detailed boolean ❌ Include size & timestamps (default: false)

Examples

# List current directory
> You: What files are here?
[📁 listFiles] Scanning .
[✅ listFiles] Found 23 items (16 files, 7 directories)

# List specific directory with details
> You: Show me files in src/ with details
[📁 listFiles] Scanning src/ with details
[✅ listFiles] Complete

Return Data

{
  "success": true,
  "data": {
    "directory": ".",
    "total": 23,
    "files": 16,
    "directories": 7,
    "items": [
      {
        "name": "package.json",
        "type": "file",
        "size": 1024,        // if detailed=true
        "modified": "2026-02-10T12:00:00Z"  // if detailed=true
      },
      {
        "name": "src",
        "type": "directory"
      }
    ]
  }
}

🔍 searchFiles

Search for files using glob patterns.

Parameters

Parameter Type Required Description
pattern string ✅ Glob pattern (e.g., **/*.ts)
directory string ❌ Search root (default: .)
ignore string[] ❌ Patterns to ignore

Glob Pattern Examples

  • *.js - All JS files in current directory
  • **/*.ts - All TS files recursively
  • src/**/*.tsx - All TSX files in src/
  • **/*.{js,ts} - All JS and TS files
  • !**/node_modules/** - Exclude node_modules

Default Ignore Patterns

Automatically ignored:

  • node_modules/**
  • .git/**
  • dist/**

Examples

# Find TypeScript files
> You: How many TypeScript files are there?
[🔍 searchFiles] Searching **/*.ts
[✅ searchFiles] Found 25 files

# Find in specific directory
> You: Find all markdown files in docs/
[🔍 searchFiles] Searching docs/**/*.md
[✅ searchFiles] Found 8 files

Return Data

{
  "success": true,
  "data": {
    "pattern": "**/*.ts",
    "directory": ".",
    "count": 25,
    "files": [
      "src/index.ts",
      "src/core/llm.ts",
      ...
    ]
  }
}

📂 getCurrentDirectory

Get the current working directory.

Parameters

None.

Examples

> You: Where am I?
[📂 getCurrentDirectory] Getting current directory
[✅ getCurrentDirectory] Success

Alice: You're in D:\projects\Alice
Platform: Windows (win32)

Return Data

{
  "success": true,
  "data": {
    "path": "D:\\projects\\Alice",
    "platform": "win32"  // or "darwin" (macOS) or "linux"
  }
}

🌿 getGitInfo

Get information about the Git repository.

Parameters

Parameter Type Required Description
directory string ❌ Git repo path (default: .)

Examples

> You: What branch am I on?
[🌿 getGitInfo] Fetching Git information
[✅ getGitInfo] Success

Alice: You're on the "master" branch.
You have 3 uncommitted changes.

> You: Show me recent commits
[🌿 getGitInfo] Fetching Git information
[✅ getGitInfo] Success

Alice: Recent commits:
- eba23ee: docs: add v0.2.0 release notes (2 hours ago)
- a65ad43: chore: prepare for v0.2.0 release (3 hours ago)

Return Data

{
  "success": true,
  "data": {
    "currentBranch": "master",
    "branches": ["master", "develop", "feature/tools"],
    "status": {
      "modified": ["src/cli/app.tsx"],
      "created": ["src/tools/newTool.ts"],
      "deleted": [],
      "staged": ["README.md"],
      "ahead": 2,
      "behind": 0
    },
    "remotes": [
      {
        "name": "origin",
        "url": "https://github.com/AndersHsueh/Alice.git"
      }
    ],
    "recentCommits": [
      {
        "hash": "eba23ee",
        "message": "docs: add v0.2.0 release notes",
        "author": "Anders",
        "date": "2026-02-10T12:00:00Z"
      }
    ]
  }
}

Errors

  • Not a Git repository
  • Git not installed

⏰ getCurrentDateTime

Get the current date and time with timezone information.

Parameters

None.

Examples

> You: What time is it?
[⏰ getCurrentDateTime] Getting current time
[✅ getCurrentDateTime] Success

Alice: It's currently 10:15 PM, Tuesday, February 10, 2026.
Timezone: Asia/Shanghai (UTC+8)

> You: What's today's date?
[⏰ getCurrentDateTime] Getting current time
[✅ getCurrentDateTime] Success

Alice: Today is February 10, 2026, Tuesday.

Return Data

{
  "success": true,
  "data": {
    "iso8601": "2026-02-10T14:15:30.123Z",
    "local": "2026/2/10 22:15:30",
    "unix": 1770730530,
    "timezone": "Asia/Shanghai",
    "platform": "win32",
    "date": {
      "year": 2026,
      "month": 2,
      "day": 10,
      "weekday": "星期二"
    },
    "time": {
      "hour": 22,
      "minute": 15,
      "second": 30
    }
  }
}

🔧 executeCommand

Execute system shell commands.

⚠️ WARNING: This tool can make system changes. Dangerous commands require user confirmation.

Parameters

Parameter Type Required Description
command string ✅ Command to execute
cwd string ❌ Working directory (default: current)
timeout number ❌ Timeout in ms (default: 30000)

Dangerous Command Detection

The following patterns trigger confirmation:

  • rm -rf / del /s - Recursive deletion
  • format - Disk formatting
  • dd if= - Direct disk operations
  • shutdown / reboot - System power
  • mkfs - Filesystem formatting
  • Fork bombs and similar

Examples

Safe Command (No Confirmation)

> You: Show me the current directory listing

[🔧 executeCommand] Executing: ls -la
[✅ executeCommand] Command completed

Alice: Here's the directory listing:
total 156
drwxr-xr-x  10 user  staff    320 Feb 10 22:15 .
drwxr-xr-x  20 user  staff    640 Feb 10 12:00 ..
-rw-r--r--   1 user  staff   1024 Feb 10 22:15 package.json
...

Dangerous Command (Requires Confirmation)

> You: Delete the node_modules folder

[🔧 executeCommand] Preparing: rm -rf node_modules

┌─────────────────────────────────────┐
│ ⚠️  Dangerous Command Warning        │
│                                     │
│ Command: rm -rf node_modules        │
│                                     │
│ This command may cause data loss.   │
│                                     │
│ Confirm execution? (y/N): y         │
│                                     │
│ Tip: Set "dangerous_cmd": false     │
│ in settings to skip confirmation    │
└─────────────────────────────────────┘

[🔧 executeCommand] Executing...
[✅ executeCommand] Command completed

Alice: node_modules has been deleted.
Run 'npm install' to reinstall dependencies.

Platform-Specific Execution

Platform Shell Example
Windows PowerShell Get-ChildItem
macOS Bash ls -la
Linux Bash ls -la

Return Data

{
  "success": true,
  "data": {
    "command": "ls -la",
    "stdout": "total 156\ndrwxr-xr-x ...",
    "stderr": "",
    "exitCode": 0,
    "platform": "darwin"
  }
}

Errors

  • Command not found
  • Permission denied
  • Timeout (> 30 seconds)
  • Exit code non-zero

Safety Features

  1. Confirmation Dialog - Required for dangerous commands
  2. Timeout Protection - Max 30 seconds
  3. Platform Detection - Uses appropriate shell
  4. Error Handling - Captures and reports errors
  5. Configurable - Can disable confirmations

Configuration

{
  // Skip dangerous command confirmation
  "dangerous_cmd": false
}

Learn more about dangerous commands →

Tool Comparison

Tool Read Write Search Execute
readFile ✅ ❌ ❌ ❌
listFiles ✅ ❌ ❌ ❌
searchFiles ✅ ❌ ✅ ❌
getCurrentDirectory ✅ ❌ ❌ ❌
getGitInfo ✅ ❌ ❌ ❌
getCurrentDateTime ✅ ❌ ❌ ❌
executeCommand ✅ ✅ ✅ ✅

See Also

Clone this wiki locally