src — interpreter

Module: src-interpreter Cohesion: 0.80 Members: 0

src — interpreter

The src/interpreter module serves as the central intelligence and control unit for Code Buddy, enabling the AI to understand, reason, and interact with the host computer and external services. Inspired by the Open Interpreter project, it provides a robust framework for managing AI conversations, executing tasks, adhering to safety protocols, and tracking resource usage.

Purpose

The primary goal of the interpreter module is to:

  1. Orchestrate AI Interactions: Manage the flow of conversation between the user and the AI, processing messages, generating responses, and executing actions.
  2. Provide Computer Capabilities: Offer a structured and safe interface for the AI to perform operations on the local machine (file system, OS commands, web browsing) and leverage external tools (skills, LLMs).
  3. Manage AI Behavior: Allow configuration of the AI's personality, capabilities, and safety settings through a profile system.
  4. Ensure Safety and Budget: Implement mechanisms for user approval of actions and track token usage and cost to prevent unintended consequences or overspending.

Core Concepts

Before diving into the components, understanding these core concepts is crucial:

Architecture Overview

The InterpreterService acts as the central hub, orchestrating interactions between the user, the underlying Large Language Model (LLM), and the Computer module. It uses InterpreterProfile configurations to guide its behavior and delegates specific tasks to specialized sub-modules. 

graph TD
    A[User Interaction] --> B(InterpreterService)
    B -- Configured by --> C(InterpreterProfile)
    B -- Sends messages to --> D(LLMClient)
    D -- Generates Tool Calls / Responses --> B
    B -- Executes via --> E(Computer Module)
    E -- Delegates to --> F(ComputerBrowser)
    E -- Delegates to --> G(ComputerFiles)
    E -- Delegates to --> H(ComputerOS)
    E -- Delegates to --> I(ComputerSkills)
    I -- Can use --> D
    F -- External Web --> J(Internet)
    G -- Local FS --> K(Filesystem)
    H -- OS Commands --> L(Operating System)

Key Components

The src/interpreter module is composed of several interconnected classes and files:

1. InterpreterService (src/interpreter/interpreter-service.ts)

This is the core class that manages the AI's conversational state, profile, budget, and the execution of actions. It's the primary interface for interacting with the Code Buddy AI.

Key Responsibilities:

Execution Flow for chat():

  1. Checks if already processing or if budget is exceeded.
  2. Adds the user message to conversationHistory.
  3. Constructs a message payload for the LLM, including system prompts (from profile/custom instructions) and a slice of recent conversation history.
  4. Calls the CodeBuddyClient.chat() method with the constructed messages and model parameters from the active profile.
  5. Parses the LLM's response, extracts content, token usage, cost, and any tool calls.
  6. Updates internal tokenUsage and totalCost statistics, and checks budgetStatus.
  7. Adds the assistant's response (including tool calls/results) to conversationHistory.
  8. Returns the ChatResult.

2. Computer Module (src/interpreter/computer/index.ts)

This module provides a unified, high-level interface for the AI to interact with the host computer's environment. It aggregates several specialized sub-modules, each handling a distinct domain of computer interaction.

The computer object (or getComputer() singleton) provides access to these capabilities:

2.1. ComputerBrowser (src/interpreter/computer/browser.ts)

Enables the AI to perform web searches and fetch web page content without requiring a visible browser window.

Key Methods:

2.2. ComputerFiles (src/interpreter/computer/files.ts)

Provides a comprehensive API for interacting with the local file system, abstracting away raw Node.js fs operations.

Key Methods:

2.3. ComputerOS (src/interpreter/computer/os.ts)

Provides capabilities for interacting with the operating system, including clipboard, processes, and system information. It handles platform-specific commands for macOS, Linux, and Windows.

Key Methods:

2.4. ComputerSkills (src/interpreter/computer/skills.ts)

Manages a library of reusable automations or "skills" that the AI can discover, run, and even create. Skills are defined as structured JSON/YAML files containing a sequence of steps.

Key Methods:

3. Interpreter Profiles (src/interpreter/profiles.ts)

This file defines a collection of predefined InterpreterProfile objects, each tailored for a specific use case or AI behavior. These profiles are used by InterpreterService to quickly configure the AI.

Built-in Profiles:

Profile Configuration:

Each profile specifies:

Utilities:

4. Interpreter Types (src/interpreter/types.ts)

This file centralizes all TypeScript interfaces and types used across the interpreter module, ensuring consistency and clarity.

Key Types Defined:

Integration Points

The interpreter module integrates with several other parts of the Code Buddy codebase:

Usage Examples

The interpreter module is designed to be easily accessible through singleton instances: 

import { interpreter, computer } from './interpreter'; class="hl-cmt">// Or from the main entry point

async function demonstrateInterpreter() {
  class="hl-cmt">// --- Interpreter Service Usage ---

  class="hl-cmt">// Load a specific profile
  interpreter.loadProfile('coding');
  console.log(`Active profile: ${interpreter.profile.name}`);

  class="hl-cmt">// Configure interpreter settings
  interpreter.autoRun = true;
  interpreter.safeMode = 'ask'; class="hl-cmt">// Will ask for approval for actions
  interpreter.maxBudget = 5.00;
  interpreter.customInstructions = 'Always use TypeScript for code examples.';

  class="hl-cmt">// Send a message to the AI
  console.log('\n--- Chatting with Interpreter ---');
  const chatResult = await interpreter.chat('Write a simple Node.js script to list files in the current directory.');
  console.log('AI Response:', chatResult.content);
  console.log('Token Usage:', interpreter.tokenUsage);
  console.log('Total Cost:', interpreter.totalCost.toFixed(4));

  class="hl-cmt">// If there are pending approvals (due to safeMode: 'ask'), you can approve them
  const pending = interpreter.getPendingApprovals();
  if (pending.length > 0) {
    console('\n--- Approving pending action ---');
    console.log('Pending action:', pending[0].description);
    class="hl-cmt">// await interpreter.approve(pending[0].id);
    class="hl-cmt">// console.log('Action approved and executed.');
  }

  class="hl-cmt">// Reset conversation and usage
  interpreter.reset();
  interpreter.resetUsage();
  console.log('\nInterpreter reset and usage cleared.');

  class="hl-cmt">// --- Computer Module Usage ---

  console.log('\n--- Using Computer Capabilities ---');

  class="hl-cmt">// Web Search
  const searchResults = await computer.browser.search('TypeScript best practices', { numResults: 3 });
  console.log('Web Search Results:', searchResults.map(r => r.title));

  class="hl-cmt">// File Operations
  const tempFilePath = 'temp_test_file.txt';
  await computer.files.write(tempFilePath, 'Hello, Code Buddy!');
  const fileContent = await computer.files.read(tempFilePath);
  console.log(`File content of ${tempFilePath}: "${fileContent}"`);
  const fileInfo = await computer.files.info(tempFilePath);
  console.log('File Info:', fileInfo.name, fileInfo.size, fileInfo.isFile);
  await computer.files.delete(tempFilePath);

  class="hl-cmt">// OS Operations
  const systemInfo = computer.os.getSystemInfo();
  console.log('OS Platform:', systemInfo.platform);
  console.log('Current User:', computer.os.getUsername());
  class="hl-cmt">// await computer.os.notify('Code Buddy', 'Hello from the interpreter!');

  class="hl-cmt">// Skills Execution
  console.log('\n--- Running a Skill ---');
  const skillResult = await computer.skills.run('llm-ask', { prompt: 'What is the capital of Canada?' });
  console.log('Skill "llm-ask" Output:', (skillResult.output as any)?.content);
}

demonstrateInterpreter().catch(console.error);