Reactant

Document-native annotations for AI-assisted writing, with an optional Python transaction kernel and the Reactant Replay history viewer.

The agent interprets annotations; the kernel records snapshots, document versions, and word-level provenance. Replay lets you inspect and trace that history.

The previous skills-only implementation is preserved on the reactant-1.0 branch. The current discussion workflow uses <@chat-user> and <@chat-model> in place of the old <@plan> / <@output> tags.

Requirements

• An Agent Skills-compatible AI coding agent with permission to read and edit your local documents. The agent interprets and executes annotations.
• Python 3.11 or newer for the optional CLI, history kernel, and bundle exporter. The Python package has no runtime dependencies; pip uses Hatchling to build it.
• A browser such as Chrome or Edge for Replay. No Node.js or frontend build is required.
• Citation search, image generation, and plotting require the corresponding capabilities in your agent host. Reactant does not supply an AI model or an account for those services.

Install the skills

Claude Code users can install the skills as a plugin:

/plugin marketplace add a554b554/Reactant
/plugin install reactant@reactant-marketplace

Install the Python package separately below to enable transaction history.

For annotation editing without history, copy the contents of skills/ into the skill directory of the workspace containing your documents: .agents/skills/ for Codex, .claude/skills/ for Claude Code, or the equivalent directory for your host. Preserve each skill's folder and supporting files. Reopen or reload the agent session so it discovers the skills.

For editing with transaction history, first install the Python package. From the repository root:

python -m venv .venv

Activate the environment using the command for your shell:

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

Then install the package and verify it:

python -m pip install .
reactant version
reactant doctor

Keep this environment available to the agent's shell. Change to a separate workspace containing the documents you want to edit, then install the skills there using one host option:

reactant install --host codex
# Or:
reactant install --host claude-code

For another host, use reactant install --target PATH_TO_SKILL_DIRECTORY. The installer refuses to replace unrelated existing skills by default.

If you want history, initialize it in that document workspace before running annotations:

reactant init
reactant doctor

This creates .reactant/ and records baseline versions of existing authored documents. The Python CLI records history; it does not execute annotation tags.

Edit a document

Create demo.md in your document workspace with:

This paragraph contains a large number of words to communicate a simple idea.
<@edit: make this shorter>

In the agent conversation, invoke /execute-one demo.md to process the first actionable annotation, or /execute demo.md to process them sequentially. If your host exposes skills with a plugin namespace, use its displayed command, such as /reactant:execute demo.md.

The agent edits the document and consumes the processed tag. With history initialized, the routers record each dispatched operation in a transaction. Copy examples from examples/ into your document workspace to try Markdown, LaTeX, citation, plotting, and custom-skill workflows.

Common annotations include <@proofread>, <@ph: fill in this passage>, <@cite: find a supporting source>, <@chat-user: discuss this paragraph>, and <@resolve>. A resolve tag applies a completed inline discussion. <<text>> protects text; ((text)) limits the editable field. Full conventions are in references/tag-protocol.md.

Inspect and restore history

Run these commands in the initialized document workspace:

reactant status
reactant log demo.md
reactant lineage-query demo.md all --json
reactant doctor

To restore one recorded version, take its ID from reactant log demo.md and run reactant checkout demo.md VERSION_ID. Checkout restores that document and refuses to overwrite unrecorded changes by default. Transaction details are available through reactant show TRANSACTION_ID.

Open Reactant Replay

Open replay/index.html in Chrome or Edge. Select Open folder and choose the .reactant/ directory from your document workspace, or drop that folder onto the page. The viewer reads history without changing it.

Use the timeline to choose a version, click a word to inspect its recorded origin, or select a passage and choose Trace this passage. The Before–After view compares revisions. Initial content and changes outside recorded requests have separate labels; the latter do not identify who made the change.

If folder loading is unavailable, export a JSON bundle. From this code/ directory, substituting the path to your initialized document workspace:

python replay/tools/export_bundle.py "PATH_TO_DOCUMENT_WORKSPACE" -o history.json

Then use Open bundle in Replay to select history.json. No pre-recorded history is included in this package; create one through the workflow above.

If needed, serve the viewer from this directory:

python -m http.server 8765 --bind 127.0.0.1

Open http://127.0.0.1:8765/replay/index.html. Stop the server with Ctrl+C.

Troubleshooting

• If reactant is not found, activate the environment in the agent's shell; python -m reactant is an alternative invocation of the same CLI.
• If a skill is missing, check its installed SKILL.md and reload the agent.
• If no history appears, run reactant init before executing tags and ensure the agent can invoke the installed CLI. Existing unrecorded edits cannot be reconstructed retroactively.
• If an operation needs unavailable search, image, or plotting tools, enable those capabilities in the host. Such operations may leave the tag unresolved.

The original MIT license is included at LICENSE.

Development

python -m pip install -e ".[dev]"
python -m pytest
reactant doctor

See the architecture and annotation guide for details. Paths in that guide are relative to the repository root. The tests/ directory includes unit and integration tests, manual acceptance matrices, and the simulated editing corpus. Paper sources and recorded authoring histories are not part of this repository.