read_terminal_output

Instructions

Implementation Reference

• src/index.ts:95-105 (handler)

  The handler function for the 'read_terminal_output' tool. It reads the 'linesOfOutput' argument, calls TtyOutputReader.call() with it, and returns the terminal output as text content.

  case "read_terminal_output": {
    const linesOfOutput = Number(request.params.arguments?.linesOfOutput) || 25
    const output = await TtyOutputReader.call(linesOfOutput)
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/TtyOutputReader.ts:1-32 (helper)

  The TtyOutputReader class with the 'call' method that retrieves terminal output by fetching the full buffer via AppleScript and optionally slicing to the requested number of lines.

  import { exec } from 'node:child_process';
  import { promisify } from 'node:util';
  
  const execPromise = promisify(exec);
  
  export default class TtyOutputReader {
    static async call(linesOfOutput?: number) {
      const buffer = await this.retrieveBuffer();
      if (!linesOfOutput) {
        return buffer;
      }
      const lines = buffer.split('\n');
      return lines.slice(-linesOfOutput - 1).join('\n');
    }
  
    static async retrieveBuffer(): Promise<string> {
      const ascript = `
        tell application "iTerm2"
          tell front window
            tell current session of current tab
              set numRows to number of rows
              set allContent to contents
              return allContent
            end tell
          end tell
        end tell
      `;
      
      const { stdout: finalContent } = await execPromise(`osascript -e '${ascript}'`);
      return finalContent.trim();
    }
  }

• src/index.ts:42-54 (schema)

  Schema/registration definition for the 'read_terminal_output' tool, including its description, input schema with 'linesOfOutput' (integer), and that it is required.

  {
    name: "read_terminal_output",
    description: "Reads the output from the active iTerm terminal",
    inputSchema: {
      type: "object",
      properties: {
        linesOfOutput: {
          type: "integer",
          description: "The number of lines of output to read."
        },
      },
      required: ["linesOfOutput"]
    }

• src/index.ts:25-71 (registration)

  The tool registration via ListToolsRequestSchema handler, where 'read_terminal_output' is listed among the available tools.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "write_to_terminal",
          description: "Writes text to the active iTerm terminal - often used to run a command in the terminal",
          inputSchema: {
            type: "object",
            properties: {
              command: {
                type: "string",
                description: "The command to run or text to write to the terminal"
              },
            },
            required: ["command"]
          }
        },
        {
          name: "read_terminal_output",
          description: "Reads the output from the active iTerm terminal",
          inputSchema: {
            type: "object",
            properties: {
              linesOfOutput: {
                type: "integer",
                description: "The number of lines of output to read."
              },
            },
            required: ["linesOfOutput"]
          }
        },
        {
          name: "send_control_character",
          description: "Sends a control character to the active iTerm terminal (e.g., Control-C, or special sequences like ']' for telnet escape)",
          inputSchema: {
            type: "object",
            properties: {
              letter: {
                type: "string",
                description: "The letter corresponding to the control character (e.g., 'C' for Control-C, ']' for telnet escape)"
              },
            },
            required: ["letter"]
          }
        }
      ]
    };