Nerf Tools
Define and generate nerf tools: limited-scope wrappers for common CLI utilities that allow for
fine-grained control over agent execution.
Nerf tools wrap CLI commands so that the resulting tool has a limited, predictable scope. This then
allows for broad permissioning in agentic tooling, knowing that the tools can't be used to perform
operations outside of the declared scope.
This mechanism was designed specifically for Claude Code, where the permission system (as of
2026-04) is not really capable of fine-grained control over broad tools like git, aws, etc. That
said, it should work in any environment where a permission layer can allow calling a tool like
nerf-git-add but block calling git directly.
Core Concepts
Packages and Tools
A tool is a single executable script that wraps one or more underlying CLI utilities in a
limited-scope interface. Tools can support parameters (options as well as positional arguments) as
needed to satisfy their purpose.
To help keep things tidy, tools are grouped into packages. This organization is completely
arbitrary but is generally done around a specific underlying CLI utility (all or part). For example,
all nerf tools that wrap git might be grouped into a git package, while tools that wrap aws
commands might be grouped into several aws-<subservice> packages, such as aws-s3, aws-ec2,
etc.
Manifests
Manifests are the way that nerf tools are defined. The mechanism is designed to make it very
easy and fast to define new tools. The nerf tool system supports several different types of tool
that have different semantics, capabilities, and relationships to the underlying CLI utilities they
wrap. A generate process then takes the manifests and generates the corresponding executable nerf
tools.
An individual manifest can contain any number of tool definitions for a single package. Any number
of manifest files can be used to generate tools and multiple manifests can contribute to the same
package, with tools merged using last-wins semantics.
For more detail on the manifest format and tool types/capabilities, see the
manifest reference.
This repo includes a set of default manifests that define a baseline
set of nerf tools for common CLI utilities. Users are free to build upon these with their own custom
manifests or exclude them entirely by passing the --no-default flag to the CLI when generating
tools.
Targets
A target is the output format that the nerf CLI should generate from the manifests. Different
targets produce different artifacts from the same set of manifests. For example, the bin target
generates executable scripts in a single directory that can then be placed on the PATH for easy
access. Other targets (such as claude-plugin) are designed and packaged for use with specific
tooling.
Many targets include a notion of "skills", which are conventional agent skills, designed to convey
how to use the generated tools. Skills are generally created one per package, listing all the tools
within that package along with the package-level information.
How to Use Nerf Tools
This repo offers several ways to use the nerf tools. Choose the best one for your specific needs:
- The repo exposes a fully-generated Claude Code plugin with the default tools that can be installed
into a Claude Code environment directly from this repository. This is super easy but does not
allow for customization of the tools or other changes to the plugin.
- Alternatively, users can install the Python package and generate their own targets locally using
the CLI.
- Additionally, platforms like Agentworks integrate
with nerf tools to allow for automated generation and consumption of targets from manifests as
part of broader agentic tooling platforms.
Security Model
Nerf tools are specifically designed to work in environments where the agent technically has access
to the underlying CLI utilities (e.g., git, aws, etc. are installed, configured, and available)
but where a permission layer can restrict direct access to those tools. This is generally true for
agentic co-development frameworks such as Claude Code, OpenCode, etc.
It's important to note that the security here is only as good as the permission layer. If that can
be circumvented such that the agent can invoke the underlying CLI utilities directly, then the nerf
tools no longer provide any meaningful restriction on what the agent can do.
