Docs - jotkit

Install

jotkit needs Node.js 24 or newer, on macOS or Linux. The login-service commands (jotkit daemon install andjotkit acp install) and desktop notifications are macOS and Linux only.

npm i -g @jotkit/jotkit
jotkit init

jotkit init creates ~/.jotkit, starts the local daemon in the background, installs the agent skills into ~/.claude/skills and~/.agents/skills, and prints a pairing code for the browser extension.

The daemon keeps running after the command exits. It listens on 127.0.0.1 only and is the single point of contact for both the extension and your agents.

Pair the browser extension

Install the jotkit extension from the Chrome Web Store, then open its settings (the gear in the toolbar) and enter the pairing code. If you need a fresh code:

jotkit pair

The pairing output also prints the daemon address. If jotkit had to fall back to a port other than 4817, set the same port in the extension settings.

Click the toolbar icon on any page to show the jotkit toolbar, or pressCmd+Shift+Y (Ctrl+Shift+Yon Windows and Linux). Pick an element to attach a comment to it, or comment on the page as a whole. Tag it, choose its scope, and save.

Scope comments to a repository

From inside a git repository:

jotkit link

This records the repository's git root in jotkit's registry. In the comment dialog the scope picker then lets you attach a comment to any registered repository, or keep it global. Repository-scoped comments carry the branch and commit you were looking at, so an agent can tell whether the code moved underneath the note.

jotkit repos      list registered repositories
jotkit unlink     remove one

Connect an agent

Model Context Protocol

Configure jotkit mcp as an MCP server in your agent. It exposes ten tools:comments_list, comment_get, comments_watch,comment_claim, comment_release, agent_log,attachment_get, task_create, task_update andtask_complete.

For Claude Code:

claude mcp add jotkit -- jotkit mcp

Agent Client Protocol

Drive an ACP agent through your comments directly:

jotkit acp --agent "npx @zed-industries/claude-code-acp" --mode stream

Stream mode reacts to comments as they arrive. Task mode groups the pending work into a plan you approve before anything happens.

Without either

Agents can use the CLI directly: jotkit agent session start,jotkit agent claim, jotkit agent log andjotkit comments watch.

Walk away: the background supervisor

jotkit acp serve watches every registered repository. When a comment is pending it spawns an agent rooted in that comment's repository, hands it the comment, and works it to completion. You get a terminal line and an OS notification when it finishes or gives up.

Nothing is silently dropped. The supervisor tracks what it dispatched, re-delivers a comment the agent never claimed, and after a few attempts leaves it pending and tells you.

Configure it in ~/.jotkit/config.json:

{
  "acp": {
    "agent": "npx @zed-industries/claude-code-acp",
    "repos": {
      "/Users/me/code/shop": { "permissions": "allow" }
    }
  }
}

jotkit acp install     launchd on macOS, a systemd user unit on Linux
jotkit acp status
jotkit acp uninstall

An unattended agent cannot write files unless you allow it. Permission resolves per comment first, then per repository, and otherwise defaults to deny-writes. Only a comment you wrote can raise its own autonomy; an agent-authored comment never can.

How the ledger works

~/.jotkit/sources/ holds append-only logs: your events, one log per agent session, and the daemon's own system events. Every line carries a global sequence number.
~/.jotkit/durable/comments.jsonl and ~/.jotkit/index.sqlite are derived by a deterministic reducer. Delete them and jotkit rebuild regenerates them byte for byte.
Agents never edit comments. They append evaluations, proposals, actions and outcomes to their own log. The daemon grants leases, verifies reported commits against git, and computes status: pending, in progress, then completed or cancelled.
Set "storage": { "mode": "global+repo" } to also project each repository's comments into <repo>/.jotkit/comments.jsonl.
Set "completion": "user" to keep finished work in progress until you accept it with jotkit comments accept or in the extension.

Everyday commands

jotkit daemon start | stop [--force] | status | run | install | uninstall
jotkit pair                          print a pairing code for the extension
jotkit comments list --repo --actionable
jotkit comments show <id>
jotkit comments explain <id> status  which events and rule produced a field
jotkit comments watch --repo         stream activity
jotkit tasks list | approve <id> | reject <id>
jotkit skills install                copy the skills into agent skill directories
jotkit mcp                           MCP server over stdio
jotkit acp serve | install | uninstall | status
jotkit rebuild                       regenerate the ledger and index from the source logs
jotkit doctor

Troubleshooting

Start here

jotkit doctor

It checks your Node version, the ledger, config, the ACP service, git, the daemon, extension pairing and listening agents, and tells you which one is unhappy.

The extension says it cannot reach the daemon

Run jotkit daemon status. If it is running, confirm the port it reports matches the port in the extension settings. jotkit falls back to the next free port when 4817 is taken, and remembers the one it chose.

The daemon will not start

The error now names the real cause. If every port in the scan range is busy, set an explicit one under "daemon": { "port": 4900 } in~/.jotkit/config.json. If a stale process holds the lock,jotkit daemon stop --force clears it.

An agent is not picking anything up

Comments tagged reference or inspiration, and comments scoped global, are context rather than work. Usejotkit comments list --actionable to see what an agent would actually treat as a job.