English | Русский

Assistant X

Ask your own library. Get answers with the document, the page and the exact quote.

Assistant X turns a folder of your documents (from a few files to tens of thousands of books, standards, papers,
reports and scans) into a private library that your AI assistant understands by meaning, not just by words. Ask in
your own words, and in under a second it finds the right passage among thousands of files, reads the page and
answers with an exact quote. The library runs on your computer and works with Claude, Codex, the ChatGPT desktop app, DeepSeek
Harness, LM Studio and any other MCP client. It is made for anyone who works from documents: engineers, researchers,
students, doctors, lawyers, economists.

At a glance

• Answers you can check. Every answer cites [code, cl. N, table N, p. N, PDF N]; a quote is verified word for word
  against the page, and the assistant can show you the image of the original page.
• Takes in a whole library. PDF and scans (OCR with a quality score per page), Word, PowerPoint, Excel, EPUB,
  FB2, DjVu, images, HTML, archives (ZIP, 7z, RAR) and e-mails with attachments. Duplicates and new editions are
  found, every document gets a card and a shelf, every step is journaled.
• Search by words and by meaning, with reranking, tables of contents of books and a warning when a scan is weak.
  Measured on a real library of 7 208 documents (945 262 fragments), 25 questions: 0.63 s a question (median), 0.89 s
  for 95 % of them on a laptop NVIDIA RTX 5080; 2.1 s and 3.7 s on its processor (Intel Core Ultra 9 275HX). The first
  question after a start waits about 20 s for the models; meanwhile the search answers by words.
• One library for all your AI apps. A single local service loads the models once (an NVIDIA, AMD or Intel video
  card, or the processor) and serves every connected app at the same time.
• Private by design. Documents, texts and the search stay on your PC; a model in the cloud sees what the tools
  give it for a question (the search hits, the pages it reads, cards), and with a local model in LM Studio nothing
  leaves the PC.
• Share a library. Export it as a base package and install it in another workspace, merged with the documents
  already there.
• English and Russian documents out of the box; one card schema and one set of shelves for any field, with domain
  profiles for special vocabularies.
• Easy to install. Ask your agent to install it, double-click Setup.bat, or use an offline medium;
  no administrator rights needed.

Version 0.6.1 (prototype) · Windows and Linux · GNU AGPL-3.0-or-later, the data folders also CC-BY-4.0 (see
License) · Author: Alexandr Yalovoy. What comes next: ROADMAP.md.

Features in detail

Answers you can check

• Every answer names the document and the place: [code, cl. N, table N, p. N, PDF N] (clause, table, printed page; a part not known is left out), with a code such as N00012 that stays
  with the document for its whole life.
• A verbatim quote is checked against the text of its page (verify_quote); a quote that does not match is caught.
• The image of the original page (page_image): look at a table, a diagram or a formula with your own eyes; the
  page of a reference comes with its quote marked in yellow ("show [N-00001, PDF 36]"; "without the mark" when you
  want it clean).
• The references of an answer gathered into a folder (export_references): "copy the references to D:\Project" puts
  there the files of the documents cited and one PDF of the pages cited, a page a sheet, each with its reference on
  top and its quote marked. Only words the text layer of a page has are marked: on a scan the sheet says the quote is
  not marked, never a mark at a guessed place; the originals are never changed, a file there already is replaced
  only when you agree.
• The map of a book (book_map): its contents with page numbers, so the assistant reads the right section instead of
  guessing.
• A "Source quality" warning when an answer rests on a weak scan.

Search

• By words: stemming for Russian and English, a dictionary of abbreviations and the synonyms of the profile.
• By meaning: the multilingual model bge-m3, so a question in Russian finds an English text and the other way round.
• Reranking of the best fragments (bge-reranker-v2-m3).
• Reading pages in a row (read_pages), the card of a document (document_info), the list of documents
  (list_documents).
• A query log: what the apps asked and what was found, to measure the quality.

Intake of documents

