slivingdoc

Test coverage: 83.7% 😍👌

<div align="center"> <p>Distributed durable notebook built for high scale agents.</p> </div>

Features

• Gitlike semantics: slivingdoc uses terminology we (and agents) all know, designed for ease of use
• Automatic conflict resolution: commit without fear, trust that all conflicts must be resolved before being accepted
• High speed processing: the solution is quite simple conceptually, allowing for very high scale and parallelism
• Plug-and-play: setup the bucket, point at it, and start syncing notes!

docs/slivingdoc-v1.md is the full accepted contract behind these guarantees.

Get started

Add it to your agentic harness:

{
  "mcpServers": {
    "slivingdoc": {
      "command": "npx",
      "args": [
        "-y",
        "slivingdoc",
        "serve",
        "--bucket",
        "my-notes",
        "--workspace-root",
        "/srv/notes"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your-access-key-id>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-access-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

The bucket must exist, and credentials come from the normal AWS chain. No S3 account yet? examples/seaweedfs/ runs a local SeaweedFS container with a step-by-step walkthrough. You can also download a native binary directly from the GitHub release (slivingdoc-v<semver>-<os>-<arch>) and run it in place.

Supported platforms: Linux (amd64, 32-bit ARMv7, arm64), macOS (amd64, arm64), and Windows (amd64). The 32-bit Linux ARM artifact supports Raspberry Pi OS armhf.

How it works

The server exposes two MCP tools over stdio:

Tool	Inputs	Success result
notes_pull	path	OK
notes_commit	path, message	OK

notes_pull writes the current notebook into your directory. notes_commit publishes your changes and incorporates concurrent non-conflicting changes. Between calls there is no protocol at all — agents edit the files with the tools they already have, and humans can write in the same directory with any editor. The next commit carries their changes too.

Humans can also drive both operations directly, without an MCP host. A relative path resolves against the working directory:

slivingdoc pull notes
# edit UTF-8 text files under notes/
slivingdoc commit notes -m "meeting summary"

Success prints the unified result report: the OK status, the accepted remote generation, per-file insertion and deletion counts, and a totals trailer. A domain error exits nonzero and prints a candid report: the error category, the retryable verdict, and every conflicted file with its line ranges. Colour appears only on a real terminal and is disabled by any non-empty NO_COLOR.

The git part

Letting all agents write at once would work, but they would get overrun by race conditions. So slivingdoc has built-in git via libgit2 which effectively does:

1. git pull
2. (potential conflict resolution locally)
3. git add .
4. git commit -m "<agent message>"
5. git push
6. (potential conflict resolution locally)

All of these git operations are handled locally within a private mirror of the notes directory leaving a "streamlined" git sequence. This works due to two compromises, firstly that the local notes directory is prone to be changed on notes_pull, precedence goes to the remote state, leaving conflict markers. Secondly, the system only works for text (clean UTF-8).

Configuration

serve, pull, and commit read the same flags and environment variables. --bucket is required. The most common flags:

Flag	Environment	Default
--bucket	SLIVINGDOC_BUCKET	— (required)
--workspace-root	SLIVINGDOC_WORKSPACE_ROOT	startup working dir
--endpoint	AWS_ENDPOINT_URL_S3	AWS resolution
--region	AWS_REGION	us-east-1

slivingdoc serve -h prints the full reference, and docs/running.md covers everything an operator needs: all flags, the exact S3 permissions, logging (LOG_LEVEL on stderr), the notebook rules, conflict recovery, and checkpoint retention. The Terraform module in terraform/ provisions a bucket and a least-privilege IAM user for one notebook.

Development

• AGENTS.md — the developer and agent guide: package map, operation flows, conventions, and the QA gates.
• docs/slivingdoc-v1.md — the accepted architecture contract.
• docs/build.md — the native build, from pinned libgit2 source to dependency inspection.
• docs/testing.md — the test commands, the test layers, and the no-live-AWS rule.
• docs/releasing.md — release artifacts, npm trusted publishing, and make release.

make qa #lint plus the full Go and npm test suites

License

MIT — see LICENSE. Third-party notices for the statically linked libgit2 are in NOTICE.

_{Not affiliated with Paris Hilton.}