Skip to content

List dir

list_dir

ListDirTool — directory listing with file metadata.

Registered as list_dir via the axm.tools entry point.

ListDirTool

Directory listing with file metadata for AI agents.

Lists files and directories within a sandboxed root directory. Supports recursive listing via max_depth. Hidden entries and build artefacts (__pycache__, node_modules, etc.) are skipped automatically. Registered as list_dir via axm.tools entry point.

Source code in packages/axm-edit/src/axm_edit/tools/list_dir.py
Python
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class ListDirTool:
    """Directory listing with file metadata for AI agents.

    Lists files and directories within a sandboxed root directory.
    Supports recursive listing via *max_depth*. Hidden entries and
    build artefacts (``__pycache__``, ``node_modules``, etc.) are
    skipped automatically.
    Registered as ``list_dir`` via axm.tools entry point.
    """

    agent_hint: str = (
        "List directory tree with file sizes."
        " Use max_depth to limit. Replaces ls/find for project exploration."
    )

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

    def execute(
        self,
        *,
        path: str = ".",
        max_depth: int = 1,
        **kwargs: object,
    ) -> ToolResult:
        """List files and directories in a project directory.

        Args:
            path: Root directory to list (default ".").
            max_depth: Recursion depth — 1 for immediate children
                only, >1 for nested listing (default 1).

        Returns:
            ToolResult with entries list (name, path, type,
            size_bytes), count, and truncated flag.
        """
        root_str = path
        depth = max(max_depth, 1)

        root = Path(root_str).resolve()
        if not root.is_dir():
            return ToolResult(
                success=False,
                error=f"Path is not a directory: {root_str}",
            )

        entries: list[dict[str, object]] = []
        truncated = _collect_entries(root, root, depth, 1, entries)

        return ToolResult(
            success=True,
            data={
                "entries": entries,
                "count": len(entries),
                "truncated": truncated,
            },
        )
name property

Tool name used for MCP registration.

execute(*, path='.', max_depth=1, **kwargs)

List files and directories in a project directory.

Parameters:

Name Type Description Default
path str

Root directory to list (default ".").

 '.'
max_depth int

Recursion depth — 1 for immediate children only, >1 for nested listing (default 1).

 1

Returns:

Type Description
ToolResult

ToolResult with entries list (name, path, type,
ToolResult

size_bytes), count, and truncated flag.
Source code in packages/axm-edit/src/axm_edit/tools/list_dir.py
Python
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def execute(
    self,
    *,
    path: str = ".",
    max_depth: int = 1,
    **kwargs: object,
) -> ToolResult:
    """List files and directories in a project directory.

    Args:
        path: Root directory to list (default ".").
        max_depth: Recursion depth — 1 for immediate children
            only, >1 for nested listing (default 1).

    Returns:
        ToolResult with entries list (name, path, type,
        size_bytes), count, and truncated flag.
    """
    root_str = path
    depth = max(max_depth, 1)

    root = Path(root_str).resolve()
    if not root.is_dir():
        return ToolResult(
            success=False,
            error=f"Path is not a directory: {root_str}",
        )

    entries: list[dict[str, object]] = []
    truncated = _collect_entries(root, root, depth, 1, entries)

    return ToolResult(
        success=True,
        data={
            "entries": entries,
            "count": len(entries),
            "truncated": truncated,
        },
    )