• Formats: PDF and scans; DOC, DOCX, RTF, ODT; PPT, PPTX, ODP; XLS, XLSX, ODS (every sheet as a table); EPUB, FB2,
  MOBI; TXT, Markdown, HTML; DjVu; JPG, PNG, TIFF; archives ZIP, 7z, RAR, TAR (unpacked); e-mails EML, MSG (their
  attachments taken out).
• OCR (Tesseract) with a quality score per page; long scans are split and recognized in parallel.
• Hidden text in documents is found, cut out of the search and reported.
• A broken font encoding is detected and the pages are read again by OCR.
• Duplicates by content and new editions by designation: "replace the old one" or "keep both".
• The program drafts the card (title, designation, type, topic, contents); the assistant checks it.
• The move into the library is a transaction: every step is journaled, an interrupted intake goes on with --resume.
• Files that are not documents (programs, CAD, video) are put aside, never lost.

Library and cards

• One set of shelves for any field: N Standards, L Literature, P Projects and reports, E Equipment documents,
  R Regulations and law, J Journals and papers, X Other.
• The card of every document is JSON under an open schema: type, designation, year, publisher, the links "replaces",
  "other version", "adopts" (for standards), searchable texts in English and Russian.
• The catalog CATALOG.md, the journal journal.md and the OCR quality report are made from the cards.
• The texts are Markdown with page markers: you can read them without the program.
• A document can be taken out of the library, its code kept reserved.

One service for all your apps

• One command connects them: assistant-x connect auto finds Claude Desktop, Claude Code, Codex, DeepSeek Harness,
  LM Studio, Gemini CLI, Antigravity, Cursor, Cline and Kimi and writes the library into each.
• One local service per PC: the models are loaded once and serve every app at the same time.
• An NVIDIA video card (CUDA), an AMD or Intel one (DirectML), or the processor.
• A mode for small local models (--compact) and a reading set of tools (--tools reader: it changes nothing in the library).
• MCP over HTTP for other clients, with an access token.
• The skill of every app is written by the program and refreshed with a new version.

Base packages: share a library

• Export the library (cards, texts, base, without personal documents) as one package.
• Install, update or remove a package in another person's workspace, merged with their own documents.
• Every step can be resumed after a failure or rolled back.
• A package from someone else is checked as untrusted.

Privacy and security

• Documents, texts, the base and the search stay on your PC; a model gets what the tools give it for a question.
• With a local model in LM Studio nothing leaves the computer.
• The library changes only through a plan and its confirmation token.
• Documents are treated as untrusted: hidden instructions in a text are found and marked.

Installation and support

• Tell your agent (Codex, Claude Code, DeepSeek Harness) "Install Assistant X for me" and it does the rest.
• Setup.bat by double-click, without administrator rights; an offline medium for a PC without
  internet.
• Windows 10/11 and Linux; Python 3.11.
• doctor shows what is missing; connect --check checks every app; debug-report makes a report to pass on.
• Languages and fields are data: language packs (Russian, English) and profiles (general, oil-gas-ru) are added
  without changing the code.

How it works

1. Put your documents into the inbox folder.
2. Tell your assistant "AX: sort my documents": texts, OCR, cards, shelves.
3. The library builds its search by words and by meaning.
4. Ask in any connected app, starting the message with "AX:".
5. Get an answer that cites the code and the page, and check the quote against the original page.

Get the program

The shortest way: ask your agent. Tell Codex, Claude Code or DeepSeek Harness: "Install Assistant X for me:
https://github.com/AlexandrYalovoy/Assistant_X" — the agent follows INSTALL_FOR_AI.md (the
latest release, the connection of your apps, a check), and you confirm its commands. Codex and the ChatGPT desktop app
also take the plugin of this repository: codex plugin marketplace add AlexandrYalovoy/Assistant_X; Claude Code:
/plugin marketplace add AlexandrYalovoy/Assistant_X.

