npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

shijimi-editor-nightly

v0.10.0-nightly.20261121.bc2fbf6

Published

VS Code-style terminal IDE with Helix keybindings

Readme

shijimi

English | 日本語

An integrated development environment for the terminal (TUI). The screen is laid out like VS Code. For editing you can choose between Helix-style modal editing and modeless VS Code-style keys. The command is shj.

Home page: https://mm1995tk.github.io/shijimi-editor/ / Manual (English, with a Japanese version): https://mm1995tk.github.io/shijimi-editor/manual/ (source in website/home/ and website/manual/)

The UI is in English by default. To switch it to Japanese, set ui-language = "ja" in config.toml (see UI language).

Features

  • Modal editing and VS Code-style keys: choose Helix-style modal editing (normal / insert / select, : commands) or modeless VS Code-style keys
  • Multiple cursors (Helix-style): C / Alt+C copy the cursor to the line below / above, s splits a selection by a regex, , goes back to one cursor. Inserting, deleting, c and so on apply to every cursor
  • File tree (shows Git status as M / U / A)
  • LSP: diagnostics, completion, hover, signature help, go to definition, references, rename, code actions, symbol list, formatting
  • LSP configuration is written in a languages.toml that is compatible with Helix's (.shijimi-editor/languages.toml or ~/.config/shijimi-editor/languages.toml). If you are coming from Helix, copy your languages.toml to ~/.config/shijimi-editor/
  • Diff mode (Space G / Ctrl+G compares with HEAD; Space g / :pr compares with the base of a pull request): switches the whole editor to diff mode. Changed files are listed in a tree (CHANGES), and a changed file opens as the whole file in a split (or unified) diff. The right side is editable. The bar on the right edge shows where the changes are, and the parts that changed inside a line are highlighted (see below)
  • Image preview (PNG / JPEG / GIF / BMP / WebP / TIFF)
  • Markdown preview (Space m / :preview): renders headings, lists, code and tables, and shows them beside the buffer you are editing. Press it again to show only the preview at full width. Mermaid code blocks are shown as diagrams, and an image written alone on a line is shown as an image (see below)
  • Send the current context to an agent (Space a / Alt+A / command palette): formats the selection (or the cursor line) as path:line-line, the text, and the diagnostics on those lines, and after you check it in a preview, pastes it into the terminal panel (it does not press Enter)
  • Suggestions panel and ACP (Alt+I / Space i): lists suggestions such as "Resolve the conflicts?", "Create a PR?" and "Investigate the cause of the failure?" in the right panel, based on the state of git, LSP and the terminal. When you pick one, it asks an agent over ACP (Agent Client Protocol), shows the progress and the reply in the panel, and shows changes in diff mode. Comments proposed by an AI review are placed as unsent comments
  • Claude Code IDE integration: Claude Code running in the terminal panel can get the selection, the open files and the diagnostics, and you approve its changes as a diff (Claude Code writes the file after you approve; see "Agent integration" below)
  • A title line with the open file, syntax highlighting, Quick Open, project-wide search, a terminal panel, mouse support

Installation

nix run github:mm1995tk/shijimi-editor/release   # run it right away
nix profile install github:mm1995tk/shijimi-editor/release
go install github.com/mm1995tk/shijimi-editor/cmd/shj@latest      # installs the shj command
go install github.com/mm1995tk/shijimi-editor/cmd/shijimi@latest  # installs the same thing as shijimi
npm install -g shijimi-editor                                     # installs both shj and shijimi (Linux, and macOS on Apple silicon)

All of them get the latest release: the Nix commands follow the release branch, go install takes the newest tag, and npm takes the binaries published at release time. The same binaries are also attached to each GitHub Release as shj-<os>-<cpu> (shj-linux-x64, shj-linux-arm64 and shj-darwin-arm64; macOS on Intel is not supported). Unreleased changes on main are not included.

