~/smarchone/docs

Comment on your docs.
Claude makes the edits.

tl;dr Comment on your repo's Markdown docs in the browser. Claude Code, or any local agent, edits the file and replies.

The problem

Editing a doc from the terminal means describing where the problem is: "second section, the bullet about retries…"
Then you scroll a diff to check it got the right spot.
That's a lot of attention for a one-line fix, and you lose your place in the doc.

How it works

One small daemon on your machine. Each repo's agent connects to it with a skill and a polling script.

Browser

The editor

One tab for every repo. You read, highlight and comment. Changes stream in live.

⇄comments
edits

Daemon

`docs serve` · localhost:3459

Owns the workspaces. Stores each doc's comment threads and version history, and queues threads as jobs for that repo's agent.

repo-a/.docs threads · history · job queue

repo-b/.docs threads · history · job queue

⇄jobs
replies

Agent, per repo

Skill + `poll.sh`

Claude Code with the /collab-docs skill, or any local agent. It edits the Markdown file directly and posts replies.

The skill registers the current repo as a workspace. docs serve "$PWD" starts the daemon if needed.
The polling script waits on the daemon in the background. It's a long-poll, so an idle agent uses no tokens.
When you comment, the daemon hands the page's threads to that repo's agent and locks the page. The agent edits the file, replies, and the page unlocks.

GitHub →

See it work

Two comments on a spec. One asks for an edit, the other asks a question. You never leave the page.

Docs — specs/retries.md

Claude is listening

Retries

.docs/specs/retries.md

When a request to the upstream API fails, the client should, in most cases and depending on the type of error that was returned, consider trying the request again a number of times before eventually giving up.

Backoff

Waits double after each attempt, starting at 200 ms, with a little jitter so clients don't retry in lockstep.

We give up after 5 attempts. Errors after that go to the dead-letter queue.

Get started in 1 minute

npm i -g @smarchone/docsNode 22+

npx skills add smarchone/docs --skill collab-docs -g

/collab-docsin Claude Code, in any repo

Then open http://127.0.0.1:3459 and leave your first comment. Or skip the global install: npx @smarchone/docs serve

space to skip · runs on your machine, nothing leaves it

~/smarchone/docs

The editor

docs serve · localhost:3459

Skill + poll.sh

Retries

Backoff

`docs serve` · localhost:3459

Skill + `poll.sh`