• The repository: https://github.com/AlexandrYalovoy/Assistant_X (issues and pull requests there); a mirror on
  GitFlic: https://gitflic.ru/project/alexandryalovoy/assistant_x. Clone it with
  git clone https://github.com/AlexandrYalovoy/Assistant_X.git, or download the ZIP of the code from the page.
• A release: https://github.com/AlexandrYalovoy/Assistant_X/releases — the source of the version, the wheel
  assistant_x-<version>-py3-none-any.whl and the notes of the version (CHANGELOG).
• An offline medium (Windows, no internet needed on the PC): a folder made by assistant-x prepare-media on a PC
  with internet — Setup.bat, the program in app\ (its complete source), the packages, the models and the programs
  of the intake. Copy it to the PC and double-click Setup.bat.

What is in the repository

Profiles and languages

The code is English only; what it knows about documents is data. Language packs (assistant_x/lang/ru,
assistant_x/lang/en) hold the letters, stemmers, stop words and the words that match documents: headings, references
to tables and figures, designations of standards, title pages, personal papers, hidden instructions. Every pack is used
by default ([documents] languages in assistant_x.toml), so Russian and English documents are read the same way in
any workspace, and every card has its searchable texts in English and Russian. The shelves of the library (the
letters of the codes) are the same everywhere: N Standards, L Literature, P Projects and reports, E Equipment documents, R Regulations and law, J Journals and
papers, X Other (assistant_x/schemas/shelves.json). A domain profile
(assistant_x/profiles/<name>) adds only the knowledge of one field: general (the default) has none, oil-gas-ru
brings Russian oil-and-gas synonyms and the role of a process engineer in the skill (assistant-x init --profile oil-gas-ru).

Document hierarchy (default)

Answers list the requirements level by level, the highest first, and on a conflict the higher level wins; the search
lifts a higher level a little among close results. A document gets its level from its designation.

The levels and their designation patterns are data (hierarchy.json of the profile). To set your own, tell the
assistant "my hierarchy is: …": it shows the levels and, on your yes, writes hierarchy.json into the workspace
(the tool library_hierarchy), which is then used instead of the profile's.

LM Studio: the reference mode

A local model in LM Studio answers as a reference desk: up to 15 verbatim quotes of the library, each with its
reference [code, cl. N, table N, p. N, PDF N], grouped by the level of the documents, then the sources; no analysis of its own. The number
is a setting: reference_quotes = 15 under [search] in assistant_x.toml. The model needs a context of 32768
tokens: the number under the field of the message reads 0/32768 (the installer sets it as the default of every
model; with 0/8192 the answers lose their quotes, see docs/LMSTUDIO.md).

Every reference, in every app and mode, has one form: the code, the clause, the table, the printed page and the PDF
page that are known, e.g. [N-00001, cl. 6.2.1.9, table 1, PDF 36] (in Russian [N-00001, п. 6.2.1.9, табл. 1, PDF 36]); a part that is not known is left out, never made up. The full engineering answer (initial data,
requirements by level, calculation, checks) comes from Claude or ChatGPT (Codex).

Your workspace (not in the repository)

All your data lives in one folder, Documents\Assistant X by default (assistant-x init [FOLDER] makes it; another
one: AX_WORKSPACE or --workspace): assistant_x.toml (the settings), inbox/ (new documents), library/ (the
originals by shelves, 01_Standards … 99_Other), index/ (cards/<code>.json — the JSON cards,
the one source of truth about every document; texts/<code>.md with pages === page N ===; CATALOG.md and
sources_to_update.md made from the cards; intake_events.tsv and the generated journal.md, manifest.tsv,
ocr_quality.tsv), reports/, and .assistant_x/ (the base, the batches of the intake, the debug journals; the models are of
the PC, in %USERPROFILE%\.assistant_x\models). Keep your own copy of library and index: they are your data. The code folder is never written to.

Requirements

