File Access and Editing Functions

Core file-access functions read, attach, edit, create, rename, delete, and open local files.

These functions use the current solution or workspace for path validation and approval. Reads inside known solution/workspace files are usually lightweight. Reads outside the known model, writes, file creation, renames, and deletion can require user approval and may show diff annotations before applying changes.

Reading Files

  • getContentsOfTextFile returns the full contents of a local text file by absolute path. It is intended for reasonably small text files.
  • getLinesInFile returns an inclusive one-based line range from a local file. Use this for large files or focused inspection.
  • getFile attaches a local file to the model as a multimodal file. Use it for images, PDFs, or other non-code files that the model should inspect directly.

For text files and other plain text, prefer getContentsOfTextFile or getLinesInFile so text stays easy to quote, search, and edit. Use getFile when the model needs the actual file payload, such as an image or PDF.

Editing Files

  • replaceTextInFile replaces one or more exact text snippets in a file. Each replacement uses exact text, not regex. The tool validates all replacements before writing anything and supports a dryRun mode that returns proposed contents without write approval.
  • replaceFullContentsOfFile replaces the entire contents of a file. Use it only when CodeBot has the complete final contents and the exact absolute file path.

Use replaceTextInFile for targeted edits when the original text is known. Use replaceFullContentsOfFile for generated files or broad rewrites where replacing the whole file is clearer and safer than many small replacements.

Creating Files

  • createFileAndAddToProject creates a new source file in a project in the current solution. It should be used for new project files, not ordinary standalone workspace files.
  • createFileWithText creates a new local text file at an absolute path. Use this only for deliberate file creation outside normal project-file workflows.

For project-based hosts, use createFileAndAddToProject so the IDE project model stays in sync. For Campfire folder workspaces, use the Campfire-specific createFileInWorkspaceFolder instead.

Renaming, Deleting, and Opening

  • renameFile renames a file in place. It accepts the absolute path and a new file name, not a destination path.
  • deleteFileAndRemoveFromProject deletes a file and, when the file belongs to a project, removes it from the project safely.
  • goToFile opens a file in the IDE and can optionally move the cursor to a one-based line number.

Use goToFile when the user asks to show a file or jump to a known location. Use rename and delete only when the requested action is clear and the approval/diff flow has confirmed it.

When To Use Which Tool

Use getLinesInFile before loading a large file in full.

Use getFile for images and PDFs that the model should inspect directly.

Use replaceTextInFile for precise local edits.

Use replaceFullContentsOfFile for complete generated replacements.

Use host-specific file creation when the host has one, such as Campfire's createFileInWorkspaceFolder.