Slivingdoc README

Test coverage: 83.3% 😍👌

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"],
      "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:

No path needed. Each server takes its own private notebook directory and tells the agent where it is, in the server instructions and in every tool result, so nothing has to be configured or coordinated between agents. Pass --workspace-root instead when you want a fixed directory that humans and agents share, and path then addresses any directory below it.

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. The path is optional and defaults to the working directory; a relative path resolves against it:

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:

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.}