{
  "markdown": "Test coverage: 83.3% 😍👌\n\n[![slivingdoc banner](img/banner.svg)](https://slivingdoc.dev)\n\n<div align=\"center\">\n  <p>Distributed durable notebook built for high scale agents.</p>\n</div>\n\n## Features\n\n- **Gitlike semantics:** `slivingdoc` uses terminology we (and agents) all know, designed for ease of use\n- **Automatic conflict resolution:** commit without fear, trust that all conflicts must be resolved before being accepted\n- **High speed processing:** the solution is quite simple conceptually, allowing for very high scale and parallelism\n- **Plug-and-play:** setup the bucket, point at it, and start syncing notes!\n\n[`docs/slivingdoc-v1.md`](docs/slivingdoc-v1.md) is the full accepted\ncontract behind these guarantees.\n\n## Get started\n\nAdd it to your agentic harness:\n\n```json\n{\n  \"mcpServers\": {\n    \"slivingdoc\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"slivingdoc\", \"serve\", \"--bucket\", \"my-notes\"],\n      \"env\": {\n        \"AWS_ACCESS_KEY_ID\": \"<your-access-key-id>\",\n        \"AWS_SECRET_ACCESS_KEY\": \"<your-secret-access-key>\",\n        \"AWS_REGION\": \"us-east-1\"\n      }\n    }\n  }\n}\n```\n\nThe bucket must exist, and credentials come from the normal AWS chain.\nNo S3 account yet? [`examples/seaweedfs/`](examples/seaweedfs/) runs a local\nSeaweedFS container with a step-by-step walkthrough. You can also download\na native binary directly from the\n[GitHub release](https://github.com/baalimago/slivingdoc/releases)\n(`slivingdoc-v<semver>-<os>-<arch>`) and run it in place.\n\nSupported platforms: Linux (amd64, 32-bit ARMv7, arm64), macOS (amd64,\narm64), and Windows (amd64). The 32-bit Linux ARM artifact supports Raspberry\nPi OS armhf.\n\n## How it works\n\nThe server exposes two MCP tools over stdio:\n\n| Tool           | Inputs                       | Success result |\n| -------------- | ---------------------------- | -------------- |\n| `notes_pull`   | `path` (optional)            | `OK`           |\n| `notes_commit` | `message`, `path` (optional) | `OK`           |\n\nNo path needed. Each server takes its own private notebook directory and\ntells the agent where it is, in the server instructions and in every tool\nresult, so nothing has to be configured or coordinated between agents. Pass\n`--workspace-root` instead when you want a fixed directory that humans and\nagents share, and `path` then addresses any directory below it.\n\n`notes_pull` writes the current notebook into your directory.\n`notes_commit` publishes your changes and incorporates concurrent\nnon-conflicting changes. Between calls there is no protocol at all —\nagents edit the files with the tools they already have, and humans can\nwrite in the same directory with any editor. The next commit carries\ntheir changes too.\n\nHumans can also drive both operations directly, without an MCP host. The\npath is optional and defaults to the working directory; a relative path\nresolves against it:\n\n```text\nslivingdoc pull notes\n# edit UTF-8 text files under notes/\nslivingdoc commit notes -m \"meeting summary\"\n```\n\nSuccess prints the unified result report: the `OK` status, the accepted\nremote generation, per-file insertion and deletion counts, and a totals\ntrailer. A domain error exits nonzero and prints a candid report: the\nerror category, the retryable verdict, and every conflicted file with its\nline ranges. Colour appears only on a real terminal and is disabled by\nany non-empty `NO_COLOR`.\n\n### The git part\n\nLetting all agents write at once would work, but they would get overrun by race conditions.\nSo `slivingdoc` has built-in git via [libgit2](https://github.com/libgit2/libgit2) which effectively\ndoes:\n\n1. `git pull`\n1. (potential conflict resolution locally)\n1. `git add .`\n1. `git commit -m \"<agent message>\"`\n1. `git push`\n1. (potential conflict resolution locally)\n\nAll of these git operations are handled locally within a private mirror of the notes directory\nleaving a \"streamlined\" git sequence. This works due to two compromises, firstly that the local\nnotes directory is prone to be changed on `notes_pull`, precedence goes to the remote state, leaving\nconflict markers. Secondly, the system only works for text (clean UTF-8).\n\n## Configuration\n\n`serve`, `pull`, and `commit` read the same flags and environment\nvariables. `--bucket` is required. The most common flags:\n\n| Flag               | Environment                 | Default             |\n| ------------------ | --------------------------- | ------------------- |\n| `--bucket`         | `SLIVINGDOC_BUCKET`         | — (required)        |\n| `--workspace-root` | `SLIVINGDOC_WORKSPACE_ROOT` | temporary dir[^1]   |\n| `--endpoint`       | `AWS_ENDPOINT_URL_S3`       | AWS resolution      |\n| `--region`         | `AWS_REGION`                | `us-east-1`         |\n\n[^1]: `serve` with no configured root takes a per-process temporary\n    notebook directory and removes it at shutdown; the notes themselves live\n    in the bucket. `pull` and `commit` default to the working directory.\n\n`slivingdoc serve -h` prints the full reference, and\n[`docs/running.md`](docs/running.md) covers everything an operator\nneeds: all flags, the exact S3 permissions, logging (`LOG_LEVEL` on\nstderr), the notebook rules, conflict recovery, and checkpoint\nretention. The Terraform module in [`terraform/`](terraform/)\nprovisions a bucket and a least-privilege IAM user for one notebook.\n\n## Development\n\n- [`AGENTS.md`](AGENTS.md) — the developer and agent guide: package\n  map, operation flows, conventions, and the QA gates.\n- [`docs/slivingdoc-v1.md`](docs/slivingdoc-v1.md) — the accepted\n  architecture contract.\n- [`docs/build.md`](docs/build.md) — the native build, from pinned\n  libgit2 source to dependency inspection.\n- [`docs/testing.md`](docs/testing.md) — the test commands, the test\n  layers, and the no-live-AWS rule.\n- [`docs/releasing.md`](docs/releasing.md) — release artifacts, npm\n  trusted publishing, and `make release`.\n\n```bash\nmake qa #lint plus the full Go and npm test suites\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE). Third-party notices for the statically\nlinked libgit2 are in [NOTICE](NOTICE).\n\n<sub>Not affiliated with Paris Hilton.</sub>\n",
  "bytes": 6109,
  "sha": "6159b37f522e53cba4a2f2f572ee4478883269944124c3c184ba35a64926d354",
  "repo_slug": "baalimago/slivingdoc",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_baalimago_slivingdoc_6a49a340/readme"
}