simpleAgentTools 0.1.0

Agent tools in Python (web, files, terminal, browser, memory, cron, and more).

simpleAgentTools

Python agent tools: web, browser (optional Playwright), terminal, files, vision (OpenAI-compatible), todo, clarify, code execution, delegation (callback), memory, session search, cron, messaging hooks, Honcho-like local profile, and skills on disk.

This repository is the simpleAgentTools distribution on PyPI (project page — PyPI normalizes the name to lowercase in URLs). The importable Python package is simpletools. Builds and installs are driven by uv.

Agent toolkit

Tools are registered in simpletools/registry.py (TOOLS). Host code wires a ToolContext and calls ToolRunner.call or registry.call_tool. The CLI can list the same names: simpleAgentTools list (the simpletools command is an alias).

Tool	What it does
browser_back	History back.
browser_click	Click element by @ref.
browser_close	Close browser.
browser_console	Console messages since navigate.
browser_get_images	List images on page.
browser_navigate	Open URL (Playwright).
browser_press	Press key.
browser_scroll	Scroll page.
browser_snapshot	Accessibility-ish snapshot with @refs.
browser_type	Fill input by @ref.
browser_vision	Screenshot + vision model.
clarify	Ask user (TTY) or return non-interactive payload.
cronjob	Cron create/list/update/run/remove.
delegate_task	Subtasks via on_delegate callback.
execute_code	Run Python in subprocess.
honcho_conclude	Append conclusion to facts/profile.
honcho_context	Concatenate matching facts.
honcho_profile	Peer card JSON.
honcho_search	Search stored facts.
memory	File-backed MEMORY.md/USER.md (add/replace/remove/read).
patch	Replace mode: fuzzy multi-strategy match or V4A mode=patch.
process	Manage background processes.
read_file	Read file with line numbers.
search_files	Search by content or filename.
send_message	Pluggable outbound messaging.
session_index	Store session title/summary/body for session_search.
session_search	Search indexed sessions.
skill_manage	Create/update/delete skill.
skill_view	Read SKILL.md or file.
skills_list	List skills.
terminal	Run shell command (optional background).
todo	Session todo list.
vision_analyze	Vision on image file or base64.
web_extract	Fetch URL and return stripped text.
web_search	Search the web (Tavily if TAVILY_API_KEY else DuckDuckGo instant).
write_file	Write file (overwrite).

Development with uv

git clone <repo-url> && cd <repo-directory>
uv sync --all-extras          # install runtime + browser extra + dev (pytest, ruff)
uv run python -m unittest discover -s tests -v
uv run ruff check simpletools tests
uv run ruff format simpletools tests

Lockfile: uv.lock is committed so CI and installs stay reproducible. Refresh after dependency edits:

uv lock

Install (users)

uv tool install simpleAgentTools
# or
uv pip install simpleAgentTools
# optional browser automation
uv pip install "simpleAgentTools[browser]"
playwright install chromium

PyPI release

1. Bump version in pyproject.toml.

2. Run uv lock (if dependencies changed) and uv build.

3. Local publish: use make publish-doppler. Put a PyPI API token in Doppler as PYPI_TOKEN (recommended), or UV_PUBLISH_TOKEN, or V_PUBLISH_TOKEN (SimpleAgents’ publish-python alias). That target runs preflight and the real upload inside one doppler run, so uv publish --dry-run and uv publish both see the token—no interactive “Enter username (__token__)…” prompts. Doppler still needs which project and config to load. Use any one of these:

   • Recommended: from the repo root run doppler setup, pick your Doppler project and config (e.g. dev). That stores the mapping for this directory so plain doppler run works.
   • Environment: export DOPPLER_PROJECT=your-project and export DOPPLER_CONFIG=dev (or prd), then make publish-doppler.
   • Make flags: make publish-doppler DOPPLER_OPTS='--project your-project --config dev' (short form: -p / -c, e.g. DOPPLER_OPTS='-p your-project -c dev').

   Put PYPI_TOKEN (or UV_PUBLISH_TOKEN / V_PUBLISH_TOKEN) in that Doppler config. See the Doppler docs for CLI and secrets setup (including -p / --project and -c / --config on doppler run).

4. CI publish: GitHub Actions .github/workflows/publish.yml runs on release published and passes PYPI_TOKEN to uv (falls back to PYPI_API_TOKEN if PYPI_TOKEN is unset). Add one of those repository secrets with your PyPI token.

Trusted publishing (OIDC) can be enabled later via uv publish --trusted-publishing always once the PyPI project is configured for it.

Usage

from pathlib import Path
from simpletools import ToolRunner

r = ToolRunner(cwd=Path("."))
print(r.call("web_search", query="Python 3.12"))
print(r.call("memory", action="add", target="memory", content="Uses uv for packaging"))

CLI:

simpleAgentTools list
simpleAgentTools call memory --args '{"action":"read"}'

Configuration

Environment highlights: FIRECRAWL_API_KEY / FIRECRAWL_API_URL, TAVILY_API_KEY, EXA_API_KEY, optional SIMPLETOOLS_WEB_BACKEND (firecrawl, tavily, or exa), OPENAI_* for vision, SIMPLETOOLS_DATA_DIR, SIMPLETOOLS_FILE_READ_MAX_CHARS, SIMPLETOOLS_SKILLS_DIR.

Behavior notes: multi-strategy fuzzy patch replace, optional mode="patch" V4A hunks, file read guards (device blocklist, char cap, repeat-read loop), configurable web search backends, file-backed memory (memories/MEMORY.md + USER.md, § entries), session todos with content/status.

Acknowledgments

All of the tools in this repository are inspired by Hermes from NousResearch. The intent of this project is to simplify tool usage for external agents as well.

Nothing but love to the NousResearch team.