Tagvico
Tagvico v3 is stable. Companion writes always require explicit approval,
and Paperless-ngx remains the document system of record.
Deploying v3? Read the stable deployment guidance, share a
redacted deployment result,
or report a reproducible bug.
The private Action Center and Household Companion for Paperless-ngx. Turn
letters and PDFs into assigned deadlines, decisions, payments, replies,
renewals, and multi-step work while keeping Paperless as the document system of
record. Paperless files the document; Tagvico makes sure someone acts on it.
Reviewable AI metadata filing is still included as an opt-in utility — and if
you use Paperless-ngx v3's built-in AI suggestions instead, Tagvico steps aside
and focuses on the action layer. See
Tagvico and native Paperless-ngx AI.
Why Tagvico
- Chat first — Tagvico opens on a chat with suggestions built from your real documents. Answers cite the Paperless documents they used, and proposed changes wait as approval cards.
- One page for what needs you — overdue and upcoming actions, pending approvals and review items for the whole household, with a page per person and per case.
- Action Cases, not loose reminders — one case per Paperless document, with priority, owner, due date, audit trail, and up to 100 checklist steps.
- A household, not a single user — assign work to family members, with roles that decide who may approve what.
- AI with approval boundaries — the Companion can read permitted documents and prepare changes; only an owner or adult can execute a write.
- Your choice of model — the Companion uses Vercel AI SDK v6 for OpenCode Go, OpenRouter, OpenAI, and compatible gateways, or your ChatGPT Plus or Pro plan through the official Sign in with ChatGPT flow, with no API key.
- Optional Telegram and Discord access — allowlisted family members can search, upload, list actions, and approve or reject proposals using their own Paperless tokens. Configure both under Settings → Channels.
- Designed for homelabs — one container, one persistent volume, and SQLite for processing history and retries.
- Built to recover — durable OCR and terminal-failure queues, safe rescans, original-metadata restore, and interrupted-job recovery.
- Operationally hardened — optional MFA, rate limits, same-origin mutation checks, protected setup, and generated JWT secrets.
- Clear privacy boundaries — keep processing on your network with a local endpoint, or explicitly choose a hosted provider.
- Included utility: reviewable metadata filing — opt-in AI suggestions for titles, tags, correspondents, types, dates, custom fields, and owners, with a review queue, cost-aware OpenAI Flex/Batch modes, and full restore snapshots. Useful on Paperless-ngx 2.x, or whenever you want an approval gate and audit trail that native suggestions don't provide.
The v3 architecture
Tagvico owns the credential store, model resolution, session transcript, narrow
tool catalog, household roles, approval state, and audit trail. Model providers
only supply inference. There is no shell or filesystem tool in the Companion.
Top-level case state is mirrored to reserved Paperless custom fields and the
tagvico/action tag; complete checklists remain local to Tagvico.
Tagvico and native Paperless-ngx AI
Paperless-ngx v3 ships its own AI: metadata suggestions, an apply-suggestions
workflow action, and document chat. That's good news — it covers the routine
tagging Tagvico automated in v1 and v2, and Tagvico does not compete with it.
- Deadlines, cases, households, approvals, and the family bots are
Tagvico's job. Paperless-ngx is a document archive by design and has no
equivalent layer.
- Metadata filing is yours to place. Use native Paperless AI, or use
Tagvico's opt-in filing when you want a review queue, an approval gate,
restore snapshots, provider choice, or you're still on Paperless-ngx 2.x.
- Do not run two writers. If Paperless AI workflow actions apply metadata
automatically, leave Tagvico's metadata automation off or in Review
first — never both in Automatic. Two automations editing the same fields
will fight, and the audit trail stops being trustworthy.
New Tagvico installations already start with scheduled scans paused and writes
in Review first, so native Paperless AI and a default Tagvico setup coexist
safely out of the box.
What Tagvico doesn't do
Stated non-goals build more trust than feature lists. Tagvico deliberately:
- doesn't store your documents — Paperless-ngx keeps the files; Tagvico keeps cases, approvals, and history.
- doesn't replace Paperless — search, storage, permissions, and native AI stay Paperless's job, accessed only through the official REST API.
- doesn't give models shell or filesystem access — the Companion has a narrow tool catalog, and every write needs an approval or an explicitly chosen automatic mode.
- doesn't phone home by default — analytics are opt-in, previewable, and content-free.
- doesn't require the cloud — one container next to your Paperless, with local inference if you want it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
