JsonUI
← jui vizSet up jui vizInstall the plugin, start the server and choose the language of the page. Then keep it up to date, remove it, or fix it when it does not work.9 min read
Install
What you need• jsonui-cli (the `jui` command), on Python 3.11 or later. • Claude Code, running on this machine — the CLI, the desktop app or an IDE. Cloud sessions are not shown. • Codex too, through its app-server daemon (see Codex sessions).
Install the pluginIn Claude Code, install the plugin once. From then on, every Claude Code session tells `jui viz` about each step of its work.
Claude Code
/plugin marketplace add Tai-Kimura/jsonui-cli
/plugin install jui-viz@jsonui
• Your `~/.claude/settings.json` is not changed. To remove it, remove the plugin. • When the `jui viz` server is not running, the plugin does nothing and returns at once. It does not slow Claude Code down.
Where plugins are not availableThis command adds the same hooks to `~/.claude/settings.json` instead. The hooks and settings you already have stay as they are.
shell
jui viz hooks install --dry-run # show the change, write nothing
jui viz hooks install
The file as it was before the change is saved in `~/.local/state/jui-viz/backups/` (`$XDG_STATE_HOME/jui-viz` or `$JUI_VIZ_HOME` instead, when you set one).
Start it
shell
jui viz serve --open
Your browser opens `http://127.0.0.1:7788/`. To stop the server, press Ctrl+C or run `jui viz stop`.`jui viz start` runs it in the background instead and prints the URL.Sessions that were already running before the hooks went in also appear in the list (read from `claude agents --json`).
A stop ends within 5 secondsOnce the server takes a stop (Ctrl+C, `jui viz stop`, or a TERM signal), it ends within 5 seconds whatever is holding it up, and clears its files. If a step held it that long, the server prints the line stop held in <step> for 5 s; ending without it, naming the step (starting, the readers, the tasks, the file watchers, the web server, the pools, the files, the exit). A server started with `jui viz start` writes that line to serve.log in its state folder. A TERM that comes while the server is still starting is a stop like any other: it ends with code 0 and its files cleared. A stuck server leaves a record. Each `jui viz start` moves the last run's serve.log to serve.log.1 (up to 5 kept), and `jui viz stop` does the same for a server it had to force, naming the kept file. The server writes every thread's stack to its log on a USR1 signal, and stop sends one before it kills. When the server's loop has not run for 10 seconds, it writes one line (the connections open, the last request, the ones being handled) and the stacks, once each time, and a line when it runs again.
Change the languageThe page is in English by default, and Japanese is available. There is no language switch on the page itself: its Settings (設定) section holds the near weather, the bills and the card notes, nothing else. You choose the language in jui viz's settings file, and the server reads it when it starts.
1
Stop the server if it is running: `jui viz stop`.
2
Open `config.json` in jui viz's state folder: `~/.local/state/jui-viz/config.json` (`$JUI_VIZ_HOME/config.json`, or `$XDG_STATE_HOME/jui-viz/config.json`, when you set one). If it is not there, create it.
3
Write "language": "ja" in it, as below. Keep any other keys already in the file. To go back to English, write "en".
4
Start the server again (`jui viz start`, or `jui viz serve --open`) and reload the page.
5
To check, run `jui viz doctor`: its language row says which language the server uses, and any problem with your settings.
~/.local/state/jui-viz/config.json
{
"language": "ja"
}
Read only when the server startsEditing config.json does nothing to a running server; restart it. "language" takes any language code (BCP 47: fr, de, it, ko, zh-CN, zh-TW, pt-BR …). It is the page's language for dates, numbers and the plural forms; the words are bundled for en and ja, and any other code starts from English, under your own "strings" file (below). A value that is not a language code is reported as a warning and English is used. A config.json that is not a JSON object is ignored with a warning, and the defaults are used.
For one start only: JUI_VIZ_LANGUAGEThe environment variable JUI_VIZ_LANGUAGE comes before config.json. Set it on the command that starts the server, e.g. `JUI_VIZ_LANGUAGE=ja jui viz start`. While it is set, `jui viz doctor` adds (from JUI_VIZ_LANGUAGE) to its language row.
Your own words"strings" in the same config.json names a file of your own words: a flat {key: words} for any of the page's keys (the keys are those of `jui_cli/viz/web/i18n/en.json` in jsonui-cli). A path that is not absolute is taken from the state folder. A key is looked up in your file first, then the language, then English. A key it does not know, or words whose {slots} differ from the bundled words, are left out with a warning in the serve log and in `jui viz doctor`. Words that change with a count are written {"one": …, "other": …}. `jui viz strings template --lang fr > fr.json` prints every key with its English words, and each plural key with that language's plural forms (one, many, other for fr): a file to translate, keeping the {name} slots. Name it as "strings" beside "language": "fr". `jui viz doctor` says the words' language, the locale, and how many of the file's keys were used.
~/.local/state/jui-viz/config.json
{
"language": "en",
"strings": "my-words.json"
}
~/.local/state/jui-viz/my-words.json
{
"status.waiting": "Needs your OK"
}
What follows the language, and what does notThe words jsonui-doc gives the server room (a cost meter's name, a model file's problem lines) follow the page's language too. Only what your own files say, such as a node's label, stays as written (measured on a cost day's reply under English: 4 runs of Japanese, all of them node labels the example model writes in Japanese). jsonui-doc's own terminal output is unchanged. What only the terminal and the serve log show is English whatever the page's language (`jui viz status` prints stopped).
How the page's words came to beThe page is in English by default, and every word it shows comes from one table, with the same keys in English and Japanese. `jui viz doctor` prints language: en on a fresh install. Where the Japanese table says something one way, the English table does too, except 21 groups that stay apart on purpose, where the English names two things (a status and a sign's short word, say).
These articles give the English words first and the Japanese words after them, as the page shows them with Japanese on.
Update to a new version
1. Restart the serverAfter updating jsonui-cli, restart the server. The new `jui viz stop` also finds a server an older version left running.
shell
jui viz stop
jui viz start
2. Update the pluginThen update the plugin, and restart each Claude Code session so it loads the new one. In Claude Code, `/plugin` does the same from its menu.
shell
claude plugin marketplace update jsonui
claude plugin update jui-viz@jsonui
Until you restart the sessions, the robots and permission prompts keep working, but question cards do not appear.
3. If you installed with hooks insteadIf you installed with `jui viz hooks install` instead of the plugin, run it again. It adds the question hook and points the test-progress setting at the new state folder. It also adds the --stop hooks the card's Stop (停止) needs.
shell
jui viz hooks install
Stopping a server that does not answer`jui viz stop` also stops a server of yours that no longer answers, after checking its pid and command line; KILL if TERM has not ended it 5 seconds later. The server works in its state folder, not in the folder it was started from.
The page picks up the new filesThe server sends every response with Cache-Control: no-store and names the page's CSS and scripts by their content, so a page opened after an update fetches the new files once under new names.
Plugin versions that matter• The plugin is what makes a question wait longer than 5 minutes. • The plugin is what lets the card's Stop (停止) stop a session (see Talk, prompts and notifications).
Remove itIn Claude Code, run `/plugin uninstall jui-viz@jsonui`.If you installed with `jui viz hooks install`, use these commands:
shell
jui viz hooks uninstall # remove the hooks (your other hooks stay)
jui viz relay uninstall # unregister the relay
When it does not workRun `jui viz doctor` first. It checks what jui viz depends on and says how to fix what it finds.
shell
jui viz doctor
It checks Python, the libraries it needs, the `claude` command, the hooks (also the timeout of the plugin's question hook), the server, the port, the folder test results are read from, the near weather, the usage-limits statusLine, what the git box and the shredder can see, and whether the Codex daemon runs (never NG: it is optional).
No robotsCheck that jui-viz is enabled in `/plugin`, or that `jui viz hooks status` reports the hooks.
The port is takenChange it, as in `jui viz serve --port 7789`.
Safety
Only your machineThe server listens on `127.0.0.1` only. It cannot be seen from your LAN or another device.
A new token each startEach start creates a new token. Writes that do not come from the browser page, and connections from another site's page, are refused.
Tool input stays in memoryTool input (file contents and commands) is kept in memory only. It is written to a file only when you pass `--record`.
Outside connectionsA running server fetches public cloud price lists for the infra cost simulator 10 minutes after it starts and then once a day (a file that failed is fetched again alone an hour later), on by default: https to pricing.us-east-1.amazonaws.com and prices.azure.com only, sending nothing about your project. `jui viz cloud-prices off` turns it off (from the next start), and `jui viz doctor` says which. The near weather connects only when you turn it on. The Slack intake connects only once you write slack.json: to Slack, to the router you choose, and with mode connector to Claude. See the Slack intake article.
Keep reading
jui viz`jui viz` shows the Claude Code sessions and subagents running on your machine (the Codex sessions too) as rooms and robots in the browser. Start with the demo below, then pick the article for what you want to do./viz
Codex sessionsCodex sessions in the same rooms, their permission requests on the page, starting one from the bell, and local models from LM Studio or Ollama. Also prompts from the card, the History tab and Clock out./viz/codex