• System: Windows 10 or 11 (x64), or Linux (x86_64; see "Linux and macOS" below).
• Python 3.11 (the tested version; Setup.bat installs it on Windows when it is missing).
• Disk: about 6 GB for the models (≈ 4.5 GB) and the packages (≈ 1 GB), plus the room of your library.
• Memory: 8 GB of RAM recommended (the models and the intake of scans take several GB).
• Video card: optional. NVIDIA (CUDA), AMD or Intel with its own memory (DirectML) make the search by meaning
  faster; without one it runs on the processor.
• An app with MCP: Claude Desktop or Claude Code; Codex (CLI, IDE) or the ChatGPT desktop app; DeepSeek
  Harness; LM Studio with a model that can call tools; or any MCP client (stdio, or streamable HTTP with
  assistant-x serve --http). The library also works from the command line alone ("Without an app" below).
• Where your text goes: the search runs on your PC, but what the tools give the model goes to the provider of
  that model (Anthropic, OpenAI, DeepSeek, Google, Moonshot AI for Kimi, the provider set in Cursor or Cline): your
  question, the search hits (fragments, quotes, codes and titles of documents), the pages it reads, cards and the
  list of documents, page images, and during "AX: sort my documents" the drafts of the cards with the headings and the
  start of the text of the new files and their names. For confidential documents use a local model in LM Studio.

Getting started (Windows)

1. Setup.bat — finds or installs Python, installs the packages and the program, makes the workspace
   Documents\Assistant X with the profile general, connects the library to every app it finds (Claude Desktop,
   Claude Code, Codex, DeepSeek Harness, LM Studio, Gemini CLI, Antigravity, Cursor, Cline, Kimi:
   assistant-x connect auto), writes the skills and runs a
   self-test. From a medium (assistant-x prepare-media --out E:\ on a PC with internet:
   Setup.bat, app\, packages\, models\ with MODELS.json, programs\) everything of the program goes to
   %USERPROFILE%\.assistant_x — app\<version>, the environment venv, the models (checked against MODELS.json),
   the programs of the intake — and the workspace holds your data only; a base package (a .axbase file) beside Setup.bat
   is offered at its end, else the window "Open a file" asks for one (Cancel goes on without a base);
   Install-Base.bat installs one later and Update.bat takes the latest release,
   each with a double click (docs/LMSTUDIO.md); Setup.bat --base E:\base\x.axbase installs it
   with no question. Another folder or the oil-and-gas profile: Setup.bat --workspace "D:\My library" --profile oil-gas-ru. From a folder of the code (a development checkout) it uses .venv beside it; then
   assistant-x.bat download-models downloads the models (≈ 4.5 GB) into %USERPROFILE%\.assistant_x\models;
   without them the search is by words. The PC folder %USERPROFILE%\.assistant_x (program, models, programs of the
   intake, locks, tokens) can be moved: set AX_MACHINE_DIR to another folder before Setup.bat and keep it set.
2. scripts\install_intake.bat (assistant-x setup-intake) — LibreOffice, Tesseract (the languages of the packs: rus+eng by default), 7-Zip and DjVuLibre for the
   intake, without administrator rights.
3. Claude Desktop only: zip the folder skill of the workspace (it holds SKILL.md) and upload it in Claude →
   Settings → Capabilities → Skills, then restart Claude Desktop (the icon by the clock → Quit, then open it again).
   Codex, Claude Code and DeepSeek Harness got their skill from connect; in LM Studio any model learns the rules from
   the tool library_guide. Questions before a tool call: none in the Code tab of Claude Desktop, in Claude Code and in
   LM Studio (connect allows the tools of the library there); the chat of Claude Desktop keeps its permissions to
   itself: at the first call of a tool press "Always allow", it does not ask again.
4. Put documents into inbox of the workspace and write to your assistant "AX: sort my documents" (or double-click
   intake.bat and let the assistant write the cards afterwards).
5. Ask, starting the message with "AX:" (or "connect to the library"). The answers cite [code, cl. N, table N, p. N, PDF N].
   assistant-x.bat doctor shows where everything is and what is missing, assistant-x connect --check whether every
   app reaches the library.

