Skip to content

Mero LangChain Tools — Documentation

Mero LangChain Tools (langchain_mero_tools) is a set of security-conscious file, directory, search, process, and rsync tools for LangChain / LangGraph agents. It ships with scoped permissions, path sandboxing, command allow/deny lists, human-in-the-loop approval, and manager/worker delegation — all optional, all composable, and none of it forced on you.

If you never pass a SecurityContext, every tool behaves exactly like a plain LangChain tool with full filesystem access. The security layer only activates when you opt in.

This docs/ directory is the full reference. Each page is self-contained — you can open any single page and get a complete picture of that topic without having to piece things together from five other files. Pages link to each other for related material, but nothing here requires reading in order (though a first-time reader will likely enjoy going 1 → 2 → 3).

Contents

# Page What's in it
1 Installation Requirements, pip install, optional extras, optional system binaries
2 Quickstart Smallest possible working examples, unrestricted and sandboxed
3 Core Concepts How the library is put together: guard(), SecurityContext, Permission, exceptions
4 Tools Overview All five tools at a glance, the get_tools() factory, wiring into an agent
5 File Tool read / write / edit / copy / move / delete on individual files
6 Directory Tool list (tree view) / create / copy / move / delete on directories
7 Search Tool Find files or search file contents (ripgrep → grep → pure Python)
8 Process Tool Run shell commands, shell=True vs shell=False
9 Rsync Tool Sync a source directory to a destination, both sides sandboxed
10 Security & Sandboxing SecurityContext/PathEntry in depth: the virtual mount table, permission inheritance, command patterns
11 Approval Workflows Human-in-the-loop approval backends, including writing your own
12 Manager/Worker Delegation Multi-agent setups where a manager can approve on behalf of workers
13 LangGraph Integration Pausing a graph with interrupt() and resuming with Command(resume=...)
14 Building Custom Tools How to add your own tool that plugs into the same security layer
15 Error Handling The exception hierarchy and how errors reach the agent
16 FAQ & Troubleshooting Common questions and gotchas

30-second overview

from langchain_mero_tools import SecurityContext, PathEntry, Permission, get_tools

# Sandbox an agent to one directory, read+write only, no delete/execute.
ctx = SecurityContext(
    name="worker_1",
    paths=[
        PathEntry(
            path="./workspace",
            slug="root",
            allowed_permission=Permission.READ | Permission.WRITE,
        ),
    ],
)

tools = get_tools(ctx)  # file, directory, search, process, rsync — all scoped

Bind tools to any LangChain-compatible agent (create_react_agent, a custom AgentExecutor, a LangGraph ToolNode, etc.) exactly like you would any other list of StructuredTool objects — see Tools Overview for a full wiring example.

What makes this different from "give the agent a shell tool"

  • Path sandboxing that resolves symlinks and .. before checking — an agent can't escape its configured PathEntry scope with ../../etc/passwd-style tricks, and an out-of-scope absolute path is rejected outright rather than silently remapped inside the sandbox.
  • Explicit, non-guessed command matching — allow/deny rules are always one of exactly three kinds (literal, glob, re:), so a glob like "git *" can never accidentally behave like an unanchored regex (see Security & Sandboxing).
  • Fail-safe approval — if a context requires approval for an action and no approval backend is configured, the action is denied, not allowed.
  • Zero required system dependencies — the search and rsync tools work out of the box with a pure-Python fallback, and get faster automatically if ripgrep/rsync happen to be installed.
  • Composable approval chains and manager/worker delegation — for multi-agent systems where you don't want every worker action escalated to a human.
  • A single choke point (guard()) — every tool funnels through the same path/permission/approval checks, so adding a new tool never means re-implementing security logic. See Building Custom Tools.

Package layout (for orientation)

src/langchain_mero_tools/
├── __init__.py           # public API: get_tools(), re-exports
├── core/
│   ├── security.py       # SecurityContext, PathEntry, Permission, pattern matching
│   ├── guard.py          # the single choke point every tool calls
│   ├── approval.py       # ApprovalBackend implementations
│   ├── hierarchy.py      # manager/worker delegation
│   └── exceptions.py     # MeroToolsError and subclasses
└── tools/
    ├── file_tool.py
    ├── directory_tool.py
    ├── search_tool.py
    ├── process_tool.py
    └── rsync_tool.py

Start with Installation if you're setting this up for the first time, or jump straight to Quickstart if you already have the package installed.