LITerature MANager

English | 中文

Local-first, AI-augmented literature manager.

A local knowledge base for research papers, stored as plain files on your disk. Papers link explicitly to projects, code repositories, and each other through structured metadata and symlinks. Use it through a web UI for everyday browsing, reading, and annotation — and, for anything the UI doesn't cover, run the lit CLI yourself, or ask an AI agent to drive it for you via the bundled Claude Code skills.

Know before you use

A few things worth knowing up front:

1. Don't move a vault or project folder by hand. The symlinks, project bridges, and registry that hold it together are path-based; if you must move one, run lit health-check afterward to repair what broke.
2. Figure/table reading needs a multimodal model. A text-only model falls back to plain-text extraction and can't see figures or image-based tables.
3. Don't edit metadata files by hand. Change papers, taxonomy, and config through the web UI or your AI agent — both go through validated lit commands.
4. Windows users. Symlink features (browsing views, project bridges) need administrator privileges; WSL is recommended.

Key Features

1. Plain files you own. Your whole library is plain text on disk — YAML metadata, markdown notes, original PDFs. No cloud database, no lock-in: back it up anywhere, grep the lot.

2. Consistent by design. A shared TAXONOMY.md governs topics, methods, projects, and sources; atomic writes plus lit health-check keep cross-references clean as the library grows.

3. Paper ↔ project ↔ code. Bind one paper to many projects (each gets a symlinked folder and an auto-generated REFERENCES.md) and to its cloned code repo — an explicit knowledge graph with no manual upkeep.

4. Web UI + AI agent over one validated core. Browse, read, and annotate in the web UI (lit gui); for anything more, ask Claude Code in plain English and the bundled lit-library / lit-reading skills drive the full CLI. Every write is validated, so the library stays correct even when the model isn't.

Install

litman is a Python CLI tool. Install with pipx so lit is permanently available in every shell, isolated from your other Python environments. Don't have pipx? See pipx.pypa.io.

From PyPI (recommended):

pipx install litman   # first install
pipx upgrade litman   # update

From a local clone (development):

# first install
git clone https://github.com/wqx1999/litman.git
cd litman
pipx install .

# update (pull latest code first)
git pull
pipx install --force .

Then run the one-shot setup wizard:

lit setup   # interactive wizard: shell completion → Claude Code skill → vault setup → (optional) cloud sync

Uninstall

Run two steps, in order — lit uninstall first (while the lit command still exists), then pipx:

lit uninstall          # removes bundled skills, shell completion, and the vault registry
pipx uninstall litman  # removes the lit CLI itself

lit uninstall lists exactly what it will delete and asks first — pass --dry-run to preview or -y to skip the prompt.

If you installed from a local clone, also delete the cloned repo folder once the CLI is gone:

rm -rf path/to/litman   # the directory you git-cloned into

Your vault (papers, PDFs, notes, annotations) is never touched by any of this; delete that directory by hand if you also want the data gone.

Quick start

lit gui   # open the web UI — browse, read, annotate, tag, and link papers

That's it — lit setup already created your vault. The web UI handles everyday browsing, reading, and annotation; for anything more (adding papers, taxonomy edits, project links), ask your Claude Code agent in natural language or see the command reference.

Agent model benchmark

litman's agent layer (the bundled lit-library and lit-reading skills) is meant to work with whatever model you point Claude Code at, not only Anthropic's. To see how well different models drive it, we ran each one as the Claude Code backend and had it operate litman through the skills, over 22 everyday-workflow tasks (add, read, tag, modify, link, export, taxonomy edits, health checks, ...), 3 rounds each, on the litman 1.0.0 codebase (commit 876d11c, June 2026).

What the score is. Each task is a single-turn prompt in a clean context: a fresh agent gets one natural-language instruction and must complete it in that one turn, with no prior conversation and no follow-up. TRR (task-completion rate) is the fraction of tasks the resulting vault state passed; RA (routing accuracy) is how often the agent picked the correct skill for a request.

A low score does not mean the model cannot operate litman. It means the model less often one-shots the task from a cold start. With more guidance (a more detailed request, or a few follow-up turns) a lower-scoring model can still do the same work. This is a deliberately hard zero-shot floor, not a ceiling.

TRR is the mean over the 22 auto-scored tasks across 3 rounds; network-dependent and multi-turn scenarios (code cloning, cloud sync, a multi-turn recovery case) are excluded from this single-turn score. Whatever the model scores, the data layer validates every write — a wrong command fails loudly rather than writing bad data into the vault, so a lower-scoring model needs more turns but never corrupts the library.

Documentation

Full documentation lives under docs/. New to litman? The tutorial covers about 80% of everyday use; for anything else, ask the agent or check the command reference. docs/0-readme.md maps out the whole set.

Local-preview the docs as a static site:

pip install mkdocs mkdocs-material
mkdocs serve

Acknowledgments

This tool was developed in the Süssmuth Lab, Technische Universität Berlin. Development was carried out with access to the TU Berlin HPC cluster.

This project was built with the help of AI-powered development tools:

Core dependencies that make litman possible:

Cloud sync (lit sync) is powered by rclone, the external CLI that mirrors the vault to any cloud backend it supports — the backbone of how a vault gets backed up and moved between machines:

Octopus mascot generated with Doubao (AI image generation).

License

MIT. See LICENSE.

_{AI agents: a condensed, link-dense map of this project lives in README-Agent.md.}