Files of the working copy

read_file

Reads a file as text, whole or by lines. Says how many lines it has and whether the answer was cut. A file too large to read whole is read by lines.

read-only · every call adds · stays on this machine.

Parameter Type Required Default Description
path string yes — Path of the file, absolute or relative to the session's root.
from integer? — null First line to return, counting from one; omit for the start of the file.
to integer? — null Last line to return; omit for the end of the file.
JSON Schema
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Path of the file, absolute or relative to the session\u0027s root.",
      "type": "string"
    },
    "from": {
      "description": "First line to return, counting from one; omit for the start of the file.",
      "type": [
        "integer",
        "null"
      ],
      "default": null
    },
    "to": {
      "description": "Last line to return; omit for the end of the file.",
      "type": [
        "integer",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "path"
  ]
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "path": {
          "description": "The file, relative to the session\u0027s root.",
          "type": "string"
        },
        "from": {
          "description": "The first line given, counted from 1.",
          "type": "integer"
        },
        "to": {
          "description": "The last line given.",
          "type": "integer"
        },
        "lines": {
          "description": "How many lines the file has.",
          "type": "integer"
        },
        "text": {
          "description": "The lines from..to, joined by line ends.",
          "type": "string"
        },
        "isCut": {
          "description": "Whether the text was cut at the server\u0027s output limit; read on from the line after the last one shown.",
          "type": "boolean"
        }
      },
      "required": [
        "path",
        "from",
        "to",
        "lines",
        "text",
        "isCut"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}

write_file

Writes a file whole, creating the folders above it. Overwrites without asking: read it first, or use edit_file to change a part.

may overwrite or delete · every call adds · stays on this machine.

Parameter Type Required Default Description
path string yes — Path of the file, absolute or relative to the session's root.
text string yes — The whole new contents of the file.
JSON Schema
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Path of the file, absolute or relative to the session\u0027s root.",
      "type": "string"
    },
    "text": {
      "description": "The whole new contents of the file.",
      "type": "string"
    }
  },
  "required": [
    "path",
    "text"
  ]
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "path": {
          "description": "The file, relative to the session\u0027s root.",
          "type": "string"
        },
        "isCreated": {
          "description": "Whether the file was not there before.",
          "type": "boolean"
        },
        "bytes": {
          "description": "The length of the file now, in bytes.",
          "type": "integer"
        }
      },
      "required": [
        "path",
        "isCreated",
        "bytes"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}

edit_file

Replaces exact text in a file; nothing else in it changes, its encoding and line ends included. Refuses when the text is not there, when it is there more than once without 'all', and when the file is too large to read whole: write such a file with write_file.

may overwrite or delete · every call adds · stays on this machine.

Parameter Type Required Default Description
path string yes — Path of the file, absolute or relative to the session's root.
find string yes — The exact text to replace, with its indentation; a line end may be written as \n.
replace string yes — What to put in its place; empty removes it.
all boolean — false Replace every occurrence rather than refusing when there is more than one.
JSON Schema
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Path of the file, absolute or relative to the session\u0027s root.",
      "type": "string"
    },
    "find": {
      "description": "The exact text to replace, with its indentation; a line end may be written as \\n.",
      "type": "string"
    },
    "replace": {
      "description": "What to put in its place; empty removes it.",
      "type": "string"
    },
    "all": {
      "description": "Replace every occurrence rather than refusing when there is more than one.",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "path",
    "find",
    "replace"
  ]
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "path": {
          "description": "The file, relative to the session\u0027s root.",
          "type": "string"
        },
        "replaced": {
          "description": "How many places were replaced.",
          "type": "integer"
        },
        "bytes": {
          "description": "The length of the file now, in bytes.",
          "type": "integer"
        }
      },
      "required": [
        "path",
        "replaced",
        "bytes"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}

list_directory

Lists what is under a folder, to the depth asked for. Build output, .git and links are never walked into.

read-only · every call adds · stays on this machine.

