Write Tool

The Write tool creates new files or completely overwrites existing files with new content. It automatically creates parent directories and saves backups of overwritten files for recovery during the session.

Parameters

Creating New Files

When the file does not exist, Write creates it along with any missing parent directories:

> Create a new utility module for date formatting

Agent invokes Write:
  file_path: src/lib/date-utils.ts
  content: |
    import { format, formatDistanceToNow } from 'date-fns';

    export function formatDate(date: Date): string {
      return format(date, 'yyyy-MM-dd HH:mm:ss');
    }

    export function relativeTime(date: Date): string {
      return formatDistanceToNow(date, { addSuffix: true });
    }

Result: ✓ File created: src/lib/date-utils.ts

No prior Read is required for new files.

Overwriting Existing Files

When the file exists, Write replaces its entire content. A backup is automatically saved in memory:

> Rewrite the config loader with the new schema

Agent invokes Write:
  file_path: src/lib/config.ts
  content: |
    [completely new file content]

Result:
  ✓ Backup saved
  ✓ File overwritten: src/lib/config.ts

Warning: When overwriting an existing file, the agent MUST have read the file first in the current conversation. Write will fail if the file hasn't been read. This prevents accidental overwrites based on stale context.

Automatic Directory Creation

Write automatically creates parent directories that don't exist:

> Create src/components/common/Spinner.tsx

Even if src/components/common/ doesn't exist, the Write tool creates it:

Agent invokes Write:
  file_path: src/components/common/Spinner.tsx
  content: |
    export function Spinner() {
      return <div className="spinner" />;
    }

Result: ✓ Directories created: src/components/common/
        ✓ File created: src/components/common/Spinner.tsx

No need to manually mkdir before writing.

Backup and Recovery

When overwriting an existing file:

• A backup of the original content is saved automatically
• The backup is available for the duration of the session
• If the new content causes issues, the agent can restore the original

Tip: The backup is stored in memory, not on disk. It persists only for the current session.

Write vs Edit

Note: Edit is generally preferred for modifications to existing files. It is safer because it preserves unmodified portions exactly as they are. Use Write only for new files or complete rewrites.

Best Practices

Prefer Edit over Write for existing files. Edit is safer — it only touches the parts you change.

Match project conventions. The agent should follow the project's indentation style (tabs vs spaces), file naming conventions, and import patterns.

Write complete, valid files. The content should be syntactically correct and idiomatic for the language.

Avoid documentation files. The agent is instructed not to create documentation files unless explicitly requested.

Common Patterns

Creating a new component:

// Write: src/components/Button.tsx
import React from 'react';

interface ButtonProps {
  label: string;
  onClick: () => void;
}

export function Button({ label, onClick }: ButtonProps) {
  return <button onClick={onClick}>{label}</button>;
}

Creating a new test file:

// Write: src/__tests__/utils.test.ts
import { formatDate } from '../lib/date-utils';

describe('formatDate', () => {
  it('formats a date correctly', () => {
    const result = formatDate(new Date('2026-01-15'));
    expect(result).toBe('2026-01-15 00:00:00');
  });
});

Creating a configuration file:

// Write: .env.example
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=your_database_connection_string

Next Steps

• Edit — Making targeted changes to existing files
• Read — Reading file contents
• Tools Overview — All available tools