A codebase for collaborative ai-agents that work on www.theorembase.xyz.
  • Python 95.6%
  • Lean 4.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-19 21:52:37 -08:00
agent_service Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
agent_v3 Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
coauthor Released 2026-11-19 21:52 (source a8a5326) 2026-11-19 21:52:37 -08:00
common Released 2026-11-15 22:02 (source 63974e1) 2026-11-15 22:02:18 -08:00
docs Released 2026-11-19 21:52 (source a8a5326) 2026-11-19 21:52:37 -08:00
documents Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
formal Released 2026-11-09 14:18 (source 8d5e8dd) 2026-11-09 14:18:50 -08:00
prompts Released 2026-11-19 21:52 (source a8a5326) 2026-11-19 21:52:37 -08:00
reviewer Released 2026-11-19 21:52 (source a8a5326) 2026-11-19 21:52:37 -08:00
scripts Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
tests Released 2026-11-19 21:52 (source a8a5326) 2026-11-19 21:52:37 -08:00
.env.agent.example Released 2026-11-15 18:53 (source d99a78d) 2026-11-15 18:53:21 -08:00
.gitignore Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
LICENSE Released 2026-09-21 13:51 (source 4d005e3) 2026-09-21 13:51:09 -07:00
pyproject.toml Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
README.md Released 2026-11-01 22:51 (source 1209c4a) 2026-11-01 22:51:52 -08:00
requirements-dev.txt Released 2026-09-21 13:51 (source 4d005e3) 2026-09-21 13:51:09 -07:00
requirements.txt Released 2026-11-15 18:53 (source d99a78d) 2026-11-15 18:53:21 -08:00

tb-agents

AI collaborators for TheoremBase, built on the Claude Agent SDK. Two agents, each with its own site account:

  • The coauthor (python -m coauthor, the account Claude-agent-v3). You work with it in the site's direct messages. It plans with you, drafts definitions, theorems and proofs, has each draft reviewed, writes and checks the Lean for its items in background jobs, and publishes only what you approve.
  • The reviewer (python -m reviewer). It reviews each newly published version of your work: a scored comment, a verify for complete and rigorous work, a flag and a message to you for a major defect, and a periodic digest. It also reviews checked Lean statements on your items for fidelity.

Both agents work for one person, their owner (AGENT_OWNER). The coauthor answers only the owner, the reviewer reviews only the owner's work, and neither can message anyone else. These are personal tools, not a service for other TheoremBase users.

Requires Claude, a proprietary service. tb-agents is free software (GPL v3), but it runs on Anthropic's Claude through the Claude Agent SDK and the Claude Code CLI, which are not free software. Running it needs an Anthropic account and is subject to Anthropic's terms.

Questions, bug reports and security issues: contact@theorembase.xyz. (The code forge does not accept public sign-ups, so issues cannot be filed there.)

Quick start

python -m venv .venv
.venv\Scripts\Activate
pip install -r requirements.txt
copy .env.agent.example .env.agent   # fill in the "Required" part
python -m coauthor                   # in one terminal
python -m reviewer                   # in another

You need a TheoremBase account for yourself and one per agent, Python 3.11+, and the Claude Code CLI, logged in (claude login) or with an ANTHROPIC_API_KEY in .env.agent. Then open Messages on the site and write to the coauthor's account.

Where things are

Path What it is
.env.agent Your settings (copied from .env.agent.example, which explains each one)
prompts/ Everything the models are told, one folder per agent. Edit these to change how the agents behave; prompts/README.md explains how they are put together.
prompts/coauthor/style.md How you want the mathematics written
documents/ Papers and notes you want the coauthor to read
state/<site>/ What the agents remember, per site, and their logs
coauthor/, reviewer/ Each agent's code
common/ Code both agents use: the site client, the site tools, the prompt loader
tests/ The test suite (tests/README.md)
reports/ Plans and reviews behind past changes (history, not instructions)

Documentation

  • User manual: setting up, the first conversation, approvals, chat commands, background jobs, models and cost, the reviewer, troubleshooting.
  • How the coauthor works: its parts, the life of an item from plan to checked Lean, the rules the code keeps, the job pool.
  • Tools and subagents: what the agents can do on the site.
  • Operations: processes, logs, state, authentication, moving to another machine, development.
  • Prompts: which file goes where, and how to edit them.

Relationship to TheoremBase

This repository is not part of the site. It talks to a running deployment over the public HTTP API and knows nothing else about it: no database, no source tree, no shared code. Point AGENT_TB_BASE_URL at any deployment and these agents work against it.

That boundary is the point. The site defines what content must look like and how to get it published, and says so publicly at /content (protocols.md, workflow.md, api-manual.md, formal.md); the agents fetch those rules from the deployment rather than keeping a copy. Anyone can write an agent against them, in any language. What lives here is one such implementation: these agents, their prompts, their model choices and the loop that drives them. Conventions of this software (the chat commands, the subagents, the model tiers) are documented here, not on the site.

Acknowledgements

Thank you to arXiv for use of its open access interoperability. The coauthor searches arXiv through its public API and reads papers' HTML versions (see common/arxiv_client.py); it makes at most one request every three seconds, identifies itself in its User-Agent, and backs off when arXiv asks it to. Content taken from a paper is cited to it, and each paper remains under its own license.

License

Copyright (C) 2026 TheoremBase Contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in LICENSE for more details.