To try the unreleased changes on main, install the nightly build. It installs as shj-nightly (and shijimi-nightly) next to shj, reads ~/.config/shijimi-editor-nightly/ (falling back to ~/.config/shijimi-editor/ while that directory does not exist), uses its own socket directory, and has the [experimental] settings (features being tried out) on by default. Nix builds it from the newest main at install time; npm takes the build published every day (the nightly dist-tag, version X.Y.Z-nightly.<yyyymmdd>.<sha>), and the same binaries are attached to the nightly pre-release as shj-nightly-<os>-<cpu>.

nix run github:mm1995tk/shijimi-editor#shj-nightly
nix profile install github:mm1995tk/shijimi-editor#shj-nightly
npm install -g shijimi-editor-nightly   # installs shj-nightly and shijimi-nightly (Linux, and macOS on Apple silicon)
npx shijimi-editor-nightly              # run it without installing

To compare with the base of a pull request you need gh and gh auth login.

kisui-terminal

kisui-terminal is a separate app that works closely with shijimi-editor: it splits a window into panes and runs terminals (with shj inside), videos, images, PDFs, browser pages and a file tree in them. It has its own repository, version and releases, and ships with the shj it was tested with (inside its panes that shj runs first, whatever version you installed yourself). How to install it is in its README; how shj behaves inside it is in the manual.

Usage

shj            # open the current directory
shj ./src      # open a directory
shj main.go    # edit just one file (single-file mode, for $EDITOR)

shijimi works the same as shj (installing with Nix gives you both).

Given a file, shj starts in single-file mode. It does not start the file tree, LSP, terminal, diff mode or agent, and exits when you close it with :q or :wq (see Installation and startup in the manual).

Settings

