Docs
AI & MCP

The jot CLI

Log in once, bind a repo, read, reply to and resolve feedback from the terminal, and run the MCP server.

jot is one small native program: the terminal commands, the setup that gives your coding agent /jot, and the MCP server itself (jot mcp).

Using Claude Code? The Jot plugin is one line, and runs this CLI for you.

Install

npm i -g @usejot/cli     # then type jot

Or without installing, prefix any command with npx @usejot/cli:

npx @usejot/cli login

npm picks the build for your machine: macOS (Apple silicon and Intel), Linux (x64 and arm64) and Windows x64. Node 18 or later runs the installer; jot itself needs nothing else.

macOS already has a jot

macOS ships an unrelated /usr/bin/jot that prints number sequences. npm's global folder comes first on a normal PATH, so jot is this one; if jot --version prints jot: illegal option, put npm's folder (npm prefix -g, then /bin) ahead of /usr/bin, or use npx @usejot/cli.

Get started

jot login     # the browser opens; pick a workspace
jot init      # in a repo: .jot.json, .mcp.json, /jot, the jot skill and AGENTS.md
jot whoami    # check: the profile, workspace and projects in use

jot init writes, in the repo root:

  • .jot.json: the profile and project. No secrets, safe to commit.
  • .mcp.json: the jot MCP server, with no token inside. It runs jot mcp when jot is installed, npx -y @usejot/mcp when it is not; both find the token through .jot.json. An old JOT_API_TOKEN in it is removed, and jot init says so.
  • .claude/commands/jot.md: the /jot command for Claude Code.
  • .claude/skills/jot/SKILL.md: the jot skill, how an agent should work the queue.
  • AGENTS.md: the same guide in a marked <!-- jot --> section, for Codex, Cursor and other agents. Only that section is ever rewritten; the rest of the file is yours.

A /jot command or skill you edited is left alone; jot init --force replaces it.

Commands

This reference is generated from the contract the CLI is built from.

CommandDoes
jot loginconnect this terminal to a workspace (opens the browser)
jot initin a repo: bind it to a project and add /jot for Claude Code
jot list [--status S] [--json]open feedback, one line each (--status all for every state)
jot show <id>the full repro, as markdown
jot status <id> <STATUS> [-m note]move it to IN_PROGRESS, RESOLVED or APPROVED; the API applies the workspace's policy
jot reply <id> -m "text"reply in the thread
jot watch [--once] [--json] [--interval 5] [--all]wait for new feedback and print it
jot loop [--agent claude] [--fix]hand each new comment to an agent
jot profileslist them (* is the default)
jot use <name>make one the default
jot logout <name>forget one
jot whoamithe profile, workspace and projects in use
jot profile <name> <command…>run any command as that profile (same as --profile)
jot promptinstructions to paste into Cursor, Codex or any agent
jot mcpthe MCP server, over stdio (what .mcp.json runs)
jot help | --versionthis help, or the version
CommandFlagDoes
jot login-p, --profile namesave as this profile name
jot login--api urlthe API (default BACKEND_API_URL, then the hosted one)
jot login--app urlthe dashboard (default JOT_APP_URL, then the hosted one)
jot init--project idbind this project instead of asking
jot init--forcereplace an edited /jot command or jot skill
jot list--status SOPEN (default), IN_PROGRESS, RESOLVED, APPROVED or all
jot list--jsonprint JSON
jot status-m, --message notepost this note too
jot reply-m, --message textthe reply
jot watch--oncestop after the first new comment
jot watch--jsonone JSON object per line
jot watch--interval secondspoll interval, 1 or more (default 5)
jot watch--allon the first run, count what is already open as new
jot loop--agent clauderun headless with this agent
jot loop--fixlet the agent edit, then resolve
jot loop--interval secondspoll interval, 1 or more (default 5)
jot loop--allon the first run, count what is already open as new
any-p, --profile namerun as this profile
any-h, --helpprint the help
any-v, --versionprint the version

jot status passes any status through; the API decides what this token may set. Approval follows the workspace's policy, so APPROVED works only where the workspace lets agents approve.

Profiles

A profile is a workspace's API address and token, saved in ~/.jot/config.json (readable only by you; JOT_HOME moves the folder). jot login names it after the workspace; --profile office names it yourself. The first one is the default.

Which profile a command uses, highest first:

  1. --profile <name> (or jot profile <name> …)
  2. the JOT_PROFILE environment variable
  3. the nearest .jot.json, walking up from the current folder
  4. the default profile
  5. JOT_API_TOKEN and BACKEND_API_URL, for setups from before profiles

A name from the first three that this machine does not have is an error, never a quiet switch to another workspace.

Two workspaces, or two accounts

Log in once per workspace, naming each profile. Signing in with a different account works the same way: sign out of Jot in the browser (or use another browser profile) before the second login.

jot login --profile office      # pick the company workspace
jot login --profile personal    # pick your own, or sign in as someone else
jot profiles                    # both, * marks the default
jot use personal                # change the default

Then run any command as either, without changing the default:

jot profile office list
jot --profile personal show cmv1x…
JOT_PROFILE=office jot watch

Each repo's .jot.json names its own profile, so jot init in your work repo and in your side project keeps the two apart for you and for your agent. jot logout <name> forgets a profile; revoke its token in Settings → Agents.

Watch

jot watch checks for new open feedback every 5 seconds (--interval to change it) and prints each new comment as markdown, or one JSON line with --json. --once exits after the first. The first run treats what is already open as known, so only new feedback comes through; --all includes it. What it has shown is remembered per profile in ~/.jot/state/.

Loop

Inside Claude Code, /jot loop is the loop: the agent runs jot watch --once, proposes a fix, and waits for your OK (/jot loop fix skips the wait).

Headless, jot loop --agent claude runs Claude Code once per new comment:

  • Propose (default): claude -p in plan mode. The comment moves to IN_PROGRESS and Claude's plan is posted on it as a reply, for the team to approve.
  • --fix: Claude edits the code (acceptEdits). When it succeeds the comment moves to RESOLVED and Claude's summary is posted as the reply.

Each comment prints one line, and the loop keeps going until Ctrl+C.

The MCP server: jot mcp

jot mcp is the Jot MCP server, over stdio. Your agent starts it; you never run it by hand. It serves the same six tools as npx -y @usejot/mcp, with the same names and inputs, reads the token through the same profiles, and sends the agent the playbook as its instructions.

{
  "mcpServers": {
    "jot": { "command": "jot", "args": ["mcp"] }
  }
}

jot mcp doctor checks the token and the API, and prints a config to paste. Setup for each agent is in MCP for coding agents.