Agent Tools

Agent Tools is a cross-platform command-line application for coding-agent workstations. It discovers and diagnoses the Python and native capabilities agents depend on. Read-only inspection is the default; workflows that change desired state, agent integrations, or native providers require explicit authorization.

Quick start

Install uv through a trusted package manager, then install the current stable release from PyPI:

uv tool install --python 3.13 smartnuf-agent-tools

Run the installed executable directly from uv's tool directory so no shell profile or persistent PATH change is required.

PowerShell:

$agentTools = "$(uv tool dir --bin)\agent-tools.exe"
& $agentTools doctor
& $agentTools tools list
& $agentTools tools status

Linux or macOS:

agent_tools="$(uv tool dir --bin)/agent-tools"
"$agent_tools" doctor
"$agent_tools" tools list
"$agent_tools" tools status

doctor, tools list, and tools status are read-only. Discovery verifies what is already available and never installs software, edits configuration, or changes PATH. tools list shows the packaged capability catalogue; tools status [CAPABILITY] reports detected providers, executable paths, versions, execution environments, and architectures where observable. A missing required native executable makes doctor report the gap and return a nonzero status. Published v0.1.2 also requires its bundled Python libraries; the v0.2 optional-library behavior is described below.

Upgrade an unpinned installation:

uv tool upgrade smartnuf-agent-tools

Remove the application:

uv tool uninstall smartnuf-agent-tools

Uninstalling removes uv's isolated application environment and launcher. It does not remove user-owned desired state, reverse an active agent integration, or uninstall external native providers such as Bash, Poppler, or Ghostscript.

Install native capabilities (v0.2+)

These commands require v0.2 or later; published v0.1.2 does not include them. Use the installed launcher from the quick start. Names come from agent-tools tools list; they are capabilities such as poppler, not arbitrary package names, files or named sets.

PowerShell — install Poppler:

& $agentTools install poppler --dry-run
& $agentTools install poppler --allow-provider-mutation
& $agentTools install --help

Linux or macOS — install Poppler and Ghostscript:

"$agent_tools" install poppler ghostscript --dry-run
"$agent_tools" install poppler ghostscript --allow-provider-mutation
"$agent_tools" install --help

The dry run displays a read-only plan. The mutation flag authorizes the displayed native package-manager actions and managed provenance recording. There is no interactive confirmation prompt. Only named capabilities are requested; enabling Bash in configuration does not add it to an installation of Poppler. Stored exact preferences for requested capabilities are honored. For execution, requests that are already satisfied are verified no-ops; if changes are needed, a request without the mutation flag displays the plan and refuses installation. Dry runs display the plan without entering execution or requiring that flag.

The supported package manager and its existing privileges must already be available. On Windows, the catalogue's Ghostscript WinGet package is currently unavailable upstream; there is no automatic fallback. Existing verified Ghostscript can still satisfy discovery. See the platform guide for provider requirements, exact tested combinations and known gaps.

A successful dry run returns status 0 for producing a plan; it does not prove installation or final verification. For execution, status 0 requires verified success or no-op and successful or unnecessary provenance recording. Status 1 means planning, authorization, execution, verification or persistence did not finish successfully; invalid syntax or capability names return 2 and interruption returns 130. Read the separate host-mutation and provenance results: a nonzero status does not mean that nothing changed. Follow the reported recovery guidance and do not blindly retry a partial or uncertain result. Installation does not enable capabilities, remove shared providers or alter your shell profile.

Optional document libraries

Version 0.2 installs a core CLI without third-party Python dependencies. To include the existing PDF, image, Word and Excel library bundle, explicitly select the documents extra. The extra and diagnostic flag require v0.2 or later; published v0.1.2 still bundles the libraries.

uv tool install --python 3.13 --reinstall 'smartnuf-agent-tools[documents]'
agent-tools doctor --documents

Plain doctor reports optional-library availability separately; missing or broken optional libraries do not affect its exit status. doctor --documents requires the full stack to import successfully. Both modes still check native Poppler and Ghostscript, which are installed separately. Neither mode installs anything. Use the absolute launcher path shown above if it is not on PATH.

An unpinned PyPI v0.1.2 upgrade will select the new core behavior; explicitly select [documents] to retain the library bundle. Later uv tool upgrade smartnuf-agent-tools retains the selected extra and stored version constraints. To change an exact pin, reinstall the intended smartnuf-agent-tools==VERSION or smartnuf-agent-tools[documents]==VERSION requirement. For v0.1.1 direct-wheel migration and checksum-bound rollback, follow the release guidance below.

Return to an unpinned core-only installation explicitly:

uv tool install --python 3.13 --reinstall smartnuf-agent-tools

These requests manage only uv's application environment and launcher; they do not change native providers, desired state or integration settings. There are currently no document-processing subcommands. The extra does not expose its Python imports to arbitrary project interpreters; use a project environment for project document processing. documents is a Python extra, not a native capability accepted by agent-tools install.

