ex-USSR Kinship Research
Turns Codex or Claude Code into a careful, evidence-first family-history researcher for the former USSR.
- Source repo
- DenisSergeevitch/ex-ussr-kinship-research
- Stars
- ★ 1.9k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 56/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A family historian whose great-grandfather was exiled to Kazakhstan in the 1930s wants the agent to trace his parents through church books.
- Not a fit if
- Anyone seeking living people's addresses or phone numbers
- Users expecting automatic identity or kinship confirmation
- Source review
- 56/100 · Major gaps
What does this agent do, and when should you use it?
This is an agent skill for genealogy across the 15 former Soviet republics and the Russian Empire. Its core is SKILL.md — the workflow and hard rules — backed by references/ covering source strategy, the evidence protocol, historical jurisdiction, privacy, and regional topics such as Habsburg Galicia and Bukovina, the 1944 Chechen deportation, German forced labour, and Bessarabia/Moldova. Python helpers turn a case into auditable registers: init_case.py creates the case folder, hash_artifact.py records a SHA-256 for every saved scan, audit_evidence.py checks citations and corroboration before conclusions are written, and build_pdf.py exports the HTML report to PDF only when asked. The default deliverable is a complete HTML report; a GEDCOM family tree can be produced on request. Skill instructions are written in Russian, but the agent converses in the user's language and quotes sources in original spelling with a translation.
Case intake fixes one research question, known facts, who may be alive and what is off-limits, then init_case.py builds the case outside the skill checkout. Research resolves every event to the state, province, district, parish or civil registry as of the event date, builds name-variant matrices (pre-reform Russian, Ukrainian, Polish, Romanian, German, Yiddish plus patronymics, maiden names and transliterations), and searches in the order originals → official catalogs → indexes → published document collections → trees and forums as leads only. Findings go into person, artifact, claim, relationship and search-log (CSV) registers, with each saved scan hashed by hash_artifact.py. Claim statuses are explainable labels — hypothesis, single-source, corroborated, strongly-corroborated, contradicted, unresolved — and copies of one record share an independence_group so they never count as independent proof. audit_evidence.py checks referential integrity, IDs and statuses and lists what is still uncorroborated or marked illegible. Helper scripts include familysearch.py (find FamilySearch books by place or DGS through an existing lawful browser session and keep only permitted fragments), the connected FamilySearch MCP workflow described in familysearch-mcp.md, gwar.py (WWI GWAR reports, hospital, award and prisoner-of-war records), register_search.py, and scan_montage.py (needs Pillow). Output is an HTML report built from assets/report.template.html with relationship evidence, optionally a GEDCOM 5.5.1 UTF-8 file.
- A family historian whose great-grandfather was exiled to Kazakhstan in the 1930s wants the agent to trace his parents through church books.
- Someone holds scans of a marriage certificate and a soldier card and needs to know whether they describe the same person, with an evidence chain.
- A researcher needs the parish and the right FamilySearch film for a Podolia village in the 1890s and wants the births for one surname read.
- You need to draft and, when authorized, send focused request letters to archives, libraries or universities without duplicate sends, treating replies as evidence.
- Families dealing with the 1944 Chechen deportation, German forced labour 1941–1945, or cross-border Bessarabia records.
- Exporting an existing tree into GEDCOM with source citations so another genealogy program can continue the work.
How do you install or deploy this agent?
With Node.js available, the optional Skills CLI installs into the current project by default; add -g for a personal install:
npx skills add https://github.com/DenisSergeevitch/ex-ussr-kinship-researchOr clone directly into your agent's skills folder. For Codex:
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-researchFor Claude Code personal skills:
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-researchFor a single project, put the folder in .claude/skills/ inside that repository. Most scripts need only Python 3 and the standard library; scan_montage.py needs Pillow, build_pdf.py needs a Chromium-based browser (or CHROME_PATH), and page-to-PNG previews with --png-dir need pypdfium2.
How do you use this agent?
After installing, just describe the family question; the agent works from available information and continues while archive requests await replies. For example: "My great-grandfather was exiled to Kazakhstan in the 1930s. Help me find his parents in church records."Initialize a case from the skill folder (the script refuses to create a case inside the skill folder, even with --force):
python scripts/init_case.py --case-dir ~/kinship-cases/my-case --research-question "Who were Maria's parents?" --subject-label "Maria"Hash every saved artifact:
python scripts/hash_artifact.py ~/kinship-cases/my-case/scans/marriage-1902.jpgAudit the registers before writing conclusions:
python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-caseExport to PDF only when explicitly requested; the exporter requires static HTML with local or embedded images and rejects active HTML and network image sources:
python scripts/build_pdf.py --html ~/kinship-cases/my-case/report.html --out ~/kinship-cases/my-case/report.pdfKeep private case data outside the skill's Git checkout. Run the unit tests with:
python3 -m unittest discover -s testsWhat are this agent's strengths and limitations?
- Explainable claim statuses instead of percentages, plus an independence_group that stops mirrored copies of one record counting as separate proof.
- Resolves archives by the historical jurisdiction at the event date rather than today's map, so it does not send you to the wrong repository.
- audit_evidence.py checks referential integrity, IDs and weak corroboration before conclusions, guarding against conclusion-first research.
- Default deliverable is a complete HTML report with relationship edges; PDF is opt-in and the exporter rejects active HTML and network images.
- Explicitly refuses to look up living people's addresses, phones or accounts and reports deportation, repression, adoption and DNA findings neutrally.
- The skill instructions are written in Russian, so review and maintenance of the rules need Russian even though the agent replies in the user's language.
- Several capabilities depend on a signed-in lawful browser session with FamilySearch; without it or under regional restrictions they are limited.
- PDF export depends on a locally installed Chrome, Chromium or Edge, or a CHROME_PATH setting.
- The FamilySearch MCP workflow requires you to connect a server and verify its browser, privacy and write capabilities; nothing is hosted by the skill.
- Institutional correspondence can only be sent through tools you authorize — connecting a mailbox alone does not authorize sending.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ex-USSR Kinship Research This agent | 56 · Major gaps | Agent plugin / skillFree + model costs | ★ 1.9k | 1d ago | Python | Codex · Claude Code |
| Apify Agent Skills | 40 · Major gaps | Agent plugin / skillFreemium | ★ 2.5k | 5d ago | Python | Codex · Claude Code |
| Jev Social | 71 · Some gaps | CLIFree + model costs | ★ 196 | 3d ago | JavaScript | — |
| Principia | 66 · Some gaps | CLIFree + model costs | ★ 1.1k | 1mo ago | Rich Text Format | — |
How does FollowAgents rate this agent?
Why each dimension lost points
README explicitly refuses to track living persons, avoids uploading files to third parties without consent, limits CAPTCHA to one attempt with user handoff, requires authorization for sending mail, and init_case.py refuses to create cases inside the skill directory—showing least privilege and user confirmation. However, dependency security is only asserted ('Python standard library only') without lockfiles or audit, so deducted; rollback is limited to preserving existing PDF on render failure, lacking broader recovery, hence 1.
Tests cover audit script field validation, independence grouping, status consistency, and report ID references, showing good self-consistency; but dependency availability relies on README prose (Chromium, optional pypdfium2) with no version constraints or manifest, deducted; failure messages are concrete (e.g., 'file not found', field count mismatch) per tests, so 2.
Targets multilingual users and multiple scenarios (church books, military, deportation, FamilySearch, GWAR, GEDCOM) with clear boundaries (no automatic identity determination, no external installs); but trigger precision is only described in SKILL.md without specific trigger words or routing rules, hence 1; environment fit covers Codex/Claude Code and CLI install, so 2.
README is well-structured with complete install notes, rich examples, and clear MIT license; but naming stability only references a changelog without version numbers or semantic versioning, deducted; known limitations are scattered rather than consolidated; maintenance responsibility is just an author name without governance or update process, hence 1.
Output usability is high (CSV registers, final report template, PDF generation, GEDCOM export), and marginal value is evident (evidence-first, independence grouping, audit script); but cost-benefit is constrained by manual case directory setup, external browser and optional library dependencies, and no quantified benefits, hence 1.
Evidence protocol clearly separates hypothesis, single-source, corroborated, strongly-corroborated, contradicted, and unresolved, and requires independence groups and direct original records; audit script enforces cited ID and status matching, with good fact/inference separation; but cross-source corroboration depends on users correctly filling groups, and the script can only validate declarations, not actual independence, so 2.
- Dependency security relies on the verbal claim of 'standard library only' without lockfiles or dependency audit; real use may introduce unaudited third-party packages.
- Cross-source corroboration depends on users manually filling independence groups; the audit script only validates declaration consistency, not actual source independence.
- Trigger precision is not explicit in visible files; SKILL.md lacks specific trigger words or routing rules, risking false or missed triggers.
- Version and change management only references a changelog without semantic versioning or release process; long-term maintenance responsibility is unclear.