vivac

<div align="center">

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/img/logo-dark.svg">
    <img alt="vivac™" src="docs/img/logo-light.svg" width="320">
  </picture>
</h1>

**A tree where every node knows which node it was born from.**

*So that months later something can still answer “why are we here?”*

[![ci](https://github.com/JAAvila-Of/vivac/actions/workflows/ci.yml/badge.svg)](https://github.com/JAAvila-Of/vivac/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/vivac?color=2f5d50&labelColor=24292f)](https://crates.io/crates/vivac)
[![msrv](https://img.shields.io/badge/msrv-1.89-2f5d50?labelColor=24292f)](rust-toolchain.toml)
[![licence](https://img.shields.io/badge/licence-MIT%20OR%20Apache--2.0-24292f)](#licence)

</div>

```
$ vivac why 4

  Why we are here  ->  t4
  ------------------------------------------------------------------

  g1    Ship the 2.0 API
        the first customer is waiting on it
        (4 open / 1 closed below)
        |
        v
  t2    Replace the cache adapter
        the session bug traces back to it
        (3 open / 1 closed below)
        |
        v
  t4    No test for expiry  [closed]
        no way to reproduce the session bug
        ! the corpus run is what settled it
        = reproduced: sessions expire at 300s, not 3600

        ^^^ you are here

  In parallel, still open (3):
      t3     Rate limiting is undecided
      d5     Retry policy: three tries, then fail loudly
      t6     Migrate the callers

  t2 does not close until these close (1):
      t6     Migrate the callers
```

<div align="center">

**[What you get](#what-you-get)** · **[See it](#see-it)** · **[Install](#install)** · **[First five minutes](#the-first-five-minutes)** · **[Why one map](#one-map)** · **[Bring a project in](docs/MIGRATING.md)**

</div>

---

## Built for one person's own work

I run eight projects in parallel — open source, work and my own — and five
of them are large. Every time I came back to one I had to piece together what
had been decided in it, and more than once I watched the agent change
something we had already settled, because both of us had forgotten we had.
What I had against that was manual: ending each stretch of work by asking
the model for *a safepoint, so we can pick this up later*, or keeping a
`where_are_we.txt` at the root of the project.

vivac is what replaced them, and it is still measured on those projects. That
is the whole of its pedigree, and it shows in what got built: every mechanism
here came out of a defect that had already cost me days, and every number on
this page came off a real tree rather than a benchmark written to make a
README look good.

The tree this project keeps of itself, 23 days in: **695 nodes, 315 of them
closed, 176 standing decisions, 16 levels deep.**

Three of those defects, and what each one turned into:

- **A run marked `DONE` with its findings still open** — and 26 days before
  anybody noticed. Now `vivac done` refuses, and says what is missing.
- **A reading list of 109 open fronts across 224 lines**, with the one
  touched yesterday at the bottom. Now `open` answers *what is waiting on
  you*, in that order, and stops at ten.
- **Three claims shipped to crates.io that the binary beside them
  contradicted.** Now a test runs every command this page shows and holds its
  lists against `--help`.

What I would not give up now is no single feature. It is looking at the tree
of what was decided and why; picking a project back up with whichever model
is at hand and having it know what the last one settled; and knowing where
the work stands at any moment. In my experience that is worth more than
anything else here, and I hope it serves you as well.

Issues are open, and I want to hear where it fails you. Pull requests are not
open yet; [`CONTRIBUTING.md`](CONTRIBUTING.md) says why.

---

## The problem

When you develop with an agentic AI, work spawns more work. Three hops in, you
have lost the thread of what you originally set out to do.

It is not a memory problem: usually everything is written down. **It is a
provenance problem.** What is written does not say what it was born *from*,
and without that edge there is no way to reconstruct why you are where you
are.

> Measured on a real compiler: the path between the goal and the day's work
> was **six levels deep**, spread across a chronologically ordered 8,853-line
> tracker, 52 planning documents and 21 issues. The structure was temporal,
> which is exactly the opposite of provenance.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/img/edge-dark.svg">
  <img alt="Left: five records in the order they were written, with nothing connecting them — everything is here, nothing says what came from what. Right: the same five records as a tree, each one pointing at the node it was born from, so walking up the edge reads as why you are here." src="docs/img/edge-light.svg">
</picture>

Logbooks, decision records, issue trackers and session memory for agents all
store the **node**. Where one of them stores the **edge** as well, it is a link
somebody has to remember to add — so it is missing on exactly the node where
nobody thought it would matter. [Where it sits](docs/POSITION.md) goes through
them category by category, and says where each one is better than this.

---

## What you get

**The agent starts oriented, and nobody has to ask it to.** A hook runs
`vivac session start` when a session opens, so the first thing in its context
is where you are, what has already been decided, and what not to touch:

```
$ vivac brief

vivac · project: demo · lane: main · 2026-09-21
------------------------------------------------------------

 GOAL g1     Ship the 2.0 API
  |
  |-- t2     Replace the cache adapter
  |     why: the session bug traces back to it
  |
  `-- t6     Migrate the callers   <== HERE
        why: the old adapter had a different signature

 STANDING DECISIONS
  d5     Retry policy: three tries, then fail loudly

 LAST VIVAC
  v5 · push · 2026-09-21 · bcdba21
         you were about to: Migrate the callers

------------------------------------------------------------
 143 tokens · depth 3 · 0 parked
```

**In tokens, that is the whole argument.** A project keeping its state in
three places was asked to pick up where it left off. A hand-written plan
answered in **9,252 tokens**. A memory system answered *“maybe”* in about
**12,720**, depending on which of two names for the project it resolved. The
tree answered in **100**. The brief carries a token budget because a context
window is the one resource every session spends.

**Nothing closes over what is still open.** The one operation in the model
that rejects, and it earns it: a run marked done over open findings took 26
days to be spotted once.

```
$ vivac done 2

  t2 CANNOT close: 1 open closure condition(s)

      t6     Migrate the callers

  A run closes with its findings, not with its report.
  Closing it anyway leaves a trace:  vivac done 2 --force
```

**Every decision keeps what it turned down**, and what it was judged against.
`--alternative` holds the option rejected, `--supersedes` links a reversal to
what it reverses, and `--against` records the rule or pillar that decided it —
so a decision can be argued with a year later instead of guessed at. This
project's own tree carries 176 of them.

**An assumption that falls does not take its children with it.** `abandon`
marks the premise refuted and everything under it goes with it, except what
you rescue — and what is rescued **still hangs where it was born**, because
being born somewhere is not undone by that place turning out to be wrong.

---

## What it does not promise

**It saves tokens, not all of them.** Picking a project up took the tree 100
tokens where a hand-written plan took 9,252, and that difference comes back
every time a session opens. The agent still reads files, still reasons and
still explains itself, and none of that gets cheaper.

**It does not make sure nothing is ever forgotten.** No memory system can,
this one included, because every one of them still runs on the model's
judgement: *should I save this? is this a finding? do I need to read the tree
again before I answer?* The best skill in the world, a hundred subagents or a
hundred daemons move where that judgement happens, and none of them removes
it. vivac hangs capture off the seams of the work rather than off that
judgement, and still [measures where it slips](docs/SEAMS.md#where-it-slipped-and-what-changed).

What is left over after that is why the tree is built to be looked at.

---

## See it

```sh
vivac web
```

The agent writes the tree, and you can read it at any moment without asking
the agent anything. `vivac web` opens every project on this machine in a
browser: which one moved and which has been sitting still, what changed in
one while you were away, a node's whole lineage, and the whole tree. It is
where you see the state of each item for yourself, and where you catch what
the agent let pass.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/img/web-index-dark.png">
  <img alt="The index of vivac web with four example projects as cards. billing-api moved today, and its last stop made by hand was yesterday, with work since. field-app moved two days ago and nothing since its last stop. ci-costs moved yesterday, six days after its last stop. docs-site has not moved in thirteen days and has no stop made by hand. Each card names the node where its work was left." src="docs/img/web-index-light.png">
</picture>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/img/web-today-dark.png">
  <img alt="The page of one example project, billing-api. What moved since the last stop you made: four nodes opened, among them a finding and a decision, and one closed with its outcome. Where you are: the goal, the task under it, and the task you are on, marked you are here. What g