- Python 95.6%
- Lean 4.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| agent_service | ||
| agent_v3 | ||
| coauthor | ||
| common | ||
| docs | ||
| documents | ||
| formal | ||
| prompts | ||
| reviewer | ||
| scripts | ||
| tests | ||
| .env.agent.example | ||
| .gitignore | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| requirements-dev.txt | ||
| requirements.txt | ||
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.