Chloe

Reference

@chloejs/core/tools/fs

One folder, as tools: list, read, search, write and edit.

The tools over services/filesService.ts: one folder, offered to a model.

An agent binds each one to a root it is allowed to see, and names that folder in plain words for the description.

import * as fs from "@chloejs/core/tools/fs";
tools: { fsReadFile: fs.readFile({ root: "/srv/notes", what: "the shared notes" }) }

editFilelistFilesreadFilesearchFiles

editFilefunction

export function editFile({
  root,
  what,
  commit = false,
  author,
  memory = false,
}: Folder & { commit?: boolean; author?: string; memory?: boolean })

Makes a tool that lets the model change a file inside root. It gives a list of changes, each the exact text to replace and the new text, and each old text must appear in the file once, or nothing is changed. A change with no old text adds to the end of the file, or makes the file when it is not there: for a log, a list that only grows, or a first draft. There is no tool that replaces a whole file, because that is how the rest of one gets lost. Missing folders are made. The same tool moves, renames or deletes a file or a folder (moveTo, delete), after any changes, as one commit.

Options, besides root and what:

  • commit: set to true to save each call as one git commit, with a commit message the model must write. Off by default. root must be inside a git repository, or the file is written but not committed.
  • author: the name the commits are made under, such as the agent's id. Default: this machine's own git name.
  • memory: set to true when root is the agent's memory folder, so each commit is listed on the run that made it. Off by default. Only matters with commit.

model/tools/fs.ts:127

listFilesfunction

export function listFiles({ root, what }: Folder)

Makes a tool that lets the model list the files and folders in one folder inside root. Hidden files (names starting with .) are left out.

The model also gets a map of the folders in root, two levels deep, at the start of each reply, so it knows the layout before its first call.

Needs no connection.

tools: { fsListFiles: fs.listFiles({ root: "/srv/notes", what: "the shared notes" }) }

model/tools/fs.ts:39

readFilefunction

export function readFile({ root, what, limit = 40_000 }: Folder & { limit?: number })

Makes a tool that lets the model read one file inside root, or some of its lines.

limit is the most characters the model gets when it reads a whole file. A longer file is cut at the end of a line, and the model is told how many lines the file has, so it can ask for the part it needs. Default: 40,000 (about 10,000 tokens).

model/tools/fs.ts:69

searchFilesfunction

export function searchFiles({ root, what, around = 2 }: Folder & { around?: number })

Makes a tool that lets the model search the text of the files inside root. The search ignores upper and lower case, and looks for the exact words given (not a pattern). Each result has its file and line number.

around is how many lines before and after each match the model gets with it. Default: 2. The model gets at most 5 matches per file, and 30 in all (80 when around is 0).

model/tools/fs.ts:93