Skip to content

write_file

The write_file tool creates new files or completely overwrites existing ones. It automatically creates parent directories if they don’t exist.

Description

Write content to a file at the specified path. Creates the file if it doesn’t exist, or overwrites if it does. Parent directories are created automatically as needed.

Parameters

ParameterTypeRequiredDescription
pathstringYesThe path to the file to write
contentstringYesThe content to write to the file

Examples

Create a New File

you: Create a README with basic project info


ai: I'll create a README file for you.


[tool: write_file]
  path: "README.md"
  content: "# My Project\n\nA brief description..."


Successfully wrote 8 lines to README.md

Create File in New Directory

you: Create a test file at tests/unit/config_test.rs


ai: I'll create the test file. The directories will be created automatically.


[tool: write_file]
  path: "tests/unit/config_test.rs"
  content: "#[cfg(test)]\nmod tests ..."


Successfully wrote 10 lines to tests/unit/config_test.rs

Output Format

On success:

Successfully wrote 8 lines to path/to/file.txt

On error:

Failed to write file: Permission denied

Behavior Notes

Directory Creation

Parent directories are created automatically:

write_file("a/b/c/file.txt", content)
# Creates: a/, a/b/, a/b/c/ if they don't exist

Overwrites Completely

write_file replaces the entire file content:

# Original file: "Hello World"
write_file("file.txt", "Goodbye")
# Result: "Goodbye" (original content is gone)

For partial edits, use edit_file instead.

Error Handling

ErrorCause
Failed to create directoriesPermission denied or invalid path
Failed to write file: Permission deniedNo write permission
Failed to write file: Read-only file systemFilesystem is read-only

Use Cases

When to Use write_file

  • Creating new files from scratch
  • Generating boilerplate code
  • Writing configuration files
  • Creating test fixtures
  • Replacing entire file contents

When to Use edit_file Instead

  • Modifying part of an existing file
  • Adding a function to existing code
  • Fixing a bug in specific lines
  • Updating imports or dependencies

Best Practices

  1. Review before writing

    • Ask the AI to show the content before writing
    • Verify the path is correct

  2. Use edit_file for modifications

    • Safer for existing files
    • Preserves content you don’t want to change

  3. Consider file organization

    • Let kicode create appropriate directory structure
    • Follow project conventions for file placement