What is zotkit CLAUDE.md?

Repository-specific instructions for developing the Zotkit Python package, a command-line and library tool for working with a Zotero research library through its web API and WebDAV.

Use it when fixing bugs, changing or releasing Zotkit, running its tests, updating documentation, or deciding whether a change needs approval from the main project session.

It gives an AI coding agent the project’s rules for scope, cross-session communication, versioning, documentation, and safe changes.

zotkit CLAUDE.md — Instructions file for coding agents by oldantique: Repository-specific instructions for developing the Zotkit Python pack

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/oldantique/zotkit/claude-md

Clone the repo

git clone --depth 1 https://github.com/oldantique/zotkit

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/oldantique/zotkit/claude-md.svg)](https://agentmods.dev/instructions/oldantique/zotkit/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/oldantique/zotkit/claude-md"><img src="https://agentmods.dev/badge/instructions/oldantique/zotkit/claude-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 1,581 This file is loaded in full into every session.

When invoked 1,581 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.01581	$0.01581
Opus 5	$0.00790	$0.00790
Sonnet 5	$0.00316	$0.00316
Haiku 4.5	$0.00158	$0.00158

Measured 3d ago against content hash 15bb38f36f8d, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

zotkit CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 104 lines

How it starts

The opening of the file, as written. The whole thing — 104 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Development context (for agent sessions in this repo)

This file is for AI-assisted development sessions on zotkit itself. If you are an agent helping a user use zotkit on their library, read AGENTS.md instead.

Scope

This repo is the Python package only (headless Zotero Web-API + WebDAV CLI/library). The Zotero Reader plugin is a separate repo, oldantique/zotkit-reader — see docs/adr/0003. Data conventions (version of record, abstract-source stamp) are documented in README — keep docs and code consistent with it.

Cross-session routing

Crash/bug reports arriving directly from any session may be fixed and shipped right away when the fix is behavior-preserving and tested — but notify the HQ session (private zotero repo) in the same breath. Feature requests, CLI surface changes, and anything touching conventions/policy need an HQ work order first. Never name other sessions' confidential projects in public surfaces (commit messages, release notes, issues) — "a downstream session" is enough.

Releasing

Bump the version in both pyproject.toml and zotkit/__init__.py (keep them equal).
Update README "Limits & roadmap" / changelog notes if behavior changed.
Commit, push to main.
Create the GitHub release via REST — gh release create has given a spurious scope error here, the API works: gh api repos/oldantique/zotkit/releases -X POST -f tag_name=vX.Y.Z -f name=vX.Y.Z -f body='...'
.github/workflows/publish.yml then publishes to PyPI automatically via Trusted Publishing (no tokens anywhere). Tags are plain vX.Y.Z.
Verify: pipx run --spec zotkit==X.Y.Z zotkit --version once PyPI updates.

Tests

tests/ is the offline pytest suite, filed by module, never by release (a file named after a version guarantees an archaeology layer per release): test_metadata.py (abstract cleaner + two-layer version-of-record predicate
- fetch_arxiv_batch against a canned feed), test_enrich.py (plan_enrich VoR gate, the "source has no abstract" note + its status invariant, set_abstract guard/force/stamp matrix), test_audit.py (bucketing), test_find.py (--any/--abstract matching, hit annotations, snippet shape), test_dedup.py (dedup_maps/duplicate_key + skipped-meta keys), test_show.py (one-line format, sanitized errors, --verbose), test_export.py (_rekey + provenance header + faked HTTP), test_fetch_warning.py (git-worktree detection on tmp repos), and test_lint.py (lint_tags accepts both str and Zotero-native {"tag": ...} shapes). Run with pip install -e ".[dev]" && pytest. pytest is a dev extra only — runtime deps stay exactly pyzotero + httpx.
Tests stay offline: no network, no .env, no credentials, no live library. Anything that needs those is a manual smoke step: read-only zotkit audit against the real library, plus a create/abstract round-trip on a temp item that is deleted (and confirmed 404) afterwards.
CI (.github/workflows/ci.yml) runs the suite on every push/PR across ubuntu + windows × Python 3.11/3.13 — Windows is not optional (the v0.1.x release-breaker was a Windows UTF-8 bug). publish.yml runs the same test job before build, so release step 3 (push) now implies CI must be green; a failing suite blocks the PyPI publish.
Still-open debt: the Zotero Storage attachment branch has no automated or live test — manual verification only (see Hard constraints).

Read the full file on GitHub · 104 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

3d ago First seen · 104 lines · 1,581 tokens per session scan A 15bb38f36f8d

Subscribe to this mod's changes

zotkit CLAUDE.md is an instructions file published in the GitHub repository oldantique/zotkit (23 stars, last pushed 18d ago), licensed MIT. It adds 1,581 tokens to every session, about $0.0079 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Research Zotero bibliography cli headless reference-manager webdav

zotio AGENTS.md

Instructions for OrgMentem/zotio, covering zotio agents guide, local operating contract, dependency updates, zotero api surface and mcp surface.

OrgMentem/zotio · 2,494 tokens

obscura AGENTS.md

Instructions for h4ckf0r0day/obscura, covering agents.md, build, rendering and stealth, no rendering, with rustls or stealth and test.

h4ckf0r0day/obscura · 2,630 tokens

payload AGENTS.md

AGENTS.md instructions for payloadcms/payload, a project described as: Payload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.

payloadcms/payload · 12 tokens

zotkit CLAUDE.md