Advanced use and source development

• Verify the installed version and optionally update PATH.
• Pin or roll back an exact release.
• Configure desired capabilities and the Claude Code integration.
• Use the source checkout and shared development environment.
• Browse the CLI reference for current command help, arguments, safety requirements, and exit statuses.
• Read the platform guide, packaging contract, or release history.

Installed release details

Choose a published version from the release history. Packaged releases support Python 3.11 through 3.13. Verify your installed version without assuming uv's executable directory is already on PATH:

& "$(uv tool dir --bin)\agent-tools.exe" --version

"$(uv tool dir --bin)/agent-tools" --version

To make agent-tools directly discoverable in future shells, uv tool update-shell can update the user shell configuration. That is an explicit profile change; review uv's reported change and open a new shell afterward.

Pin or roll back

The v0.1.1 prerelease used a direct GitHub wheel rather than PyPI. Replace its recorded direct-wheel requirement while upgrading to the current release:

uv tool install --python 3.13 --upgrade smartnuf-agent-tools

Pin the published version you intend when reproducibility matters, or reinstall that exact version if its isolated environment is damaged. For example, to pin the earlier v0.1.2 release:

uv tool install --python 3.13 --reinstall "smartnuf-agent-tools==0.1.2"

Before rolling back to a version that predates integration commands, explicitly restore any active managed integration while the current command is available:

& "$(uv tool dir --bin)\agent-tools.exe" integrations claude-code remove --allow-config-mutation

"$(uv tool dir --bin)/agent-tools" integrations claude-code remove --allow-config-mutation

Then roll back to the available v0.1.1 GitHub artifact by its exact reviewed, checksum-bound requirement:

uv tool install --python 3.13 --reinstall "smartnuf-agent-tools @ https://github.com/smartnuf/agent-tools/releases/download/v0.1.1/smartnuf_agent_tools-0.1.1-py3-none-any.whl#sha256=b790d7c30294fae43f57ef6e83de02396489dac97ffe59e3616202dff289c14f"

Remove an integration explicitly before rollback or application uninstall when restoration of its managed setting is intended; older releases may not have the integration-removal command.

Poppler and Ghostscript are not bundled. For v0.1.2, install them through the operating system package manager before expecting agent-tools doctor to pass completely. See the v0.1.2 release notes for current limitations.

Capability configuration and integrations

After the optional uv tool update-shell step above, these commands inspect or change desired capability and integration state. Without that PATH change, use the same platform-specific executable path shown above.

agent-tools doctor
agent-tools tools list
agent-tools tools status
agent-tools tools status bash
agent-tools tools enable bash --allow-config-mutation
agent-tools tools disable bash --allow-config-mutation
agent-tools integrations claude-code status
agent-tools integrations claude-code apply --allow-config-mutation
agent-tools integrations claude-code remove --allow-config-mutation

tools status bash reports desired state separately and verifies the detected provider, executable path, version, execution environment, and executable architecture where observable. On Windows it discovers Git Bash outside the normal process PATH; the default WSL distribution is reported separately and never silently treated as Windows-hosted Bash. tools enable and tools disable change only the versioned per-user desired-capability document, require the dedicated mutation flag for a real change, and back up an existing document before replacement. Disable never uninstalls a provider. The status and list commands do not install software or alter PATH.

On native Windows, the Claude Code integration commands can explicitly bind Claude Code's documented user setting to the same selected, verified Git Bash path. Apply and remove require the dedicated configuration-mutation flag, preserve unrelated Claude settings, and restore the exact prior setting; they never install or uninstall Git for Windows. A matching setting not created by Agent Tools remains unowned and is not removed. See Decision 0006 for the recovery and compatibility contract. Version 0.1.2 is the first packaged release containing the read-only commands. Desired-state and integration commands are included in released v0.2.0 and later; no checkout is required.

Source checkout and bootstrap

For the shared agent-python development environment and repository automation, clone into the conventional user-level location:

git clone https://github.com/smartnuf/agent-tools.git "$HOME/.agent-tools"

Alternatively, download the repository's main-branch ZIP archive, extract it, and rename or move the extracted directory to ~/.agent-tools. An archive installation works normally but cannot be updated with git pull; download a newer archive or replace it with a clone to update.

Bootstrap

PowerShell 7+ on Windows:

Set-Location $HOME\.agent-tools
.\scripts\bootstrap.ps1 -InstallUv -InstallNativeTools -AddToPath
agent-tools doctor

Linux or macOS (install uv with a trusted package manager first):

cd "$HOME/.agent-tools"
./scripts/bootstrap.sh --install-native-tools --add-to-path
agent-tools doctor

