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).
