An AI agent that collaborates with historians to extract structured datasets from primary sources, adapt to heterogeneous documents, and accumulate domain knowledge across sessions. Chronos combines a document analysis agent with a VS Code extension to analyze scanned page images, extract structured data, and build knowledge about archival sources.
- VS Code (v1.110+)
- Node.js (v18+) — required by the underlying
piagent the extension installs on first run - A Gemini API key for the vision model
Install the Chronos — The AI Historian extension from inside VS Code:
- Open the Extensions view (
Ctrl+Shift+X, orCmd+Shift+Xon macOS). - Search for Chronos — The AI Historian.
- Click Install.
That's it. The first time you run a Chronos command, the extension checks for pi (the AI agent framework Chronos runs on) and the Chronos pi-package, and offers to install both in a terminal — no manual npm install -g or pi install step required.
Manual install (advanced / offline)
If you'd rather install everything by hand:
# 1. Install the pi agent globally
npm install -g @mariozechner/pi-coding-agent
# 2. Register the Chronos pi-package
pi install https://github.com/ai-historian/history-agent
# 3. Install the VS Code extension from a downloaded .vsix
code --install-extension chronos-ai-historian-0.1.7.vsixThe .vsix is published on GitHub Releases.
Open VS Code in an empty folder. Press Ctrl+Shift+P and run Chronos: Init Workspace. This creates the workspace structure and prompts for your Gemini API key.
Press Ctrl+Shift+P and run Chronos: Import Sources. Select a folder containing your source material — PDFs, images (PNG, JPG, TIFF, BMP), or text files. Each file within the folder is treated as a source. PDFs are automatically converted to page images. You can import additional sources at any time by running the command again.
Note: Very large PDFs can sometimes crash the system during conversion. If this happens, please open an issue so we can look into it.
Press Ctrl+Shift+P and run Chronos: Start Agent Session. The page viewer opens and a pi terminal starts.
On first startup, type /login in the terminal to log into your AI provider account (e.g. Anthropic, Google). Without this, no models will be available.
Type /select-source to pick a source and begin working.
Set in .chronos/.env:
GEMINI_API_KEY=your-key-here
pi supports many options natively. Common ones:
# Use a specific model
pi --model gemini-2.5-pro
# Continue previous session
pi -c
# Resume a specific session
pi -rRun pi --help for the full list.
See DOCS.md for technical details on workspace structure, tools, skills, memory, and the VS Code extension.
@article{hufe2026towards,
title={Towards the AI Historian: Agentic Information Extraction from Primary Sources},
author={Hufe, Lorenz and Griesshaber, Niclas and Greif, Gavin and Eck, Sebastian Oliver and Torr, Philip},
journal={arXiv preprint arXiv:2604.03553},
year={2026}
}See LICENSE for details.