Skip to content

Write file

write_file

WriteFileTool — write content to a file.

Registered as write_file via the axm.tools entry point.

WriteFileTool

Write content to a file, creating parent directories.

Simple single-file write for AI agents. For atomic multi-file operations, use :class:BatchEditTool instead. Registered as write_file via axm.tools entry point.

Source code in packages/axm-edit/src/axm_edit/tools/write_file.py
Python
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
class WriteFileTool:
    """Write content to a file, creating parent directories.

    Simple single-file write for AI agents. For atomic multi-file
    operations, use :class:`BatchEditTool` instead.
    Registered as ``write_file`` via axm.tools entry point.
    """

    agent_hint: str = (
        "Write text content to a file (creates parents)."
        " Use for artifacts, configs, and new files."
        " For multi-file atomic edits, use batch_edit instead."
    )

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "write_file"

    def execute(
        self,
        *,
        path: str | None = None,
        content: str | None = None,
        **kwargs: object,
    ) -> ToolResult:
        """Write content to a file.

        Args:
            path: Absolute path to the file to write.
            content: Text content to write.

        Returns:
            ToolResult with written file path and byte count.
        """
        file_path = path

        if not file_path:
            return ToolResult(success=False, error="Missing required argument: path")
        if content is None:
            return ToolResult(success=False, error="Missing required argument: content")

        target = Path(file_path)

        try:
            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_text(content, encoding="utf-8")
        except OSError as exc:
            return ToolResult(success=False, error=f"Write failed: {exc}")

        byte_count = len(content.encode("utf-8"))
        logger.debug("wrote %s (%d bytes)", file_path, byte_count)

        target_path = str(target)
        return ToolResult(
            success=True,
            data={
                "path": target_path,
                "bytes": byte_count,
            },
            text=render_text(path=target_path, byte_count=byte_count),
        )
name property

Tool name used for MCP registration.

execute(*, path=None, content=None, **kwargs)

Write content to a file.

Parameters:

Name Type Description Default
path str | None

Absolute path to the file to write.

 None
content str | None

Text content to write.

 None

Returns:

Type Description
ToolResult

ToolResult with written file path and byte count.
Source code in packages/axm-edit/src/axm_edit/tools/write_file.py
Python
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def execute(
    self,
    *,
    path: str | None = None,
    content: str | None = None,
    **kwargs: object,
) -> ToolResult:
    """Write content to a file.

    Args:
        path: Absolute path to the file to write.
        content: Text content to write.

    Returns:
        ToolResult with written file path and byte count.
    """
    file_path = path

    if not file_path:
        return ToolResult(success=False, error="Missing required argument: path")
    if content is None:
        return ToolResult(success=False, error="Missing required argument: content")

    target = Path(file_path)

    try:
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")
    except OSError as exc:
        return ToolResult(success=False, error=f"Write failed: {exc}")

    byte_count = len(content.encode("utf-8"))
    logger.debug("wrote %s (%d bytes)", file_path, byte_count)

    target_path = str(target)
    return ToolResult(
        success=True,
        data={
            "path": target_path,
            "bytes": byte_count,
        },
        text=render_text(path=target_path, byte_count=byte_count),
    )

render_text(*, path, byte_count)

Render a compact, git-style LLM-facing view of a write result.

The header carries the global status (✓) plus the written path and its exact byte count. Both values mirror data verbatim — only the JSON structure (braces, quotes, keys) is dropped, so no information is lost relative to data.

Source code in packages/axm-edit/src/axm_edit/tools/write_file.py
Python
18
19
20
21
22
23
24
25
26
27
def render_text(*, path: str, byte_count: int) -> str:
    """Render a compact, ``git``-style LLM-facing view of a write result.

    The header carries the global status (``✓``) plus the written path and
    its exact byte count. Both values mirror ``data`` verbatim — only the
    JSON structure (braces, quotes, keys) is dropped, so no information is
    lost relative to ``data``.
    """
    plural = "s" if byte_count != 1 else ""
    return f"write_file | ✓ | {path} · {byte_count} byte{plural}"