Build histories with an agent, real or invented

Every screen of the app is also a CLI command that answers in JSON, and althistory mcp gives Claude, Cursor or any MCP client the same tools. Bring a premise from real history, or a world nobody has written yet. The agent does the writing, and althistory checks that the dates and causes hold together.

Install it

You need Node 20 or later. npm link puts althistory on your PATH, which the MCP configs below assume; without it, use the full path to bin/althistory in the repository.

Local mode keeps every graph in JSON files, so there is no database to set up. althistory status reports the mode it is running in.

Terminal
$ git clone https://github.com/Qworg/althistory.git
$ cd althistory
$ npm install
$ npm link
$ althistory status

Connect an agent over MCP

althistory mcp is a stdio MCP server. Add it to Claude Desktop, Cursor or Claude Code, and the agent can create graphs, write events, ages and causal links, check them, and branch them for you. If the app is running, the server works through it, so what the agent writes appears as it goes; otherwise it works on the files directly.

The server also offers three prompts, one for each way of working described below. In Claude Code they appear as /althistory:worldbuild and so on: run one on its own, then describe your world or premise in your next message.

No extra API key needed. Claude writes the history itself through the tools. Only the drafting tools, generate_timeline and branch_timeline, call a model of their own, and only if the server has ANTHROPIC_API_KEY or OPENAI_API_KEY in its environment (env in the config, or -e on the command). Without one they return a generic skeleton marked "source": "template" for the agent to rewrite. With the app running they run inside it, as jobs you can watch fill in.

You never start althistory mcp yourself: your client runs it, and talks to it over stdin and stdout. If your client cannot find althistory, give the full path to bin/althistory in the clone; it needs node on the client’s PATH.

claude_desktop_config.json · .cursor/mcp.json
{
  "mcpServers": {
    "althistory": {
      "command": "althistory",
      "args": ["mcp"]
    }
  }
}
Claude Code, for every project
$ claude mcp add --scope user althistory \
    -- althistory mcp

Three ways to work

Each is a prompt the server offers. Pick it in your client, or just ask in your own words: the prompt only gives the agent a plan to follow.

Bend real history

Start from a premise and the moment real history turns. The agent drafts what follows and corrects the years before the turn from what it knows really happened; althistory checks that every consequence comes after its causes.

“Draft a history where Byzantium wins at Manzikert, then show me where it’s weakest.”

Prompt
alternate_history
Tools
generate_timeline, ingest_text, link_events, branch_timeline

Invent a world

No real history underneath: the agent writes the world’s ages, events and causes, and althistory keeps them consistent. The graph keeps the world’s own calendars, of any shape, so the app, the tools and the exports write “Thaw 4, 312 AR” in a year of twelve months and two festivals, and a day of thirty hours.

“Help me build the history of Vael, a drowned archipelago where salt is money.”

Prompt
worldbuild
Tools
create_graph, create_arc, create_event, link_events, validate_graph

Grow what you have

Hand the agent a graph you already have. It reads the whole history, writes one open thread forward, and branches wherever you can’t choose. A simulation can suggest what comes next, but it is a rough model of pressures between actors, not prose.

“Read my Vael graph and write the next fifty years of the Glass Republic.”

Prompt
grow_history
Tools
export_context, simulate_timeline, validate_graph, branch_timeline

The tool names drop their althistory_ prefix here. Without MCP, althistory prompt worldbuild world="…" --plain prints the same brief for any agent that can run a command.

Inventing a world, start to finish

An abridged session with the worldbuild prompt. The agent settles the calendars first, lays out three ages, writes the events and links their causes.

Then one link is refused: the agent claimed the glassmakers started the Tide War, but they only joined it eleven years in. Instead of forcing the link, the agent writes the grievance that actually turned them.

