@clarvis/agent-toolsThe coding tools your agent needs — as a plain library

What it gives your agent ​

@clarvis/agent-tools is the tool layer for an LLM coding agent, packaged as a library you call directly. You give it a workspace root; it gives you a validated, bounded, workspace-confined surface of nine tools — the primitives an agent needs to read, search, edit, and run code:

• Advertise a tool surface to your model. listTools() returns each tool's name, description, and JSON Schema — hand it straight to a model's tool-use API.
• Call tools safely. callTool(name, args) validates arguments against the schema, runs the handler, bounds the output, and never throws for tool-level problems — you always get { isError, text } back.
• Keep the agent inside the workspace. File paths are confined to the root by default; a stray ../ or absolute path comes back as a path_escape error rather than touching the host.
• Get typed, honest results. Success is plain text (or a JSON object for bash); failure is a JSON error envelope with a stable error code.

It carries no transport and no built-in agent loop — it is the tools, and nothing else. Advertise the surface, dispatch the calls, feed the results back; how the tools reach your model is entirely up to you.

Install ​

npm install @clarvis/agent-tools

Node ≥ 20, ESM only. Optional: ripgrep (rg) on PATH — grep uses it when present and falls back to an in-process implementation otherwise.

Quick start ​

import { createAgentTools } from "@clarvis/agent-tools";

const tools = createAgentTools({ workspaceRoot: process.cwd() });

// Advertise the surface (name / description / JSON Schema) to your model:
const surface = tools.listTools();

// Call a tool by name with its arguments:
const res = await tools.callTool("read_file", { path: "package.json" });
if (res.isError) {
  const err = JSON.parse(res.text) as { error: string; message: string };
  console.error(err.error, err.message);
} else {
  console.log(res.text);
}

Two ways in ​

Use the factory. createAgentTools(options) resolves a config once and returns listTools() / callTool() — the ergonomic path for wiring the tools into an agent loop. Start with Getting started, then Embed it in an agent loop.

Drive the core directly. The building blocks — resolveConfig, dispatch, listTools, and the raw tool registry — are exported too, for building your own transport (an HTTP endpoint, a CLI, a test harness). See The core API.

Built for safety ​

These tools grant read/write access to the workspace and arbitrary shell execution with the privileges of the host process. Path confinement is defense-in-depth for the file tools — it is not a sandbox, and it does not constrain bash. Run the process inside an OS-level sandbox scoped to the project. See Workspace confinement and Deploy securely.