AI Tools Reference

const result = await tools.getStatus.execute({});
// {
//   branch: "feature/auth",
//   staged: ["src/auth.ts"],
//   modified: ["src/utils.ts"],
//   untracked: ["src/new-file.ts"],
//   deleted: [],
//   hasChanges: true,
//   isClean: false
// }

const result = await tools.getDiff.execute({ staged: true });
// {
//   diffs: [{
//     file: "src/auth.ts",
//     additions: 5,
//     deletions: 2,
//     content: "--- a/src/auth.ts\n+++ b/src/auth.ts\n@@ -10,7 +10,10 @@..."
//   }],
//   totalAdditions: 5,
//   totalDeletions: 2,
//   filesChanged: 1,
//   summary: "1 file(s) changed, 5 insertion(s), 2 deletion(s)"
// }

// Stage specific files
await tools.stageFiles.execute({ files: ["src/auth.ts", "src/utils.ts"] });

// Stage all files
await tools.stageFiles.execute({ files: ["."] });

const result = await tools.createCommit.execute({
  message: "feat(auth): add token refresh logic",
  all: true
});
// {
//   success: true,
//   hash: "abc123def456789...",
//   shortHash: "abc123de",
//   branch: "feature/auth",
//   message: "[feature/auth abc123de] feat(auth): add token refresh logic",
//   filesCommitted: 2
// }

// Read entire file
const result = await tools.readFile.execute({ filePath: "src/auth.ts" });

// Read specific lines (useful for large files)
const result = await tools.readFile.execute({
  filePath: "src/auth.ts",
  startLine: 50,
  endLine: 100
});

const result = await tools.editFile.execute({
  filePath: "src/auth.ts",
  edits: [
    {
      oldText: "const token = getToken();",
      newText: "const token = await getToken();"
    },
    {
      oldText: "function validateUser(user) {",
      newText: "async function validateUser(user) {"
    }
  ],
  dryRun: true  // Preview first
});

// Package managers
'npm', 'npx', 'yarn', 'pnpm', 'bun'

// Build tools
'node', 'tsc', 'tsx', 'vite', 'webpack', 'esbuild', 'rollup'

// Testing
'jest', 'vitest', 'mocha', 'pytest', 'cargo'

// Linting
'eslint', 'prettier', 'biome', 'rustfmt', 'black', 'ruff'

// Languages
'python', 'python3', 'ruby', 'go', 'rustc'

// Utilities
'cat', 'ls', 'pwd', 'echo', 'head', 'tail', 'grep', 'find', 'wc', 'make', 'cmake'

'rm', 'rmdir', 'sudo', 'su', 'curl', 'wget', 'ssh', 'chmod', 'kill', 'eval'
// ...and other dangerous commands

const result = await tools.semanticSearch.execute({
  query: "code that validates email addresses",
  limit: 5,
  minSimilarity: 0.7,
  language: "typescript"
});
// Returns semantically relevant code, not just keyword matches

import { witTools } from 'wit/ai/tools';

// All 23 disk-based tools
const tools = witTools;
// tools.getStatus
// tools.getDiff
// tools.stageFiles
// tools.createCommit
// tools.getLog
// tools.getBranches
// tools.switchBranch
// tools.getMergeConflicts
// tools.resolveConflict
// tools.undo
// tools.search
// tools.semanticSearch
// tools.indexRepository
// tools.getIndexStatus
// tools.generatePRDescription
// tools.reviewPR
// tools.generateReleaseNotes
// tools.readFile
// tools.writeFile
// tools.editFile
// tools.listDirectory
// tools.runCommand
// tools.createBranch
// tools.openPullRequest

import { virtualTools } from 'wit/ai/tools';

// All 6 virtual filesystem tools
const tools = virtualTools;
// tools.readFile (vfs-read-file)
// tools.writeFile (vfs-write-file)
// tools.editFile (vfs-edit-file)
// tools.listDirectory (vfs-list-directory)
// tools.commit (vfs-commit)
// tools.status (vfs-status)

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const myCustomTool = createTool({
  // Unique identifier
  id: 'wit-my-custom-tool',

  // Description helps the AI understand when to use this tool
  description: `A clear description of what this tool does.
Include examples of when to use it.`,

  // Input validation with Zod
  inputSchema: z.object({
    requiredParam: z.string().describe('Description of this parameter'),
    optionalParam: z.number().optional().default(10).describe('Optional with default'),
    arrayParam: z.array(z.string()).optional().describe('Array of strings'),
  }),

  // Output schema for type safety
  outputSchema: z.object({
    success: z.boolean(),
    data: z.string().optional(),
    errorMessage: z.string().optional(),
  }),

  // The implementation
  execute: async ({ requiredParam, optionalParam, arrayParam }) => {
    try {
      // Your tool logic here
      const result = await doSomething(requiredParam, optionalParam);

      return {
        success: true,
        data: result,
      };
    } catch (error) {
      return {
        success: false,
        errorMessage: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  },
});

import { Agent } from '@mastra/core/agent';
import { witTools } from 'wit/ai/tools';
import { myCustomTool } from './my-custom-tool';

const customAgent = new Agent({
  id: 'my-custom-agent',
  name: 'Custom Agent',
  instructions: '...',
  model: 'anthropic/claude-sonnet-4-20250514',
  tools: {
    ...witTools,
    myCustomTool,
  },
});

// User: "Add input validation to the createUser function"

// Agent's internal reasoning and tool calls:

// 1. First, understand the codebase structure
const dirResult = await tools.listDirectory.execute({
  dirPath: 'src',
  recursive: true,
  pattern: '*.ts'
});
// Found: src/services/user.ts

// 2. Read the file to understand current code
const fileResult = await tools.readFile.execute({
  filePath: 'src/services/user.ts'
});
// Read 150 lines, found createUser function at line 45

// 3. Make the edit
const editResult = await tools.editFile.execute({
  filePath: 'src/services/user.ts',
  edits: [{
    oldText: `function createUser(data: UserInput) {
  const user = new User(data);`,
    newText: `function createUser(data: UserInput) {
  // Validate input
  if (!data.email || !isValidEmail(data.email)) {
    throw new ValidationError('Invalid email address');
  }
  if (!data.name || data.name.length < 2) {
    throw new ValidationError('Name must be at least 2 characters');
  }

  const user = new User(data);`
  }]
});
// Edit applied successfully

// 4. Run tests to verify
const testResult = await tools.runCommand.execute({
  command: 'npm',
  args: ['test', '--', '--grep', 'createUser']
});
// Tests passed

// 5. Stage and commit
await tools.stageFiles.execute({ files: ['src/services/user.ts'] });
await tools.createCommit.execute({
  message: 'feat(user): add input validation to createUser'
});