clioforge

ClioForge is a self-hosted, open-source research IDE designed for historians, humanities researchers, and AI agents. It brings together original documents, reading notes, evidence, and research tasks, aiming to keep interpretations connected to source material and subject to human review. The project is a personal open-source experiment; there is no hosted service, and users run it on their own computer or deploy to their own Cloudflare account. Key capabilities include importing PDFs, images, and text or selecting files from Google Drive, with private originals and preserved transcription versions. Users can read, highlight, and annotate pages, turning passages into evidence with stable source, version, and page references. A rich editor supports tables, drawings, and LaTeX; versions can be compared and writing exported with citations. Reviewed claims and evidence can be turned into a bounded manuscript draft with chapter progress, source references, coverage checks, and final human review. Research questions, competing interpretations, and evidence can be organized with a draggable task board and reviewable assistant results. Bounded extraction, comparison, and research workflows run using user-provided model API keys, tracking execution, dependencies, and estimated spending. A background research dossier workflow supports per-source reading, cross-critique, and source-linked synthesis, ending at human review. Collaboration features include project invitations, roles, and task discussions, plus project backup export and restore. The interface is available in English and Chinese with light and dark themes. Status: Self-hosted alpha. Automated tests and selected end-to-end research exercises cover important workflows but do not establish reliability for every archive, model, or institution. Semantic search covers text, not image similarity. Zotero import is not continuous synchronization. Scheduled literature monitoring checks a bounded set of Crossref metadata. Spending controls use estimates, not provider billing caps. Local recovery drafts are browser-specific. Google integration, email, and model calls require separate configuration. Running locally requires Git and Node.js 22.19 or newer. Local D1, R2, and Queues are emulated; no Cloudflare account is required. Setup involves cloning the repo, installing dependencies, configuring secrets, running migrations, and starting the dev server. The local runtime is loopback-only and not a hardened public server. For persistent hosting, a self-hosting guide is provided; a generic Docker/VPS production backend is not currently provided. Architecture: UI and HTTP API use React, Vinext, and Cloudflare Workers. Authentication uses Better Auth with records in D1. Projects, versions, references, and jobs use D1/SQLite with Drizzle migrations. Original files are stored in private R2 and served through authenticated APIs. Background research and monitoring use Queues, a separate Worker, and Cron Triggers. Transactional email uses Cloudflare Email Sending. Model access uses user-provided API credentials encrypted at rest. Application code records provenance, enforces access, tracks versions, and separates pending results from accepted research. License: Original application code is AGPL-3.0-only, with separately licensed third-party components. The project is independent and does not include or depend on Prove2Me code.