Metadata-Version: 2.5
Name: smartnuf-agent-tools
Version: 0.2.0
Summary: Cross-platform capability discovery and diagnostics for coding-agent workstations
Project-URL: Homepage, https://github.com/smartnuf/agent-tools
Project-URL: Documentation, https://github.com/smartnuf/agent-tools/tree/main/docs
Project-URL: Repository, https://github.com/smartnuf/agent-tools
Project-URL: Issues, https://github.com/smartnuf/agent-tools/issues
Project-URL: Changelog, https://github.com/smartnuf/agent-tools/releases
Author: smartnuf contributors
License-Expression: MIT
License-File: LICENSE
Keywords: capability-discovery,coding-agents,developer-tools,diagnostics,workstation-setup
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: <3.14,>=3.11
Provides-Extra: documents
Requires-Dist: openpyxl<4,>=3.1; extra == 'documents'
Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'documents'
Requires-Dist: pillow<13,>=12.3; extra == 'documents'
Requires-Dist: pymupdf<2,>=1.28; extra == 'documents'
Requires-Dist: pypdf<7,>=6.16; extra == 'documents'
Requires-Dist: python-docx<2,>=1.2; extra == 'documents'
Requires-Dist: reportlab<6,>=5; extra == 'documents'
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/getting-started/installation/) through
a trusted package manager, then install the current stable release from PyPI:

```sh
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:

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

Linux or macOS:

```sh
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:

```sh
uv tool upgrade smartnuf-agent-tools
```

Remove the application:

```sh
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:

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

Linux or macOS — install Poppler and Ghostscript:

```sh
"$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](https://github.com/smartnuf/agent-tools/blob/main/docs/platforms.md)
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.

```sh
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](#pin-or-roll-back).

Return to an unpinned core-only installation explicitly:

```sh
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`](#installed-release-details).
- [Pin or roll back an exact release](#pin-or-roll-back).
- [Configure desired capabilities and the Claude Code
  integration](#capability-configuration-and-integrations).
- [Use the source checkout and shared development
  environment](#source-checkout-and-bootstrap).
- Browse the [CLI reference](https://github.com/smartnuf/agent-tools/blob/main/docs/cli-reference.md)
  for current command help, arguments, safety requirements, and exit statuses.
- Read the [platform guide](https://github.com/smartnuf/agent-tools/blob/main/docs/platforms.md),
  [packaging contract](https://github.com/smartnuf/agent-tools/blob/main/docs/packaging.md),
  or [release history](https://github.com/smartnuf/agent-tools/releases).

## Installed release details

Choose a published version from the
[release history](https://github.com/smartnuf/agent-tools/releases). Packaged
releases support Python 3.11 through 3.13. Verify your installed version without
assuming uv's executable directory is already on `PATH`:

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

```sh
"$(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:

```sh
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:

```sh
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:

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

```sh
"$(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:

```sh
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](https://github.com/smartnuf/agent-tools/blob/main/docs/releases/v0.1.2.md)
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.

```sh
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](https://github.com/smartnuf/agent-tools/blob/main/docs/decisions/0006-claude-code-git-bash-integration.md)
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 currently available from `main` pending the next release.

## Source checkout and bootstrap

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

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

Alternatively, download the repository's [main-branch ZIP archive](https://github.com/smartnuf/agent-tools/archive/refs/heads/main.zip), 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:

```powershell
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):

```sh
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:

```powershell
.\scripts\update.ps1
```

or:

```sh
./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`](https://docs.astral.sh/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.

```text
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](https://github.com/smartnuf/agent-tools/blob/main/docs/plan/00-index.md)
records the current milestone, acceptance gates, estimates, evidence, remaining
effort, and recommended next work. The [planning protocol](https://github.com/smartnuf/agent-tools/blob/main/docs/plan/README.md)
defines how humans and agents plan tasks and report progress consistently.

The bounded [M1.5 packaged capability-discovery milestone](https://github.com/smartnuf/agent-tools/blob/main/docs/plan/09-capabilities/README.md),
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.
