use-agent 1.0.0b1__tar.gz

use_agent-1.0.0b1/.github/workflows/deploy.yaml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

use_agent-1.0.0b1/.github/workflows/testing.yaml

@@ -0,0 +1,36 @@
+name: Testing
+on:
+  push:
+    branches: ["**"]
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+    tags-ignore: ["*"]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run coverage run && uv run coverage report

use_agent-1.0.0b1/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage
+.coverage.*
+.pytest_cache/
+.ruff_cache/
+
+# Local secrets & private config — NEVER commit
+credentials.json
+token.json
+config.toml
+*.pem
+.env
+.env.*
+!.env.example
+!config.example.toml

use_agent-1.0.0b1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.25
+    hooks:
+      - id: tombi-format

use_agent-1.0.0b1/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`use-agent` is a Claude Agent that triages a Gmail inbox for
+unsolicited sales email, replies in the user's voice, and archives
+the thread. It's built on the Claude Agent SDK; Gmail API operations
+are exposed as tools via an in-process SDK MCP server.
+
+Python 3.14, uv, hatchling + hatch-vcs, ruff. Runtime deps:
+`claude-agent-sdk`, `google-api-python-client`,
+`google-auth-oauthlib`, `jinja2`, `rich`.
+
+## Commands
+
+```bash
+uv sync                               # install runtime + dev deps
+uv run use-agent auth                 # one-time Gmail OAuth
+uv run use-agent run --dry-run        # classify only
+uv run use-agent run                  # full run: reply + archive
+uv run use-agent run --daemon --interval 30m --logfile run.log
+uv run use-agent run --json | jq .    # stdout is pure JSON
+
+uv run ruff check .
+uv run ruff format --check .
+uv run coverage run                   # pytest under coverage
+uv run coverage report
+```
+
+`ANTHROPIC_API_KEY` is required for any `run`.
+
+## Architecture
+
+The data flow is deliberately narrow. All user-specific context enters
+through `config.toml`; everything else is derivable from the code.
+
+```
+cli.main → Settings.load() → agent.run(settings, reporter)
+                                 ↓
+                     _render_system_prompt(settings)
+                                 ↓
+                     claude_agent_sdk.query(
+                         prompt=<user-prompt>,
+                         options=ClaudeAgentOptions(
+                             system_prompt=<rendered>,
+                             mcp_servers={'gmail': <built from GmailClient>},
+                             allowed_tools=[mcp__gmail__search, ...],
+                             setting_sources=[],  # hermetic
+                             model=<from config>,
+                         ),
+                     )
+                                 ↓
+                      streaming AssistantMessage/TextBlock
+                                 ↓
+                        reporter.on_text(...)   (→ narration logger)
+                                 ↓
+                        reporter.finish()       (→ stdout: table/JSON)
+```
+
+Key module responsibilities:
+
+- `gmail.GmailClient` is the only module that touches the Gmail REST
+  API. It returns frozen `Message` dataclasses so tool output stays
+  JSON-friendly.
+- `tools.build_mcp_server(client)` wraps four `@claude_agent_sdk.tool`
+  closures (`search`, `get_message`, `reply`, `archive_and_mark_read`)
+  over a `GmailClient` and returns an SDK MCP server. The closure
+  approach lets the tools share state without a module-global client.
+- `agent.run()` is the orchestration entry point: renders the system
+  prompt, builds the tool server, configures `ClaudeAgentOptions`,
+  streams responses into the `Reporter`, and returns an exit code.
+  Python does no per-message logic — the agent drives the loop.
+- `reporter.Reporter` owns all output. **`on_text` never writes to
+  stdout**; narration goes to the `use_agent.narration` logger
+  instead. `finish()` parses the last ` ```json ` fenced block from
+  the buffered text and renders it as a Rich table (`pretty`),
+  pipe-delimited ASCII (`plain`), or a JSON document (`json`).
+- `settings.Settings` is a frozen dataclass loaded from
+  `config.toml` (path via `USE_AGENT_CONFIG` env var or
+  `~/.config/use-agent/config.toml`). If `[search] query` is omitted,
+  a default `in:inbox is:unread` query is built from the safelist
+  domains as `-from:<domain>` filters.
+
+### Prompts are Jinja2 templates
+
+`use_agent/prompts/classifier.md` and `reply.md` are Jinja2 templates
+rendered at startup. Context injected by `agent._render_context`:
+`user_name`, `organization`, `safelist_domains`, `vendor_names`,
+`voice_guidelines`, `reply_footer`, plus two pre-rendered strings
+(`voice_block`, `footer_block`, `footer_instruction`). The
+pre-rendered strings exist because the repo's pre-commit Markdown
+formatter strips blank lines inside `{% if %}` blocks — avoid Jinja
+control flow in prompt Markdown; pre-render composite blocks in
+Python and inject them as single `{{ ... }}` substitutions.
+
+`reply_footer` is itself a Jinja string (may reference `{{ user_name
+}}` etc.) and is rendered once in `_render_context` before being
+injected into the reply template.
+
+### Editing agent behavior without touching Python
+
+Most behavior tweaks belong in `config.toml` or the prompt Markdown:
+
+- New classification signal → edit `prompts/classifier.md`
+- Change reply voice / add a template → edit `prompts/reply.md`
+- Add a vendor exemption → `[vendors] names` in `config.toml`
+- Add a safelisted domain → `[safelist] domains` in `config.toml`
+- Change footer text / disable footer → `[voice] footer` (or `""`)
+- Change model → `[agent] model`
+
+Python changes are only needed when the set of tools, output modes,
+CLI flags, or Gmail operations needs to change.
+
+### Hermetic SDK configuration
+
+`agent.run()` passes `setting_sources=[]`, `settings=None`,
+`skills=None` to `ClaudeAgentOptions` so the agent never merges in
+the developer's `~/.claude/settings.json`, project-level Claude Code
+config, plugins, or auto-discovered skills. The only MCP server the
+agent sees is our Gmail one; the only tools it can call are the four
+in `tools.ALLOWED_TOOLS`. Keep it that way — preserving isolation is
+part of the trust model.
+
+### Threaded replies
+
+Gmail only collapses a reply into the original conversation when all
+three are correct: `In-Reply-To: <original Message-ID>`,
+`References: <chain> <original Message-ID>`, and `threadId` in the
+`users.messages.send` request. `gmail.GmailClient.reply` assembles
+all three from the fetched original. Don't regress this — dropping
+`threadId` or the headers silently demotes replies into new threads.
+
+### Output contract
+
+The agent is prompted to emit exactly one fenced ` ```json ` block
+containing `{"results": [...]}`. The reporter's `_extract_summary`
+walks the buffered text from the end backwards looking for the last
+parseable JSON fence with a `results` array (or a bare list of rows
+with a `classification` key). If the agent forgets to emit the
+block, `finish()` returns exit code 1 — treat this as a real error.
+
+### Logging
+
+| Logger | Level | Purpose |
+|---|---|---|
+| `use_agent.*` | INFO | Lifecycle (run start, daemon tick) |
+| `use_agent.narration` | INFO | Agent's running commentary (buffered text) |
+| `use_agent.tools` | DEBUG | Per-tool-call Gmail operations |
+| `claude_agent_sdk` | WARNING | Pinned; SDK INFO is too chatty |
+
+All handlers write to stderr (plus the `--logfile` target when set)
+so stdout stays pure in `--json` mode.
+
+## Conventions
+
+- **Module-level imports only.** A pre-commit hook rejects `from
+  pathlib import Path` / `from typing import Any` style imports —
+  use `import pathlib` / `import typing`, then `pathlib.Path(...)`,
+  `typing.Any`.
+- Ruff: 79-char lines, single quotes, `py314` target. Config lives
+  in `pyproject.toml`.
+- No compound shell commands: each `Bash` call is one command
+  (repo-wide preference, not project-specific, but still applies).
+- `credentials.json`, `token.json`, and `config.toml` are all
+  gitignored. The repo itself contains no identifying information;
+  `config.example.toml` uses placeholder values only.
+
+## Version
+
+`use_agent.__version__` is read at runtime via
+`importlib.metadata.version('use-agent')`, with a `0.0.0+unknown`
+fallback. `[project] version` is pinned in `pyproject.toml`; hatch-vcs
+is configured but not currently generating a version file.