Parameter Type Required Default Description
path string? — null Folder to work in; omit for the session's root.
depth integer — 2 How many folders deep to go; two by default, eight at most.
JSON Schema
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Folder to work in; omit for the session\u0027s root.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "depth": {
      "description": "How many folders deep to go; two by default, eight at most.",
      "type": "integer",
      "default": 2
    }
  }
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "path": {
          "description": "The folder listed, relative to the session\u0027s root.",
          "type": "string"
        },
        "entries": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "description": "Relative to the session\u0027s root.",
                "type": "string"
              },
              "isDirectory": {
                "description": "Whether it is a folder.",
                "type": "boolean"
              },
              "bytes": {
                "description": "The length of a file in bytes; 0 for a folder.",
                "type": "integer"
              }
            },
            "required": [
              "path",
              "isDirectory",
              "bytes"
            ]
          }
        },
        "isCut": {
          "description": "Whether there was more than the server lists at once.",
          "type": "boolean"
        },
        "unread": {
          "description": "Folders that could not be opened, so nothing in them is listed.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "description": "What the unread folders mean for the answer; null when there are none.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "path",
        "entries",
        "isCut",
        "unread",
        "note"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}

find_files

Names the files whose path matches a glob: .cs, /Tests/cs, appsettings..json.

read-only · every call adds · stays on this machine.

Parameter Type Required Default Description
pattern string yes — The glob to match. '*' stays inside one folder, '**' crosses them.
path string? — null Folder to work in; omit for the session's root.
JSON Schema
{
  "type": "object",
  "properties": {
    "pattern": {
      "description": "The glob to match. \u0027*\u0027 stays inside one folder, \u0027**\u0027 crosses them.",
      "type": "string"
    },
    "path": {
      "description": "Folder to work in; omit for the session\u0027s root.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "pattern"
  ]
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "pattern": {
          "description": "The pattern as matched.",
          "type": "string"
        },
        "files": {
          "description": "The files matched, relative to the session\u0027s root.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "isCut": {
          "description": "Whether there were more matches than the server gives at once.",
          "type": "boolean"
        },
        "unread": {
          "description": "Folders that could not be opened, so nothing in them was matched.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "description": "What the unread folders mean for the answer; null when there are none.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "pattern",
        "files",
        "isCut",
        "unread",
        "note"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}

search_text

Names the lines that contain a text, with the file and the line number of each. Exact text, not a pattern. Names the files it could not search.

read-only · every call adds · stays on this machine.

Parameter Type Required Default Description
query string yes — The text to look for, matched exactly within one line.
path string? — null Folder to work in; omit for the session's root.
pattern string? — null Only search files whose path matches this glob.
JSON Schema
{
  "type": "object",
  "properties": {
    "query": {
      "description": "The text to look for, matched exactly within one line.",
      "type": "string"
    },
    "path": {
      "description": "Folder to work in; omit for the session\u0027s root.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "pattern": {
      "description": "Only search files whose path matches this glob.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "query"
  ]
}
Output schema
{
  "type": "object",
  "properties": {
    "ok": {
      "description": "true: the call did what was asked. A refusal is an error result with ok false, error, hint and type in its text alone.",
      "type": "boolean"
    },
    "error": {
      "description": "Why the call did not go through; present only on a refusal, which is an error result.",
      "type": [
        "string",
        "null"
      ]
    },
    "hint": {
      "description": "What to do next: about a refusal, or with the data of a success that carries one; absent otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "The kind of refusal, a word a program can branch on; present only on one.",
      "type": [
        "string",
        "null"
      ]
    },
    "data": {
      "description": "What the tool answers.",
      "type": "object",
      "properties": {
        "query": {
          "description": "The text searched for.",
          "type": "string"
        },
        "matches": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "description": "The file, relative to the session\u0027s root.",
                "type": "string"
              },
              "line": {
                "description": "The line\u0027s number, counted from 1.",
                "type": "integer"
              },
              "text": {
                "description": "The line, cut to 240 characters.",
                "type": "string"
              }
            },
            "required": [
              "path",
              "line",
              "text"
            ]
          }
        },
        "isCut": {
          "description": "Whether there were more matches than the server gives at once.",
          "type": "boolean"
        },
        "unread": {
          "description": "Files and folders not searched: too large, or not readable.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "description": "What the unread files mean for the answer; null when there are none.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "query",
        "matches",
        "isCut",
        "unread",
        "note"
      ]
    }
  },
  "required": [
    "ok",
    "data"
  ]
}