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 jotOr without installing, prefix any command with npx @usejot/cli:
npx @usejot/cli loginnpm 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 usejot init writes, in the repo root:
.jot.json: the profile and project. No secrets, safe to commit..mcp.json: thejotMCP server, with no token inside. It runsjot mcpwhenjotis installed,npx -y @usejot/mcpwhen it is not; both find the token through.jot.json. An oldJOT_API_TOKENin it is removed, andjot initsays so..claude/commands/jot.md: the/jotcommand 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.
| Command | Does |
|---|---|
jot login | connect this terminal to a workspace (opens the browser) |
jot init | in 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 profiles | list them (* is the default) |
jot use <name> | make one the default |
jot logout <name> | forget one |
jot whoami | the profile, workspace and projects in use |
jot profile <name> <command…> | run any command as that profile (same as --profile) |
jot prompt | instructions to paste into Cursor, Codex or any agent |
jot mcp | the MCP server, over stdio (what .mcp.json runs) |
jot help | --version | this help, or the version |
| Command | Flag | Does |
|---|---|---|
jot login | -p, --profile name | save as this profile name |
jot login | --api url | the API (default BACKEND_API_URL, then the hosted one) |
jot login | --app url | the dashboard (default JOT_APP_URL, then the hosted one) |
jot init | --project id | bind this project instead of asking |
jot init | --force | replace an edited /jot command or jot skill |
jot list | --status S | OPEN (default), IN_PROGRESS, RESOLVED, APPROVED or all |
jot list | --json | print JSON |
jot status | -m, --message note | post this note too |
jot reply | -m, --message text | the reply |
jot watch | --once | stop after the first new comment |
jot watch | --json | one JSON object per line |
jot watch | --interval seconds | poll interval, 1 or more (default 5) |
jot watch | --all | on the first run, count what is already open as new |
jot loop | --agent claude | run headless with this agent |
jot loop | --fix | let the agent edit, then resolve |
jot loop | --interval seconds | poll interval, 1 or more (default 5) |
jot loop | --all | on the first run, count what is already open as new |
| any | -p, --profile name | run as this profile |
| any | -h, --help | print the help |
| any | -v, --version | print 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:
--profile <name>(orjot profile <name> …)- the
JOT_PROFILEenvironment variable - the nearest
.jot.json, walking up from the current folder - the default profile
JOT_API_TOKENandBACKEND_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 defaultThen run any command as either, without changing the default:
jot profile office list
jot --profile personal show cmv1x…
JOT_PROFILE=office jot watchEach 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 -pin plan mode. The comment moves toIN_PROGRESSand 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 toRESOLVEDand 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.