use_agent-1.0.0b1/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: use-agent
+Version: 1.0.0b1
+Summary: Claude Agent that triages unsolicited sales email in Gmail.
+Project-URL: Homepage, https://github.com/gmr/use-agent
+Author-email: "Gavin M. Roy" <gavinmroy@gmail.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.14
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: google-api-python-client>=2.150
+Requires-Dist: google-auth-httplib2>=0.2
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: jinja2>=3.1
+Requires-Dist: rich>=13.9
+Description-Content-Type: text/markdown
+
+# use-agent
+
+A Claude Agent that scans a Gmail inbox for unsolicited sales email,
+replies in the user's voice, and archives the thread.
+
+Built on the [Claude Agent SDK][sdk]. Gmail API operations are
+exposed to the agent as tools via an in-process MCP server. All
+user-specific configuration lives in a single `config.toml` — the
+repo itself contains no identifying information.
+
+[sdk]: https://docs.claude.com/en/api/agent-sdk/overview
+
+## What it does
+
+1. Searches the inbox for unread messages from outside senders (the
+   query is built from the safelist in `config.toml`).
+2. Fetches each candidate and checks whether the thread already has
+   a sent reply.
+3. Classifies each message using the rules in
+   [`use_agent/prompts/classifier.md`](use_agent/prompts/classifier.md).
+4. For every `COLD_SALES` hit, generates a reply using the rules in
+   [`use_agent/prompts/reply.md`](use_agent/prompts/reply.md).
+5. Sends the reply as a proper threaded reply (`In-Reply-To` and
+   `References` headers set from the original message, same
+   `threadId` passed to the send call), marks the original as read,
+   and archives the thread.
+6. Emits a summary of everything examined.
+
+Unlike the Claude Cowork Gmail connector, this agent sends actual
+replies rather than drafts and can archive threads.
+
+## Install
+
+Requires Python 3.14 and [`uv`][uv].
+
+```bash
+uv sync
+```
+
+This installs the runtime deps (`claude-agent-sdk`,
+`google-api-python-client`, `google-auth-oauthlib`, `jinja2`,
+`rich`) and the dev tools (`pytest`, `ruff`, `coverage`). The
+console script `use-agent` lands at `.venv/bin/use-agent`.
+
+[uv]: https://docs.astral.sh/uv/
+
+## Configure
+
+Copy `config.example.toml` to `~/.config/use-agent/config.toml` (or
+point `USE_AGENT_CONFIG` at any path) and fill in the sections
+below. The real `config.toml` is gitignored; only the example is
+committed.
+
+```toml
+[user]
+name = "Your Name"
+organization = "Your Company"
+
+[safelist]
+# Never classified as cold sales, and auto-appended as -from:<d>
+# filters to the Gmail search query.
+domains = ["example.com", "example.net"]
+
+[vendors]
+# Exempt from cold-sales classification when the message is about
+# billing / renewal / account management. Vendor reps pitching
+# upsells still get flagged.
+names = ["AWS", "GitHub"]
+
+[voice]
+# Rendered as a bulleted list under "## Voice Guidelines" in the
+# reply prompt.
+guidelines = [
+    "1-2 sentences maximum, never more",
+    "No apology for declining",
+    "Blunt but not hostile",
+    "Always ends with a remove request (except `specific_decline`)",
+]
+# Footer appended to every reply. May reference Jinja variables.
+# Set to "" to disable.
+footer = """\
+---
+This email was flagged as unsolicited sales outreach and this reply
+was sent on {{ user_name }}'s behalf by an automated assistant.\
+"""
+
+[agent]
+# Claude model that drives the agent.
+model = "claude-haiku-4-5-20251001"
+
+[search]
+max_results = 25
+# Override the Gmail query. If omitted, the query is built from
+# "in:inbox is:unread" plus a -from:<domain> filter for every
+# safelist entry.
+# query = "in:inbox is:unread"
+```
+
+Both `classifier.md` and `reply.md` are Jinja2 templates; their
+contents are rendered at startup using the values above. Editing
+them changes agent behavior without any Python change.
+
+### Environment variable overrides
+
+| Variable                | Purpose                          | Default                                |
+| ----------------------- | -------------------------------- | -------------------------------------- |
+| `USE_AGENT_CONFIG`      | Path to `config.toml`            | `~/.config/use-agent/config.toml`      |
+| `USE_AGENT_CREDENTIALS` | Path to OAuth client secret      | `~/.config/use-agent/credentials.json` |
+| `USE_AGENT_TOKEN`       | Path to stored OAuth token       | `~/.config/use-agent/token.json`       |
+| `XDG_CONFIG_HOME`       | Base for the above defaults      | `~/.config`                            |
+| `ANTHROPIC_API_KEY`     | Required by the Claude Agent SDK | —                                      |
+
+## Gmail OAuth setup
+
+1. In Google Cloud Console, pick a project that has the Gmail API
+   enabled and create an **OAuth 2.0 Client ID** of type _Desktop
+   app_.
+2. Download the client secret as `credentials.json`. Drop it at
+   `~/.config/use-agent/credentials.json` (or point
+   `USE_AGENT_CREDENTIALS` at wherever you saved it).
+3. Run the one-time authorization flow:
+
+   ```bash
+   uv run use-agent auth
+   ```
+
+   This opens a browser, completes the OAuth consent, and stores
+   the refresh token at `~/.config/use-agent/token.json` (mode
+   `0600`). Refreshes happen automatically on subsequent runs.
+
+The only scope requested is
+`https://www.googleapis.com/auth/gmail.modify`, which covers read,
+label changes (archive, mark read), and send — nothing destructive.
+
+## Run
+
+```bash
+# One-shot
+uv run use-agent run                    # process the inbox
+uv run use-agent run --dry-run          # classify but don't reply/archive
+uv run use-agent run --max 10           # examine at most 10 candidates
+uv run use-agent run --query 'is:unread label:followup'  # custom query
+
+# Output format (default is pretty)
+uv run use-agent run --plain            # no ANSI, pipe-delimited table
+uv run use-agent run --json             # stdout is a single JSON document
+
+# Daemon mode
+uv run use-agent run --daemon                   # loop forever, every 15m
+uv run use-agent run --daemon --interval 30m    # 30-minute cadence
+uv run use-agent run --daemon --interval 2h     # every two hours
+# Intervals accept s / m / h / d suffixes, or raw seconds.
+
+# Logging
+uv run use-agent -v run                         # DEBUG level logs to stderr
+uv run use-agent --logfile run.log run --daemon # tee logs to a file
+```
+
+### Output modes
+
+- **`--pretty` (default):** Rich table on stdout, colour-coded
+  classification, auto-wrapping columns. Running commentary ("Now
+  fetching message…", "Classifying…") streams on stderr via the
+  `use_agent.narration` logger.
+- **`--plain`:** No ANSI. A pipe-delimited ASCII table hits stdout —
+  safe to pipe into `column`, `less`, `tee`, etc.
+- **`--json`:** A single JSON document on stdout:
+  `{"results": [{...}, ...]}`. All logs and narration go to stderr,
+  so `use-agent run --json | jq '.results[].classification'` is
+  clean.
+
+Exit code is `0` on a successful run with a parsed summary, `1` if
+the agent produced no recognizable summary block.
+
+### Daemon mode
+
+`--daemon` loops until Ctrl-C. Each iteration spins up a fresh
+reporter and agent run; exceptions inside an iteration are logged
+and the loop continues. Pair with `--logfile` for long-running
+deployments:
+
+```bash
+use-agent --logfile ~/logs/use-agent.log run --daemon --interval 30m
+```
+
+### Logging
+
+The CLI emits structured logs to stderr (and, with `--logfile`, to
+the named file too). Loggers:
+
+| Logger                | Level   | Content                                                 |
+| --------------------- | ------- | ------------------------------------------------------- |
+| `use_agent.*`         | INFO    | High-level lifecycle (agent run start/end, daemon tick) |
+| `use_agent.narration` | INFO    | Running commentary from the agent                       |
+| `use_agent.tools`     | DEBUG   | Every Gmail tool call (search, get, reply, archive)     |
+| `claude_agent_sdk`    | WARNING | Pinned to WARN; SDK's INFO is too chatty                |
+
+`-v` / `--verbose` bumps the root level to DEBUG, surfacing every
+tool invocation.
+
+## Isolation from your Claude Code setup
+
+The agent is deliberately hermetic. `ClaudeAgentOptions` is
+constructed with:
+
+- `setting_sources=[]` — don't merge in `~/.claude/settings.json`,
+  any `.claude/settings.local.json`, or project-level settings
+- `settings=None` — no specific settings file
+- `skills=None` — no auto-discovered skills
+- `mcp_servers={'gmail': <our server>}` — only our Gmail MCP server
+- `allowed_tools=[...]` — only the four Gmail tools we expose
+
+Nothing from your Claude Code dev environment — custom agents,
+plugins, MCP servers, hooks, skills — can leak into this agent run.
+
+## How the agent decides
+
+Classification is rule-based, not sentiment-based. Each message
+accumulates points from STRONG (2pt) and WEAK (1pt) signals — meeting
+CTA, intro formulas, outreach-tooling domains, flattery hooks, fake
+`Re:` threads, false premises about the org, etc. A total score of
+`>= 3` means `COLD_SALES`. Vendor billing, newsletters, transactional
+notifications, threads that already have a sent reply, and senders
+from safelisted domains are hard-exempt regardless of score.
+
+Replies are one of four modes:
+
+- `hard_remove` — the default. A curt "Not interested, please remove."
+- `hard_remove_with_correction` — when the sender got a fact about
+  the org wrong; lead with a brief factual correction, then remove.
+- `specific_decline` — reserved for reps of current vendors.
+- `none` — not cold sales; skip.
+
+Every reply optionally ends with the `footer` from `config.toml`,
+which is itself a Jinja string (so it can interpolate `{{
+user_name }}` etc.).
+
+## How replies are threaded
+
+Gmail treats a reply as part of the original thread only when the
+send request is correctly chained. `gmail.py`:
+
+1. Pulls the original `Message-ID` and `References` headers.
+2. Builds a new `EmailMessage` with `In-Reply-To: <original-id>` and
+   `References: <chain> <original-id>`.
+3. Subject is prefixed with `Re: ` unless it already starts with
+   `Re:`.
+4. Base64url-encodes the MIME message and calls
+   `users.messages.send` with the encoded body **and** the original
+   `threadId`.
+
+That combination is what Gmail's UI uses to collapse the reply into
+the same conversation view the original arrived in.
+
+## License
+
+BSD-3-Clause.