agent-fileview 0.1.0__py3-none-any.whl

agent_fileview-0.1.0.dist-info/METADATA

@@ -0,0 +1,302 @@
+Metadata-Version: 2.5
+Name: agent-fileview
+Version: 0.1.0
+Summary: Read-only file viewer that turns a coding agent's file paths into links you can open on your phone over Tailscale
+Project-URL: Repository, https://github.com/tbb300/agent-fileview
+Project-URL: Issues, https://github.com/tbb300/agent-fileview/issues
+Project-URL: Changelog, https://github.com/tbb300/agent-fileview/blob/main/CHANGELOG.md
+Author: Tom Barrett
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude code,codex,file viewer,tailscale
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Requires-Dist: markdown>=3.5
+Requires-Dist: pygments>=2.17
+Description-Content-Type: text/markdown
+
+# agent-fileview
+
+Coding agents like Claude Code and Codex mention files all the time:
+`src/app.py:42`, `reports/summary.md`, `logs/run.log`. When the agent runs
+on a remote Linux box and you are reading its output on your phone, those
+paths are dead text.
+
+agent-fileview turns them into links. It is a small read-only web server
+on the box, reachable only over your Tailscale tailnet. A file's URL is the
+tailnet name plus the file's absolute path:
+
+```
+https://box.your-tailnet.ts.net:8780/home/you/project/src/app.py#L42
+```
+
+Tap it and the file opens on your phone. Markdown is rendered, code is
+highlighted with numbered, linkable lines, and notebooks, CSV and logs get
+their own views. You then add a short rule to `CLAUDE.md` or `AGENTS.md`,
+and the agents start writing these links themselves.
+
+## Who this is for
+
+You run coding agents such as Claude Code, Codex, OpenCode or Aider on a
+Linux box: a home server, a cloud VM or a GPU workstation. They work
+unattended or half-attended, often several at once. You watch and steer them
+from somewhere else. That might be Claude Code's remote control in the
+Claude mobile or web app, a tmux or screen session over SSH or mosh from a
+phone client such as Termius, Blink or JuiceSSH, or an orchestrator that
+runs agents in tmux panes.
+
+Those views show the agent's text but not the files it names. Its reports,
+plans, diffs, logs and notebooks stay on the box, and the paths in the
+transcript are dead text. The Claude app even turns a `file:line` path into
+a claude.ai link that does not open the file. agent-fileview serves those
+files read-only over your tailnet, so each path can become a link that opens
+on your phone. One rule in `CLAUDE.md` or `AGENTS.md` makes agents write
+plain markdown links and never wrap them in backticks, so the mobile apps
+make them tappable.
+
+## Quickstart
+
+```bash
+uv tool install agent-fileview          # or: pipx install agent-fileview
+agent-fileview install                  # user service + tailscale serve
+agent-fileview rule >> ~/.claude/CLAUDE.md
+```
+
+To try it without installing, `uvx agent-fileview link .` prints a URL. The
+service needs a lasting install, because `uvx` environments live in a cache
+that can be cleaned.
+
+The package installs two commands: `agent-fileview`, and `fileview` as a
+short alias. The examples below use the alias.
+
+`agent-fileview install` does the following:
+
+1. writes `~/.config/fileview/config.toml` (mode 0600) if it is missing;
+2. writes (mode 0644), enables and restarts the systemd user unit
+   `agent-fileview.service`. An existing `fileview.service` from an earlier
+   install keeps its name;
+3. runs `tailscale serve --bg --https=8780 unix:<socket>`. If tailscale
+   refuses on permissions, it asks before retrying with `sudo`. If the port
+   already serves something else, it stops unless you pass `--force`;
+4. prints the tailnet logins it can see and suggests `allowed_logins`;
+5. prints the agent rule.
+
+If lingering is off, it prints the `loginctl enable-linger` command that
+keeps the service running after you log out. To let `tailscale serve` run
+without sudo, run `sudo tailscale set --operator=$USER` once.
+
+To link a file yourself, run `fileview link path/to/file --line 42`.
+`fileview uninstall` reverses `install` and keeps your config.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `fileview serve` | Runs the server on the unix socket. The unit runs this. `--tcp PORT` listens on 127.0.0.1 instead, for development. |
+| `fileview install` | Installs, enables and restarts the user unit, checks linger and exposes the socket with `tailscale serve`. `--yes` uses sudo without asking. `--no-tailscale` skips tailscale. `--force` replaces another route on the port. |
+| `fileview uninstall` | Removes the unit, and the `tailscale serve` route if it points at fileview (`--force` removes any route on the port). |
+| `fileview link PATH...` | Prints each path's URL. `--line N` adds `#LN` (files only). It warns when the server would refuse a path, and exits 1 if any path is missing or would be refused. |
+| `fileview rule` | Prints the CLAUDE.md / AGENTS.md snippet for your config, listing only roots that pass the checks. |
+
+## Configuration
+
+`~/.config/fileview/config.toml`:
+
+```toml
+host = "box.your-tailnet.ts.net"   # default: Self.DNSName from `tailscale status --json`
+port = 8780                        # HTTPS port tailscale serves on
+roots = ["~"]                      # directories or globs to serve
+allow = [                          # dot-paths exempt from the dot rule
+    "~/.claude/CLAUDE.md",
+    "~/.claude/projects/*/memory/",
+    "~/.codex/AGENTS.md",
+]
+# socket = "/run/user/1000/fileview/fileview.sock"
+# timezone = "Europe/London"       # listing times; default local
+# allowed_logins = ["you@example.com"]   # see "Who can reach it"
+```
+
+Environment variables override the file: `FILEVIEW_HOST`,
+`FILEVIEW_PORT`, `FILEVIEW_ROOTS` and `FILEVIEW_SOCKET` replace a value,
+`FILEVIEW_ALLOW` appends to the allowlist, and `FILEVIEW_TZ` sets the
+timezone. List values are colon-separated. `FILEVIEW_CONFIG` points at a
+different file. Restart the service after editing:
+`systemctl --user restart fileview`.
+
+The config file must be owned by you and not group- or other-writable.
+Roots, allow globs and the socket must be absolute after `~` and `$VAR`
+expansion, and an unset variable is an error.
+
+Allow entries exist only to exempt specific dot-paths, so each entry must
+follow these rules:
+
+- It names at least one dot-directory literally, such as `.claude`.
+- Every component down to the last literal dot-directory is literal.
+- Below that, a wildcard component is either a bare `*` or starts with a
+  literal non-dot character, such as `p*`.
+- Something literal follows the last dot-directory, so the entry cannot
+  cover a whole dot-directory.
+
+`~/.claude/CLAUDE.md`, `~/.claude/projects/*/memory/` and
+`~/.config/systemd/user/` pass. `~/.claude/`, `~/.claude/*`, `~/*/`,
+`~/?ssh/k/` and `~/[.]ssh/k/` are refused. The server also never lets a
+wildcard match a dot name, so `*` in `projects/*/memory/` cannot reach
+`projects/.hidden/memory/`.
+
+A root may be a glob such as `/srv/data/*`, and each match is vetted on its
+own. A glob helps when a shared parent directory fails the ownership rule
+below but your directories inside it pass.
+
+## Security model
+
+agent-fileview shows files from a box that holds source code and
+credentials, so it refuses by default. Read the first two points before you
+install it.
+
+- **Who can reach it.** `tailscale serve` does no per-user authentication.
+  Every device that your tailnet ACLs let reach this machine on the port can
+  read everything under the roots. Restrict it with tailnet ACLs, or set
+  `allowed_logins`. With that list set, each request must carry a
+  `Tailscale-User-Login` header naming a listed login, or it gets 403.
+  Tailscale sets that header for devices owned by a user. Tagged devices
+  and local clients send none, so they are refused once the list is set.
+  Logins compare case-insensitively.
+- **Name rules are a heuristic.** fileview denies dot-paths and names that
+  look like credentials, but a secret in `notes.md` or `config.yaml` under a
+  root is readable. Choose roots that hold only what you would show on a
+  phone.
+- **Socket.** The server listens only on a unix socket at
+  `$XDG_RUNTIME_DIR/fileview/fileview.sock`, mode 0600, in a 0700
+  directory. Other local users cannot connect. `tailscaled` runs as root
+  and proxies HTTPS to it. A process running as you can open the socket and
+  send any `Tailscale-User-Login` header it likes. That grants nothing new,
+  because such a process can already read your files.
+- **Read-only.** GET and HEAD only, and every other method gets 405. The
+  unit runs with `NoNewPrivileges`, `ProtectSystem=strict` and a read-only
+  view of `/`.
+- **Checked opens.** Every file is opened with `O_NOFOLLOW | O_NONBLOCK`,
+  and its real path is read back from `/proc/self/fd`. The requested path
+  and the real path must both pass every rule, and bytes come only from that
+  checked fd. Swapping in a symlink after the check does not redirect the
+  read. Only regular files and directories are served.
+- **Roots.** Every request re-checks each root. A root must be a real
+  directory (not a symlink), owned by you, with no group or other write
+  bit, and with the inode it had when first accepted. A failing root is
+  skipped with one log line, and the others keep working.
+- **No JavaScript.** Every response carries
+  `Content-Security-Policy: default-src 'none'; img-src 'self' data:;
+  style-src 'unsafe-inline'; form-action 'none'; base-uri 'self';
+  frame-ancestors 'none'`, plus `X-Content-Type-Options: nosniff` and
+  `Referrer-Policy: no-referrer`. `.html` files are served as text. SVG is
+  served raw under the same CSP, so scripts inside it do not run.
+- **Escaping.** File names, paths and contents are escaped everywhere.
+  Raw HTML in markdown is escaped. Links in markdown keep only http,
+  https, mailto and relative URLs, checked after decoding HTML entities.
+- **Bounded work.** Markdown renders in a child process limited to 2 s of
+  CPU, 1 GiB of memory and 3 s of wall time, and the child is killed if the
+  client disconnects. Idle connections close after 30 s.
+
+### What it refuses
+
+Every refusal is a plain 404, so a probe cannot tell "denied" from
+"missing".
+
+- Paths outside the roots, and any `.` or `..` segment.
+- Any path component starting with `.` (`.ssh`, `.aws`, `.env`, `.git`,
+  ...), except paths in the allowlist. Dot-components below an allowlisted
+  directory are still refused.
+- These files, even inside the allowlist: `auth.json`, `.credentials.json`,
+  `credentials*`, `hosts.yml`, `.netrc`, `.pgpass`, `history.jsonl`,
+  `.docker/config.json`, `.kube/config`, `settings.json` and
+  `settings.local.json` under `.claude/`, and `*.jsonl` session transcripts
+  under `.claude/projects/`.
+- Directories named exactly `secret(s)`, `token(s)`, `credential(s)` or
+  `password(s)`, case-insensitively. `tokenizer/` passes.
+- Files matching `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_*`,
+  `*credential*`, `*secret*`, `*token*`, `*password*` or `*.kdbx`,
+  case-insensitively.
+- Extensions outside: md txt log json jsonl csv tsv py pyx js ts c h cpp
+  toml yaml yml sql sh html service lock ipynb cfg ini example svg png jpg
+  jpeg gif webp pdf. Databases, parquet, pickles and other binary data are
+  never served.
+- Extensionless files unless they start with `#!` and are valid UTF-8.
+- Text over 20 MB and binaries over 50 MB.
+
+## What you see
+
+| Type | View |
+|---|---|
+| `.md` | Rendered, up to 1 MiB. Relative links and images work. |
+| Code and text | Highlighted with numbered lines. Each line has an `#L<n>` anchor, and the gutter is not copied with the code. `.py` files get an outline. Files over 2 MiB are not highlighted. |
+| `.ipynb` | Cells in order. Markdown is rendered, code highlighted, text outputs shown and image outputs omitted. |
+| `.csv`, `.tsv` | A table of the first 2,000 rows. |
+| `.log` | The last 5,000 lines, numbered as in the file. |
+| Images, SVG, PDF | Served raw. |
+| Directories | Newest first, with sizes and times. |
+
+`?raw=1` returns a text file as `text/plain`. Pages are dark, and
+`?theme=light` switches one page to light. Range anchors such as `#L10-L20`
+are not supported, because highlighting a range needs JavaScript.
+
+## Screenshots
+
+<!-- Placeholders: add images under docs/screenshots/ before publishing. -->
+
+| Listing | Markdown | Code | Notebook |
+|---|---|---|---|
+| *(screenshot)* | *(screenshot)* | *(screenshot)* | *(screenshot)* |
+
+## Limits
+
+- Linux only. It needs `/proc/self/fd`, systemd user units and Tailscale
+  with `tailscale serve`.
+- Python 3.11 or newer.
+- One user per service. Each user who wants links runs their own instance
+  on their own port.
+- No search, no editing and no uploads, by design.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check
+uv run pytest -q
+uv run fileview serve --tcp 8141     # then open http://127.0.0.1:8141/
+```
+
+## Releasing
+
+Releases go to PyPI as `agent-fileview` through Trusted Publishing, so no
+API token exists anywhere.
+
+One-time setup:
+
+1. On PyPI, add a pending trusted publisher for project `agent-fileview`
+   with owner `tbb300`, repository `agent-fileview`, workflow
+   `release.yml` and environment `pypi`.
+2. On GitHub, create the environment `pypi` under Settings → Environments.
+   Add yourself as a required reviewer, so each release waits for approval.
+
+For each release:
+
+1. Set `version` in `pyproject.toml`, the only version source, and add a
+   CHANGELOG entry.
+2. Check locally with `uv build` and `uvx twine check --strict dist/*`.
+3. Commit, then tag and push: `git tag v0.1.1 && git push origin v0.1.1`.
+
+The `Release` workflow runs ruff and the tests, checks that the tag equals
+`v` plus the pyproject version, builds, and runs `twine check`. A separate
+`publish` job then uploads through OIDC. Only that job holds
+`id-token: write`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

agent_fileview-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fileview/__init__.py,sha256=50rboCPRrYdla8v3cd8CrxSJ4lSk14hKJjdi1WU_gyo,317
+fileview/__main__.py,sha256=x_P85HydUuzwgXFjW_d7zIkzgfz1jBGzyrdIrqaU5Jo,56
+fileview/cli.py,sha256=2vj_aHMcu6mRsodGuPybftRA7uNUOPdQrDNyoNBjy54,15137
+fileview/config.py,sha256=hs3TWIuDScS6lHyIXeKfqXGqDyC4brHAkaZIOs8edv0,10660
+fileview/server.py,sha256=NzzOxlq3bHx495fgl5AnTcar4qtzuuIFfXpTLByJfag,43473
+agent_fileview-0.1.0.dist-info/METADATA,sha256=O7fknPhor9Dv3OoL7ROUhxserbHOUH0uitbo3FW9_F4,14122
+agent_fileview-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_fileview-0.1.0.dist-info/entry_points.txt,sha256=czrwWg2N7d3MwVlJ7gU4ZqVjKiI8sRo36ccB4wyufVY,82
+agent_fileview-0.1.0.dist-info/licenses/LICENSE,sha256=8R5sjHvSIabREa9W5Zuskddwbx0l0UUW3IsRIg1OO0I,1068
+agent_fileview-0.1.0.dist-info/RECORD,,

agent_fileview-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_fileview-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agent-fileview = fileview.cli:main
+fileview = fileview.cli:main

agent_fileview-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Barrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fileview/__init__.py

@@ -0,0 +1,9 @@
+"""Read-only file viewer for agents' links, served over Tailscale."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# pyproject.toml is the one version source; installs record it in metadata.
+try:
+    __version__ = version("agent-fileview")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

fileview/__main__.py

@@ -0,0 +1,3 @@
+from fileview.cli import main
+
+raise SystemExit(main())