create_file
Create a new file in the workspace, failing if it already exists.
create_file
Create a brand-new file at a workspace-relative path. Unlike write_file, create_file never overwrites an existing file — collisions return already_exists so the agent can decide between editing the existing content or moving it aside.
import { createAgent } from "@comma-agents/core";
const agent = createAgent({
name: "scaffolder",
model: "openai/gpt-4o",
tools: ["create_file"],
});CreateFileToolConfig
Optional configuration for the factory.
Prop
Type
CreateFileData
The structured payload returned on success.
Prop
Type
Parent directories
By default create_file creates missing parent directories along the way. Pass createParents: false to require the parent to exist — the call then returns not_found if any segment is missing.
await tool.create_file({
path: "src/util/new-helper.ts",
content: "export const greet = () => \"hi\";\n",
});Newline normalization and BOM
Content is written verbatim by default. When the caller already knows the target line ending or BOM behavior, the tool will not infer one — pass content exactly as you want it on disk. The returned sha256 reflects the bytes actually written.
Errors
| Kind | When |
|---|---|
already_exists | A file or directory already exists at path. Switch to write_file (if you want to overwrite by sha256) or edit_file (to change part of the file). |
not_found | A parent directory is missing and createParents: false was passed. |
outside_workspace | The path escapes the sandbox or is absolute without allowAbsolutePaths. |
permission_denied | The path is write-blocked by forbiddenGlobs or sandbox policy. |
Related
- write_file — overwrite an existing file by sha256.
- edit_file — change a region of an existing file.
- Audit log — every successful create is journaled.