Every date is one moment on the graph’s timeline, and the world’s calendars name it. Vael’s Reckoning has twelve months of thirty days, Midyear’s Day and the four Drowned Days, in a day of thirty Earth hours divided into twenty of its own; the coast keeps the Tide-count beside it. The tools take dates as the world writes them (“Midyear’s Day, 141 AR”, or “Thaw 312 AR” for a month) and give them back the same way beside each date’s place on the timeline, as the Markdown export does.

See your world

The agent’s graphs are files in timeline/data in your clone, the same store the app reads. Start the app with ./start-local.sh, open localhost:5173, and pick the graph: its timeline, causal graph and dates read in the world’s calendars, and the header switches between them.

Open Vael in the demo

Building Vael with Claude
You    Help me build the history of Vael:
       a drowned archipelago where salt is
       money, and the tide-priests keep the
       count of years.

Claude calls althistory_create_graph
       { "name": "Vael", "calendar": {
         "version": 2, "dayLength": 108000,
         "primary": "reckoning",
         "calendars": [{
           "id": "reckoning", "name":
             "the Reckoning of the Rising",
           "parts": [
             { "name": "Lowtide", "days": 30 }, …
             { "name": "Midyear's Day", "days": 1,
               "intercalary": true }, … ],
           "epoch": 0,
           "eras": [{ "label": "AR", "from": 1 }], … },
           { "id": "tide", "name": "the Tide-count",
             … }] } }
       calls althistory_create_arc ×3
       The Age of Salt · The Tide War ·
       The Glass Republic
       calls althistory_create_event ×8
       calls althistory_link_events ×8

       calls althistory_link_events
       # the glassmakers side with the priests
       #   → the Tide War begins
       returns Temporal ordering violation:
         cause timestamp
         (Seedtide 12, 152 AR, …) must not
         be after effect timestamp
         (Midyear's Day, 141 AR, …)

Claude The glassmakers joined in 152 AR,
       eleven years into the war, so they
       can’t have started it. I’ve added what
       turned them, the salt ban of 122 AR,
       and linked it to their siding with the
       priests instead.

       calls althistory_create_event
       calls althistory_link_events
       calls althistory_validate_graph
       returns { "valid": true,
                 "errorCount": 0, … }

Claude Vael has 3 ages, 9 events and 9
       causal links. The Glass Republic has
       one event so far. Shall I branch at
       the Siege of Hollow Isle (163 AR) and
       let the last salt-king survive it?

Use the CLI

Every command prints JSON on stdout and its progress on stderr, so its output can go straight into a script or an agent. althistory schema prints the JSON Schema of every command, with the required options marked, so an agent can learn the tool by reading it.

Generating a history from a premise, or a world from a description, uses a model when ANTHROPIC_API_KEY or OPENAI_API_KEY is set; without one you get a template to fill in. With the app running, drafting runs inside it, as a job that writes as it goes and that Ctrl-C cancels. Ingestion reads text with patterns offline and adds a model when it has a key.

Exit codes
0Success
1General error
2Validation failed
3Authentication failed
4Not found
5Connection failed
Real and alternate history
# Start from a premise
$ althistory generate timeline \
    --premise "Byzantium wins at Manzikert" \
    --divergence-point 1071-08-26

# Or from the record
$ althistory ingest url \
    https://en.wikipedia.org/wiki/French_Revolution

# Then ask it how one thing led to another
$ althistory causal paths -g <graph> \
    --from <event> --to <event>

# --plain prints the Markdown itself, not a JSON envelope
$ althistory --plain export <graph> --format markdown
Invented worlds
# Draft a world from a description
$ althistory generate timeline \
    --world "A drowned archipelago ruled by salt-kings" \
    --era-label AR

# Give a graph you already have its own calendars
$ althistory graph calendar <graph> \
    --calendar-file vael-calendars.json

# Print the worldbuilding brief for any agent
$ althistory prompt worldbuild \
    world="A drowned archipelago" --plain

Go further

Back to the overview · Try the app in your browser