All mutation flags are opt-in. On Windows, -InstallUv delegates to WinGet. On systems with Homebrew, --install-uv delegates to Homebrew. -InstallNativeTools and --install-native-tools delegate Poppler and Ghostscript discovery, provider planning, mutation, provenance persistence, and final verification to the packaged capability implementation; the wrappers contain no separate native package mapping. Python discovery and environment creation disable automatic downloads; install a compatible Python 3.11 with a trusted provider before bootstrap. A translated/emulated fallback requires -AllowEmulatedPython or --allow-emulated-python. Use -PythonPath PATH or --python PATH to require a particular compatible installed interpreter. The scripts never execute a downloaded installer response directly.

Bootstrap discovers installed interpreters without downloads, verifies each executable, and passes the selected absolute path to uv. A temporary bootstrap process does not determine the final runtime: a compatible native system Python normally wins over a translated managed Python. The resulting .venv is verified again before packages are installed. If an existing .venv no longer matches the selected runtime, bootstrap stops without replacing it; remove that checkout-owned environment deliberately and rerun.

Native setup reports the reviewed package-manager commands and then reports host-mutation and managed-provenance outcomes separately. It also consumes enabled optional capabilities and exact provider preferences from the desired-state document; the bootstrap native-install flag remains a separate authorization for any resulting provider mutation. An all-satisfied rerun performs no provider command. After partial or uncertain execution, do not rerun automatically: follow the reported recovery guidance, rediscover current state, and generate a fresh attempt. Temporary process PATH refresh used for verification is restored; persistent PATH or profile changes still require the separate explicit PATH flag.

PATH changes are also opt-in. Windows backups are written under .backups/path/; Unix shell-profile changes create a timestamped sibling backup before editing an existing profile. Unix profile updates use a per-profile lock. If an interrupted update leaves that lock behind, the command stops without changing the profile and reports the exact lock path and recorded PID. Verify that no update process owns it before removing it manually and rerunning.

The checkout deliberately retains the complete document-library lock in requirements.txt; bootstrap and update continue to install that development environment independently of the lightweight wheel core. Project-local Python environments remain authoritative.

To refresh Python packages later:

.\scripts\update.ps1

or:

./scripts/update.sh

The agent-python wrapper runs the shared development interpreter. The checkout agent-tools wrapper runs the same packaged CLI. These are development and compatibility helpers; ordinary installed workflows use agent-tools without a checkout. Clone bootstrap retains its explicit-plus-enabled native request.

Repository policy and layout

The checked-in repository contains source and recipes. Machine-local state such as .venv/, .tools/, .cache/, temporary directories, and generated output stays untracked.

• Python and packages: use uv to create and update .venv from requirements.txt.
• Windows native tools: the installed CLI uses WinGet. External Chocolatey fixtures in CI do not establish a supported Agent Tools adapter or fallback.
• Debian/Ubuntu: use apt; Fedora/RHEL use dnf; Arch uses pacman.
• macOS: use Homebrew and exercise automation on hosted macOS runners.
• Poppler and Ghostscript: install them through the native package manager; do not copy opaque executables into this repository.
• Capability discovery: keep detection read-only. Git Bash is the preferred Windows-hosted Bash provider; WSL is reported as a separate environment.

bin/                    development and compatibility wrappers
docs/packaging.md       public distribution and dependency contract
docs/platforms.md       platform policy and macOS testing notes
scripts/                bootstrap, update, PATH, and validation scripts
src/agent_tools/        reusable standard-library Python helpers
tests/                  unit tests
requirements.in         reviewed direct Python dependencies
requirements.txt        generated, fully pinned Python environment lock

Scope and security

This is a convenience environment, not a substitute for project-specific dependencies. A project's own environment and lock file remain authoritative. Keep secrets, credentials, private data, and machine-local state out of this public repository.

Development and operation plan

Keep changes small and portable. Develop reusable behaviour in src/agent_tools/, unit-test it without modifying the host, then exercise bootstrap and native installations on disposable GitHub-hosted Windows, Ubuntu, and macOS runners. CI bootstraps twice to catch common idempotency failures and runs doctor against real Poppler, Ghostscript, and Python packages. Native installation on a workstation remains explicitly opt-in.

For source-checkout maintenance:

1. Pull reviewed changes.
2. Run the platform update script to refresh .venv.
3. Run agent-tools doctor and investigate failures before relying on the environment.
4. Upgrade native programs through the operating system package manager, not by replacing files in this repository.

Roadmap and current status

The maintained roadmap records the current milestone, acceptance gates, estimates, evidence, remaining effort, and recommended next work. The planning protocol defines how humans and agents plan tasks and report progress consistently.

The bounded M1.5 packaged capability-discovery milestone, the first stable PyPI publication in M2, and the tested update and capability lifecycle in M3 are complete. M3 includes native/system-first selection, clone bootstrap delegation through the explicitly authorized managed provider lifecycle, reversible desired-capability configuration, the native-Windows Claude Code Git Bash adapter, and exact-artifact upgrade, pin, rollback, and removal evidence. See the maintained roadmap for the acceptance record. The installed agent-tools CLI is the ordinary-user product; the clone-based shared environment remains development/compatibility infrastructure.