Commands at a glance

assistant-x <command> (assistant-x.bat on Windows; assistant-x help lists them all; --workspace DIR anywhere
chooses another workspace):

Without an app

The intake runs from the command line too: assistant-x intake run makes the texts and meta_draft.jsonl in
.assistant_x\work\<date>; write meta.jsonl there by hand from the draft (one JSON line per file: docs/INTAKE.md,
"Cards"), check it with assistant-x intake check-meta, then assistant-x intake build, assistant-x intake apply --dry-run, assistant-x intake apply, assistant-x build and assistant-x embed.

Troubleshooting

• "Found by words only" or "N of M fragments have no meaning vectors": the embeddings are missing or still
  loading. Wait 10–20 s after the start of the library; otherwise run assistant-x embed (or ask the assistant for
  intake_reindex), and assistant-x doctor names a missing model (assistant-x download-models).
• A base install, update or removal was interrupted (the PC switched off): assistant-x base install PACKAGE --resume goes on, --rollback undoes it (the same for update and remove); the assistant reports it in its
  status.
• An app does not see the library: assistant-x connect --check makes the handshake and a search through the
  entry of every app and says which part fails; assistant-x connect APP writes the entry again.
• The intake apply was interrupted: assistant-x intake apply --resume.
• "the machine lock is busy": another heavy task runs (assistant-x lock says which); wait, or add --wait.
• Setup.bat stops on the packages with SSL, CERTIFICATE_VERIFY_FAILED or a connection error: an antivirus that
  scans HTTPS (Kaspersky and others) may hold pypi.org, files.pythonhosted.org and download.pytorch.org (and
  huggingface.co when the models are downloaded). When it asks about one of these sites ("the site may be shown
  incorrectly"), choose to allow it (Kaspersky: "Add to exclusions"), then run Setup.bat once more; or install from
  the medium, without internet.
• Anything else: assistant-x debug-report makes a file to pass on to whoever helps you (read it first: it
  names the folders and the last questions).

Install with pip (any system)

Python 3.11 (the tested version; newer versions are not tested yet). In a folder of the code (a clone of the repository):

python -m venv .venv
.venv/bin/python -m pip install -c assistant_x/setup/constraints.txt -e ".[dense,intake]"
.venv/bin/assistant-x init
.venv/bin/assistant-x download-models

(on Windows .venv\Scripts\…). constraints.txt holds the versions of the release: the same packages as an
installation by Setup.bat. [dense] brings the search by meaning (torch; on Windows the torch of PyPI is CPU-only,
so for an NVIDIA card install the CUDA build from download.pytorch.org first — without it the card is not used and
embed asks about the processor), [intake] the intake of your own documents; without them the search goes by words.
assistant-x init makes the workspace (--profile oil-gas-ru for the oil and gas profile), assistant-x doctor shows
what is missing. Then assistant-x connect auto connects the apps (below).

Linux and macOS

The program runs there too (the PC folder is ~/.cache/AssistantX, or AX_MACHINE_DIR); Setup.bat
and the offline medium are for Windows only. The programs of the intake come from the system: apt install libreoffice tesseract-ocr tesseract-ocr-rus p7zip-full djvulibre-bin (Debian, Ubuntu) or brew install libreoffice tesseract tesseract-lang p7zip djvulibre (macOS); assistant-x setup-intake --no-install finds them and writes their
paths into assistant_x.local.toml. The tests (all but the slow ones) run in CI on Linux and Windows with Python 3.11
(.github/workflows/tests.yml); macOS and newer Python versions are not tested yet.

Connect your apps

assistant-x connect auto (Setup.bat runs it) writes the entry of the library into every app it finds; assistant-x connect APP one app (claude_desktop, claude_code, codex, dsh, lmstudio, gemini, antigravity, cursor, cline, kimi), --full gives an app every tool,
assistant-x disconnect APP takes it out. A copy of the settings file is kept beside it, the entries of others stay.
Every entry starts the same light bridge, <python> -m assistant_x.server.bridge, which talks to one library service
on 127.0.0.1: the models are loaded once for all the apps. By hand (any MCP client that starts a program):

{
  "mcpServers": {
    "assistant-x": {
      "command": "C:\\Users\\you\\.assistant_x\\venv\\Scripts\\pythonw.exe",
      "args": ["-m", "assistant_x.server.bridge", "--tools", "reader"],
      "env": {"AX_WORKSPACE": "C:\\Users\\you\\Documents\\Assistant X", "PYTHONUTF8": "1", "HF_HUB_OFFLINE": "1"}
    }
  }
}

A local model in LM Studio step by step: docs/LMSTUDIO.md.

Add to LM Studio without the command line: assistant-x connect lmstudio --link prints a link
(lmstudio://add_mcp?..., the entry of this PC); opened, LM Studio asks to add the server. The installer's summary
gives it too.

After a new version, assistant-x update writes the entries again; the skills of the apps are refreshed by the library
service at its first start (a skill edited by hand is kept), and Claude Desktop says once that its uploaded skill is
outdated.

--tools reader gives the 8 reading tools (search, pages, contents, page image, quote check, card, list, the guide)
and export_references, which writes copies of the references only into a folder the user names; without it every tool (the intake, base packages). --compact shortens the descriptions and the answers for small local
models. The apps and their files: docs/CLIENTS.md. Clients that speak MCP over HTTP only:
assistant-x serve --http [--port 8765] (every request needs the bearer token of mcp_http_token.txt in the PC folder:
SECURITY.md).

Tests

No models and no real library are needed (a mini library is built on the fly in a temporary workspace):

.venv\Scripts\python.exe -m pytest -q tests

The folders: tests\base (base packages: export, inspect, install, update, hostile packages), tests\search (the
search, the index, the server, the installer), tests\intake (the intake), tests\corpus (the recognition of a
corpus against its baseline) and the tests at the top of tests (cards, language packs, profiles, the medium, an
English library). scripts\check.ps1 runs ruff and every test (-Fast: without the slow ones). The slow tests (the
whole intake with LibreOffice and OCR, the corpus) carry @pytest.mark.slow: pytest -m slow tests.
hooks/pre-commit runs ruff and pytest -m "not slow" tests before a commit (copy it to .git/hooks/).

License

• The code is free software under the GNU AGPL-3.0-or-later (LICENSE). You may use it for yourself or inside
  your company, change it and pass it on. Whoever passes on copies, changed or not, gives the source code with them
  under the same license; whoever runs a changed version as a network service for other people offers those people
  its source code.
• The data in assistant_x/lang, assistant_x/profiles and assistant_x/schemas (language packs, domain
  profiles, the card schema and the shelves) is also available under CC-BY-4.0 (LICENSES/CC-BY-4.0.txt): it may be
  used in any project, open or closed, with credit to "Assistant X by Alexandr Yalovoy" and a link to the license.
• Your documents, cards, texts and base are yours: the licenses of the program do not apply to them.
• Third-party components (PyMuPDF, Tesseract, LibreOffice, 7-Zip, the models) keep their own licenses: NOTICE.
• Contributions are accepted under the Contributor License Agreement (CLA.md, see CONTRIBUTING.md).

Security

Report a vulnerability privately (GitHub → Security → Report a vulnerability), never with its details in a public issue
(without access to that form: an issue titled "private contact request", nothing more): SECURITY.md says how,
and what Assistant X guarantees about the documents and base packages it reads.

Disclaimer

The author is not responsible for the documents and libraries that users load into the assistant. The rights to those
documents belong to their right holders; users are responsible for checking that they may load and use what they load.
This is in addition to the no-warranty clause of the GNU AGPL.

AI-assisted development

Assistant X was developed with Claude Desktop and Claude Code using Claude Opus 5.5 and Claude Fable 5.1.