Files are read in the following order, and later ones win (languages.toml uses Helix's format. If you are coming from Helix, copy your languages.toml to ~/.config/shijimi-editor/ and remove the keys shijimi-editor does not read). If a file has a mistake (a syntax error, a value of the wrong type), shijimi-editor does not start and prints the file, line and reason. Keys it does not read are ignored with a warning.

  1. Built-in defaults (gopls / rust-analyzer / typescript-language-server and others)
  2. ~/.config/shijimi-editor/languages.toml, languages.local.toml, config.toml, config.local.toml
  3. The project's .shijimi-editor/languages.toml, languages.local.toml, config.toml, config.local.toml

In each folder, config.local.toml wins over config.toml, and languages.local.toml over languages.toml. The .local files are for what you change on your own machine only: the config.toml that home-manager writes is read-only, and a project's .shijimi-editor/config.toml is shared through git. In a project, add .shijimi-editor/*.local.toml to .gitignore.

~/.config means $XDG_CONFIG_HOME when it is set. It is read from there on every OS, macOS included (not from ~/Library/Application Support).

UI language

The language of the UI text (status line, command palette, suggestions panel, error messages, shj --help) is English by default. Set ui-language in config.toml to switch it.

ui-language = "ja"   # "en" (default) or "ja"

shijimi does not choose the language from LANG or other environment variables. Any value other than en and ja is ignored. :config-reload applies a change without restarting.

Theme

Switch with theme in config.toml, or with :theme <name> while running (without a name it lists the themes). You can also choose it from the command palette ("Settings: Switch theme").

  • Built in: github-dark (default), dark-plus, light-plus
  • Helix's github_dark* maps to github-dark, and github_light* and light map to light-plus
theme = "github_light"

Listen address of port forwarding

Sets the address that :browser forward listens on.

[browser]
listen-host = "127.0.0.1"

Agent (suggestions panel)

Write the command of the ACP agent that runs the suggestions in ~/.config/shijimi-editor/config.toml (it is not read from a project's settings).

[agent]
command = "claude-agent-acp"
args = []

Example LSP settings (.shijimi-editor/languages.toml)

[language-server.my-gopls]
command = "gopls"
args = ["serve"]
config = { gofumpt = true }          # sent as initializationOptions
environment = { GOFLAGS = "-tags=integration" }

[[language]]
name = "go"
language-servers = ["my-gopls"]
roots = ["go.mod"]
indent = { tab-width = 4, unit = "\t" }

Supported keys: command, args, config and environment of [language-server.*]; name, language-id, file-types, roots, language-servers and indent.unit of [[language]].

Editor settings (config.toml)

keymap = "helix"          # "vscode" for VS Code-style keys

[editor]
line-number = "relative"  # how line numbers are shown
file-icons = true         # Nerd Font icons in the file tree; false shows ▸/▾
mermaid-command = "mmdc -q -i {in} -o {out} -b transparent -s 2"  # external command that turns mermaid into a PNG; empty disables it
watch-files = true        # detect and reflect file changes by other processes (such as AI agents). A file with unsaved edits waits for :reload
mouse-hover = true        # show the LSP hover when the pointer rests on a word in the editor for 0.5 seconds. false disables it (and stops receiving motion-only mouse events)

# Indent guides (a faint vertical line at each indent level). false disables them
[editor.indent-guides]
render = true

# Auto save (on by default; saves when editing pauses for 1 second; unnamed files are not saved)
[editor.auto-save.after-delay]
enable = true
timeout = 1000            # milliseconds

home-manager

Import the flake's homeManagerModules.default. settings is written to ~/.config/shijimi-editor/ as config.toml, and languages as languages.toml.

{
  # inputs.shijimi.url = "github:mm1995tk/shijimi-editor/release";
  imports = [ inputs.shijimi.homeManagerModules.default ];
  programs.shijimi-editor = {
    enable = true;
    settings = { keymap = "vscode"; editor.line-number = "relative"; };
    languages = {
      language-server.gopls.command = "gopls";
      language = [ { name = "go"; language-servers = [ "gopls" ]; } ];
    };
  };
}

With herdr, programs.shijimi-editor.herdr.enable = true makes programs.shijimi-editor.herdr.keysCommand a list for herdr's [[keys.command]] that runs shj exec ':sh hide' (hide the pane) on herdr.hideKey (default prefix+t). shijimi-editor does not write herdr's config.toml; put the list into your own herdr config. It is an empty list while herdr.enable is false.

programs.shijimi-editor.herdr.enable = true;
xdg.configFile."herdr/config.toml".source = toml.generate "herdr-config.toml" {
  # ...your herdr settings...
  keys.command = config.programs.shijimi-editor.herdr.keysCommand;
};

Markdown preview and mermaid

In a .md file, Space m (or :preview, or the command palette) opens a preview to the right of the buffer. It follows your edits and scrolls with the cursor. Press it again to show only the preview at full width, and a third time to close it. At full width, scroll with j / k or the mouse wheel.

Mermaid diagrams are turned into PNGs with mermaid-cli (mmdc) and shown. If mmdc is not on the PATH, or rendering fails, the source and the error are shown instead of the diagram. mermaid-command replaces it with another command ({in} is the input, {out} the output PNG). Rendered images are kept in ~/.cache/shijimi/mermaid.

An image written alone on a line, ![alt](path), is shown as an image in the same way. The path is relative to the Markdown file. Images in the middle of a sentence, and images that are not files (such as https://), are shown as text.

Keys (Helix mode)

Normal mode

| Key | Action | | --- | --- | | h j k l | Move (a number before it gives a count) | | w b e | Move while selecting a word | | x | Select a line (press again to extend) | | % / ; | Select all / collapse the selection | | v | Select mode | | d c y | Delete / change / yank | | p P | Paste after / before | | i a I A o O | Go to insert mode | | u U | Undo / redo | | f t F T + a character | Find a character in the line | | r + a character | Replace | | > < | Indent | | J | Join lines | | mm | Go to the matching bracket | | gg ge gh gl gs / <number>g | Jump | | gd gr | Go to definition / references | | Ctrl+O Ctrl+I | Go back / forward to where you jumped from (VS Code mode: Alt+← Alt+→) | | Ctrl+Alt+D Ctrl+Alt+U | Scroll down / up while the cursor stays on its line (like Ctrl+D / Ctrl+U otherwise: line by line while held on terminals that report key release, half a screen per press elsewhere). At the top or bottom edge of the screen the cursor stays on the edge and is pushed along | | ]d [d | Next / previous diagnostic | | ga | Go back and forth between the last file and this one (VS Code mode: Ctrl+Tab) | | / ? n N * | Search | | Ctrl+C | Toggle a line comment | | : | Commands (table below) |

Space menu

When you press Space, a popup at the bottom right of the editor area lists the keys you can press next. Close it with Esc or any key with no assignment.

| Key | Action | | --- | --- | | Space f | Open a file | | Space b | Open buffers | | Space w | Window (split) menu: v split the editor in two side by side, h l w move the focus, q o close the split | | Space e | Go to the file tree | | Space k | Hover. While it is shown, scroll with Ctrl+D / Ctrl+U (PgDn / PgUp, wheel); copy the Markdown source with y or by clicking [Copy] at the top right of the frame | | Space r | Rename | | Space . | Code actions (apply a diagnostic hint) | | Space s / Space S | Symbol list (in the file / in the whole project) | | Space d | Diagnostics list | | Space / | Search and replace in the whole project (floating window; see "Search in files") | | Space g | Open / close diff mode (compared with the base of the pull request) | | Space m | Toggle the Markdown preview (side by side → full width → closed) | | Space G | Open / close diff mode (compared with HEAD) | | Space v | Review menu (when comparing with the base of a pull request) | | Space y Space p | Copy to / paste from the system clipboard | | Space ? | Command palette |

Insert mode

Esc goes back to normal mode. Completion appears automatically when you type . or similar, or after 2 characters (Ctrl+X to trigger it by hand). Confirm with Tab / Enter. A snippet completion is inserted with its placeholder selected, and Tab / Shift+Tab move between placeholders.

: commands

:w :w <path> :wa :q :q! :wq :wqa :o <path> :n <path> :bc :bc! :fmt :reload :<line number> :sh <command> :grep [-x exclude-glob] [-i include-glob] <text> :replace [-x exclude-glob] [-i include-glob] <text> => <replacement> :pr [number] :gitdiff [on|off|split|unified] :preview :lsp-restart :config-reload :browser forward|list|stop :keymap [helix|vscode]

Global

| Key | Action | | --- | --- | | Ctrl+P | Open a file | | F1 / Ctrl+K | Command palette | | Ctrl+B | Toggle the file tree | | Ctrl+E | Switch focus between the file tree and the editor | | Ctrl+G | Open / close diff mode (compared with HEAD) | | Ctrl+` / Ctrl+J | Toggle the terminal (inside the terminal, only Ctrl+` ) | | Alt+R | Pane resize mode (←→ ↑↓ (hjkl) move the borders of the focused pane, < > boundary between the editor and the preview, = defaults, Esc to finish). You can also drag the borders with the mouse. The sizes are kept until you quit the editor | | Ctrl+S | Save | | Ctrl+W | Close the current file (remove it from the list of open files) | | Ctrl+Tab | Go back and forth between the last file and this one. It needs a terminal that supports the kitty keyboard protocol; elsewhere use ga in Helix mode, or Space b | | Ctrl+\ | Split the editor into two panes side by side / close the split (Ctrl+1 / Ctrl+2 move the focus). In Helix mode: Space w v, Space w h l w, Space w q o; also :vsplit and :only. Each pane has its own title line, and Space b, ga / Ctrl+Tab, Ctrl+O / Ctrl+I act on the focused pane. At most two panes, side by side; the same file is not shown in both. Not available in diff mode (one pane then) | | Ctrl+Q | Quit |

File tree

j/k move, Enter open, h/l collapse / expand, a new file, A new folder, r rename, d delete, y copy the relative path, Y copy the absolute path, R refresh, Esc back to the editor.

Diff mode

How you open it decides what you compare with (the base). Pressing the same key while it is open closes it, and pressing a different key switches the base.

| Key | Base | | --- | --- | | Space G / Ctrl+G / :gitdiff | HEAD (includes untracked files) | | Space g / :pr [number] | The base of the pull request (git merge-base <PR base> HEAD). Opens the PR of the current branch. For a PR on another branch, run gh pr checkout first (needs gh) |

  • From the top, the screen is the header (the base and what it is compared with), the sidebar and the diff, the help line (the keys you can use now), and the status line.
  • The sidebar is split 7:3 vertically, and CHANGES (a tree of the changed files) appears in the lower 3. A folder with a single child is collapsed like internal/config. Tab moves between it and the file tree.
  • A file without changes opens in the normal editor. A changed file opens as the whole file in Split (the base on the left, the current file on the right). A new file (including an untracked one) opens in a single editor. Lines are not colored, the bar on the right edge turns all green, and the +N / -N in the file name row at the top remain.
  • The right side (the current file) can be edited and saved as usual. The diff updates right away when you edit.
  • You can also switch to Unified (s, :gitdiff unified / split, or a click on the file name row).
  • The bar on the right edge of the diff shows where the changes are by color (green: added, red: deleted, blue: modified). The range now shown is brighter, and clicking scrolls to that position.
  • In a line where only a part changed, the changed part is highlighted in a darker color.
  • While comparing with the base of a pull request, you can review with Space v (comments on lines, ranges and files, replies, resolving, applying suggestions, viewed, submitting an approval and so on, and copying or opening the PR URL with Space v y / Space v o). You can comment only on files whose working tree content is the same as the PR's latest commit. See "Diff mode" in the manual for details.

| Key (with CHANGES focused) | Action | | --- | --- | | j/k | Move | | Enter / l | Open the file | | s | Toggle split / unified | | r | Refresh the list | | Tab | Go to the file tree | | Esc | Go to the editor |

Limitations

  • The terminal panel is a login shell ($SHELL -l) on a PTY. .zshrc and the like are read, and vim / top / lazygit work. While it has focus, almost every key goes to the shell (the global ones are only Ctrl+Q / Ctrl+` / F1 / Alt+R). Ctrl+J goes to the shell, so you can enter a newline in Claude Code even on a terminal that sends Shift+Enter as LF. There is one terminal (for several, use a multiplexer such as herdr or tmux); when the shell exits the panel closes, and the next time it opens a new shell starts. You can scroll back through the output with the mouse wheel.
  • Images and mermaid diagrams are drawn with the Kitty graphics protocol. You need a terminal that supports it (Kitty / Ghostty / WezTerm and others).

Development

Use the Nix devShell (Go, gopls, gomod2nix, git, and Node.js for the npm packages). With direnv, .envrc enters it automatically. Every command runs from the root of the repository.

nix develop            # or: direnv allow
go test ./...
go build ./cmd/shj
nix flake check        # every check CI runs: formatting and go test
scripts/tidy.sh        # go mod tidy / gomod2nix / go fix / nix fmt

Run scripts/tidy.sh before you push (outside the devShell, nix run .#tidy does the same); CI runs it and fails if it changes anything. It also updates gomod2nix.toml after you change go.mod.

User-visible strings live in one table per language, ui/internal/i18n/en.go and ui/internal/i18n/ja.go. Code asks for a string with i18n.T("key") and does not contain UI text. When you add a string, add the key to both tables (a test checks that they match).

Search in files

Space /, "Search: Search / replace in the project" in the command palette, :grep and :replace all open the same floating window (almost the full screen, leaving one column or row on each side). At the top are the conditions (four fields, Search, Replace, Include and Exclude, in bordered boxes in two columns, where the border color of the selected field changes; the toggles are below them), the matched lines (Matched) are at the lower left, and the lines around the selected one (View) at the lower right. When you change a condition, it searches again automatically after a short wait. When the Replace field has text, View also shows the - / + diff.

| Key | Action | | --- | --- | | Tab / Shift+Tab | Next / previous field | | ↑ ↓ / Ctrl+P Ctrl+N / PgUp PgDn | Select a matched line | | Enter | Open the selected line in its file | | Ctrl+X (Alt+X) | Exclude the selected line from the replacement / put it back (an excluded line is marked x) | | Alt+C / Alt+W / Alt+R / Alt+P | Match case / whole word / regex / preserve case when replacing | | Alt+1 | Replace only the selected line (the panel stays open and moves to the next match) | | Alt+Enter | Replace every target line | | Esc | Close |

  • Replace All opens the target files as buffers and replaces in them. The disk does not change until you save, and u / Ctrl+Z undoes it.
  • When regex is on, you can use captures such as $1 in the Replace field. When it is off, $ is just a character.
  • When there are more than 5000 results, Replace All is unavailable until you narrow the conditions.
  • The search covers text files under Git (including untracked files that are not ignored). Outside Git it searches everything except build directories. It also searches the unsaved content of open buffers.
  • The arguments of :grep -x '*.lock,dist/**' -i '*.go' foo and :replace foo => bar open the window with those values in the fields. Typing just :grep / :replace opens it with the previous conditions.

Excluding and including files in search

In the Include and Exclude fields, write comma-separated globs (for example *.lock,dist/**). With :grep / :replace you can also give them with -x / --exclude= (exclude) and -i / --include= (include). The initial values come from the [search] setting. Put anything you always want applied in ~/.config/shijimi-editor/config.toml or .shijimi-editor/config.toml.

[search]
exclude = ["*.lock", "dist/**"]
include = []

Port forwarding (:browser forward)

:browser forward <target port> [listen port] makes shijimi listen on 127.0.0.1 and forward over TCP to localhost:<target port> (both HTTP and WebSocket work). If you omit the listen port, a free port is chosen. :browser list lists the forwards, and :browser stop <listen port> stops one. Quitting shijimi stops them all.

When shijimi runs on a remote VM, running the following on your own machine lets your local browser see the development server at http://localhost:8080.

ssh -L 8080:127.0.0.1:<listen port> vm

Compared with running ssh -L directly, the advantages are that the listen port can be fixed, and that a server that listens only on 0.0.0.0 or IPv6 can still be reached through 127.0.0.1. If you do not need those, use ssh -L directly.

The listen address can be changed with listen-host in [browser] (see "Listen address of port forwarding" under Settings). By default it does not bind to 0.0.0.0. Change it only on a trusted network.

Agent integration

Claude Code IDE integration

shijimi supports Claude Code's IDE integration protocol (the same one as the VS Code extension and claudecode.nvim). On startup it starts a WebSocket MCP server on a free port of 127.0.0.1, and writes the destination and an authentication token to the lock file ~/.claude/ide/<port>.lock (0600; under ide/ of CLAUDE_CONFIG_DIR if it is set). It removes the file on exit.

When you start claude in shijimi's terminal panel, it connects automatically through the environment variables CLAUDE_CODE_SSE_PORT, ENABLE_IDE_INTEGRATION=true and FORCE_CODE_TERMINAL=true. A Claude Code running in another terminal can be chosen with /ide if its working directory is under shijimi's root.

Tools the agent can use:

| Tool | What it does | |------|------| | getCurrentSelection / getLatestSelection | The selection (or the cursor position) and its file | | getOpenEditors / getWorkspaceFolders | The open files / the roots | | getDiagnostics | LSP diagnostics (all files if the URI is omitted) | | openFile | Open a file (select a range with startText / endText) | | openDiff | Show a change as a diff. Enter approves and Esc rejects. Claude Code writes the file after you approve | | closeAllDiffTabs / close_tab | Reject and close the diffs that are waiting | | checkDocumentDirty / saveDocument | Check for unsaved changes / save |

  • Whenever the selection or the cursor moves, it sends selection_changed.
  • While connected, Space a / Alt+A (send the current context to the agent) sends at_mentioned instead of pasting. When not connected, it shows the preview and pastes into the terminal as before.
  • Connections without an authentication token, and connections from a browser (with an Origin header), are refused.

Control socket

A running shijimi creates a Unix socket (0600) and tells its location through the environment variable SHIJIMI_SOCKET. From a shell in the terminal panel you can run the following. Only operations that the IDE integration lacks are kept.

When SHIJIMI_SOCKET is not set (for example in a shell command bound to a key of the herdr terminal multiplexer, which passes only its own variables), shj looks for a running shijimi by itself. The socket is $XDG_RUNTIME_DIR/shijimi-<uid>/<pid>.sock (shijimi-nightly-<uid> for the nightly build; under the temporary directory when XDG_RUNTIME_DIR is not set), and shijimi started inside herdr (HERDR_ENV=1) also links it as herdr-<HERDR_WORKSPACE_ID>/<HERDR_PANE_ID>.sock in that directory. Inside a herdr workspace (HERDR_WORKSPACE_ID set), shj uses the link of its pane HERDR_PANE_ID, or the only shijimi running in the workspace; outside herdr it uses the only shijimi running for your user. Sockets that no longer accept a connection are skipped, and shijimi removes its own files when it quits. When none is found, or more than one, shj writes an error and exits with code 1 (set SHIJIMI_SOCKET to choose one).

  • shj diff [path]: switch to diff mode (base HEAD). With path, opens that file as a diff
  • shj exec ":<command>": run a : command as it is (for example shj exec ":preview"). On success it writes the status-line text to standard output; on failure it writes the error text to standard error and exits with code 1. It returns an error without running commands that quit or discard (:q :q! :wq :bc! and so on), commands that open a picker when given no argument (:o :theme :grep :replace :symbol :action, and :pr with a non-numeric argument), and :reload and :bc on a file with unsaved changes

When the first argument is diff / exec / command-end / skill, it is treated as a subcommand. Write a file with the same name as ./diff.

shj skill install [destination] writes a skill (SKILL.md) that describes how to use this command. Without a destination it writes to ~/.claude/skills/shijimi/.

shj open and shj status were removed and replaced by the IDE integration (openFile / getOpenEditors / getCurrentSelection).

Inside a terminal multiplexer

When shijimi runs in a terminal multiplexer, [experimental] multiplexer is true in config.toml (the default is true in the nightly build and false in the stable build; the old key herdr is read as the same key) and the multiplexer is supported, Ctrl+` , Space t, :sh, :sh <command>, :run and :! use a pane of the multiplexer instead of the terminal panel. The multiplexer then detects the state of the agents run in the pane, notifies you and restores them.

Which multiplexer is used is set by multiplexer in [terminal]: "auto" (default), "herdr", "tmux", "zellij", "cmux", "gui" or "none". "auto" takes the panes of kisui-terminal in its primary terminal (see the manual); otherwise it follows the parent processes of shijimi and takes the first multiplexer it finds, that is the innermost one when several are nested (for example tmux inside herdr); with none, the terminal panel is used. "none" always uses the terminal panel. herdr, tmux, zellij, cmux (macOS only) and kisui-terminal are supported. Without a supported multiplexer, or with multiplexer = false, the terminal panel is used as before.

The rest of this section describes herdr (HERDR_ENV=1); tmux is described at the end.

  • The first time, a pane is created right below shijimi's pane (herdr pane split) in the workspace root, with SHIJIMI_SOCKET and the IDE integration variables, and gets focus. The next time, the same pane is shown again; when it has ended, a new one is created. Pressing the key again hides it (zooms shijimi's pane), and shj exec ":sh hide" in the pane does the same. Ctrl+J shows the pane and moves focus there; to come back, use herdr's key (Ctrl+B k by default).
  • :sh <command> runs the command in the pane. Space a / Alt+A pastes the context into the pane without Enter (at_mentioned is unchanged while the IDE integration is connected).
  • The shell of the pane (zsh, bash) reports each exit code with shj command-end <code>, so the suggestion to investigate a failed command appears as before. The pane ends with exit or herdr's Ctrl+B x, and shijimi closes the pane it created when it quits.
  • The screen, scrolling, copying with the mouse and OSC 52 of the pane are herdr's, and shijimi's own keys (Ctrl+Q, Ctrl+` , Alt+R, F1) do not work in it.

tmux 3.1 or later (TMUX set) works the same way. The pane is created with tmux split-window -v -l 30% below shijimi's pane (the one in TMUX_PANE), with the variables passed by -e; it is hidden and shown again by zooming shijimi's pane (resize-pane -Z), text is sent with send-keys, and the pane is closed with kill-pane when shijimi quits. To go back from the pane, use tmux's own keys (prefix, then an arrow key). shijimi does not set up tmux keys.

zellij 0.44 or later (ZELLIJ set; checked with 0.45.1) works the same way. The pane is created with zellij action new-pane --direction down below shijimi's pane, starting the shell through env to pass the variables, and gets focus (focus-pane-id). It is hidden and shown again with toggle-fullscreen on shijimi's pane, text is sent with write-chars (a command line) or paste (the context), and the pane is closed with close-pane when shijimi quits. Every action names the pane by --pane-id, so it works wherever the focus is. zellij has no way to set the size of a tiled pane, so the new pane takes half of the height (not 30%). To go back from the pane, use zellij's own keys (Alt+Up by default, or Ctrl+P then an arrow key). shijimi does not set up zellij keys or layouts.

cmux (macOS only; CMUX_WORKSPACE_ID and CMUX_SURFACE_ID set) also works, with these differences. The pane (a cmux "surface") is created below shijimi's surface with cmux new-split down --surface <the surface of shijimi> --focus true --command .... new-split has neither a working directory nor an environment option, so the command that cmux types into the new pane's shell is cd <root> && exec env <variables> <shell>, which you can see in the pane. Text is sent with cmux paste (and cmux send-key enter for a command that is run), and the pane is closed with cmux close-surface when shijimi quits. cmux has no zoom, so hiding the pane only moves the focus back to shijimi's surface; the pane stays on the screen, and the next Ctrl+` moves the focus to it again. To go back to shijimi yourself, use cmux's keys for moving between panes. It is not chosen on Linux. The cmux commands were written from its CLI documentation and source and have not been tried in a real cmux yet.

Editing the manual and the home page

The manual is built from website/manual/ with MkDocs Material. The home page is the plain HTML in website/home/. When you push to main, GitHub Actions publishes both to GitHub Pages: the home page at the root and the manual under /manual/. To preview the manual locally, run:

pip install -r website/manual/requirements.txt
mkdocs serve --config-file website/manual/mkdocs.yml

The manual has an English page (name.en.md, the default) and a Japanese page (name.ja.md) for each page. When you change one, change the other too. website/manual/check-translations.sh checks that every page has both languages and the same structure, and CI runs it on pull requests (it also fails when only one language of a page changed; add [skip-i18n-check] to the pull request title to skip that part, for a typo fix for example).

The screenshots and the demo video of the home page (website/home/images/) are recorded with vhs, and the ones with images and mermaid diagrams are taken in kitty, because they need the Kitty graphics protocol. After a change to the screen, run website/home/screenshots/record.sh (it needs Nix) to record them again. The scenes are in website/home/screenshots/tapes/ (vhs) and website/home/screenshots/kitty/ (kitty).

License

MIT