Agents: register the MCP server in Claude Code or Codex (runs their official mcp add command), install the
hook and choose its behavior under Agent rules. A hook written by an older Smart Tool shows as outdated, with
what an update changes; updating previews the entry and rewrites only Smart Tool's, after a backup.
Browser control comes with the registration, and with every update for clients where smart-tool is registered:
the official Playwright MCP (pinned in web_adapters/node) is registered as the playwright server, driving the
Chromium Smart Tool installs, headless, with an isolated in-memory profile (no logins of yours) and its files in
~/.smart-tool/data/playwright-mcp. Before registering, Smart Tool starts that server and opens a blank page as an
agent would; where that fails (a corporate policy that forbids remote debugging, a missing browser) nothing is
registered, agents keep reading pages through web_fetch, and the setup screen shows the reason with a retry
button. Pages the agent opens are treated as untrusted: tools a page registers (WebMCP) are never exposed, the
browser cannot open Smart Tool's own pages (every request it makes carries a header the daemon refuses), and
browser_run_code_unsafe, which runs arbitrary JavaScript in the server process, is denied in the client
(permissions.deny in ~/.claude/settings.json, disabled_tools in ~/.codex/config.toml); if it cannot be
denied, the server is not registered. A playwright server you registered yourself is never touched. Remove it with
claude mcp remove playwright -s user / codex mcp remove playwright.
The hook behaviors:
- Redirect (default): the call is not denied. Smart Tool answers it and the answer comes back as the output
of the call the agent made:
smart_search for a search, web_fetch for WebFetch, web_search for WebSearch
(without allowed_domains/blocked_domains). In Claude Code a PostToolUse entry swaps the output (WebFetch and
WebSearch still run natively, their result is replaced); a shell search whose answer is ready within 10 s runs as a
no-op instead, so a grep with no match does not end in exit 1. In Codex the shell search is rewritten to print the
answer from a file. Coexistence with other PreToolUse hooks on Bash: they run in parallel on the same original
input and the host documents no order between their updatedInput. The Smart Tool rewrite is a constant (true /
$null, whatever the search), carries no permission decision (a rival deny/ask still wins) and only applies to a
content search, so a hook that rewrites other commands never meets it; if a rival rewrite of the same search wins,
its command runs and the PostToolUse still swaps the output for the answer. Two other hooks rewriting the same command
must be resolved in the plugin that owns them (the setup audit lists them). When the Smart Tool call fails or is late, the native call and its output stay as they are; a
deny, with the exact call to make, is left only for a search whose query cannot be read from the command. The
decision is a fixed rule, under a millisecond and the same every time: a content search over a project folder (grep -r,
rg, git grep, the Grep tool on a folder) or over more than 20 listed files goes to smart_search, in Bash and
PowerShell alike and also when it is wrapped (bash -c, powershell -Command, timeout, a subshell), looped
(for f in src/*.py), fed by a listing (find -exec grep, xargs, Get-ChildItem | Select-String) or written
as an inline python/node script that walks a folder and matches text; reading or searching known files,
listings, Glob and commands that change files run. The setup screen counts the redirects and what each session
did next. With Block patterns proposed by a
model on (default), the scope model reviews, in the background, bulk reads the rule could not measure and
proposes regex patterns, each checked against the logged calls; a pattern redirects only after you accept it.
- Advise only: the native tool runs; the agent receives the same advice next to the result and decides.
- Off: no routing.
Documentation on edit checks the public functions an edit touches (Python docstrings, JSDoc, Javadoc), in
Claude Code edits and Codex patches. Private (_name, #name, private), nested and override (@Override,
@override) functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle, and a JSDoc above a set of
TypeScript overloads documents the implementation:
- Remind (default): the edit runs and the agent is told which touched functions have no docstring, and which
documented ones changed their signature, with their callers, the tests calling them and the command that runs those tests
(from the code graph, only when it is already cached: the hook never waits for an analysis).
- Require: an edit that leaves a touched function without a docstring is blocked until it adds one.
- Off: no checks.
A documented function edited only in its body is not mentioned. project_manage with action=docs lists the
public functions still without a docstring, for documenting a project that started without them.
Dependency check on edit: an edit of package.json, requirements*.txt or go.mod that adds or changes a dependency lists the OSV advisory IDs of up to 5 of them (exact version, or the lower bound of ^, ~, ~= and >=), answered from a 6 h disk cache or one 2.5 s batch call that sends only package names and versions; when OSV cannot answer, the reminder says the check was skipped and the edit goes on. dependency_mode in config.json: warn (default) or off.
PDFs inside a project are indexed as text with [page N] markers (20 MiB, 300 pages and 20 s per file; a scanned, password-protected or corrupt PDF is skipped with the reason), so smart_search returns the page that holds a passage. Presentations and workbooks (.pptx, .xlsx) are indexed the
same way: text of each slide under [slide N] with the speaker notes under [notes N], each sheet under [sheet NAME] with one
tab-separated line per row (cached formula values; 100,000 rows or 1 MiB of text at most). Older formats (.ppt, .xls,
.xlsm) are not read.
Block patterns waiting for you are shown in one approval panel: 8 per page, the ones that would have blocked
the most logged calls first, a filter over pattern, reason and example, and bulk accept or reject of the selected
rows; each row opens to its reason and example.
Duplicate functions on edit compares the functions an edit writes with the indexed code. Warn (default)
tells the agent when a written function has the same body as an existing one (comments, spacing and docstrings
ignored) or a near-identical one (only local names, strings and numbers changed), with the path and lines of the
original to reuse; it never blocks. Editing a function in place, overloads, tests, generated files and small
functions (under 5 lines or 50 tokens) are not checked. Off disables it.
After editing, project_manage with action=affected_tests lists the tests to run: every test file that imports a
changed file, directly or through other files (git diff against base, default HEAD, untracked files included),
plus changed tests and tests using a pytest fixture whose conftest.py imports the changed code, ordered with the
likeliest failures first, and the command to run them. Changed files are read from disk, so new files and imports
count before the project is reindexed. run_all is true, with
the reason, when a configuration or lockfile changed or a changed code file is outside the import graph. Go is read
by package: a file that imports a package depends on every file of it, so a changed package selects the tests of every
package that imports it (go test ./pkg ...); the Go and Rust documentation and duplicate hooks stay silent.
project_manage with action=setup_audit and a project_root (or python setup_audit.py --project <folder>)
reports what Claude Code and Codex actually load for that folder (settings layers, enabled plugins of both,
hooks, MCP servers, skills, CLAUDE.md and AGENTS.md) and where they collide: several hooks deciding on the same tool in
parallel, hook scripts that do not exist or hide their errors, hooks calling an MCP server that is not configured,
MCP servers that do not start or offer the same tools twice (a gateway re-exposing a server also registered
directly), skills sharing a name or over the description budget, an AGENTS.md only Codex reads, broken @imports
and a Codex instruction chain over 32 KiB. Each finding links the documentation it relies on; nothing is edited,
env and header values never enter the report, and what could not be checked is listed as not verified. A second
run shows what is new and what was resolved. The daemon also runs it on its own for every registered project,
two minutes after it starts and then every 30 minutes (MCP servers shared by several projects are contacted once
and their result reused for 6 hours; Run now always contacts them again), and the setup screen's Setup audit
panel shows each project's last report: findings by severity, what is new, what was resolved, the tokens each MCP
server's tools cost and what was not verified. When a scheduled run finds new errors or warnings, a Windows
notification from the tray names the folder and up to three of them, once per finding, with a button that opens the
panel; manual runs and info findings stay silent.
The agent hears about it without asking for it. setup_audit with mode=last returns the stored report for the
folder (or the nearest audited parent) without auditing again, and fails with what to do when none is stored. On
its first smart_search of a session, and once per folder, the agent also gets one short line (under 100 tokens)
when the stored report holds errors or warnings; a clean report adds nothing. Optionally, Report at session
start on the Setup audit page (Claude Code or Codex) moves that line to the start of every new session: it
previews the exact SessionStart entry, adds it to ~/.claude/settings.json or ~/.codex/hooks.json only after you
confirm (backup first), and Turn off removes only that entry. Codex runs a new hook only after you approve it in
/hooks; until then the page shows "waiting for your approval" and the search keeps repeating the line. It is off by default; while it is on, the search no longer repeats the line. The
hook script (hooks/session_audit.py) only reads the stored report from the running service and prints nothing
when the service is down.