The command line, isc

isc is the daemon and its command line in one binary. It does everything the window does, and it lets scripts wait for a pane or follow events. The full list of commands is in the reference.

Naming things

• Refer to a pane by its number, as isc ls prints it: 3 or pane:3. A tab works the same way: 7 or tab:7. Refer to a project by its name or its number.
• If you don't give a layout command a pane, it acts on the pane it's run in ($INSENSICAL_PANE). Outside any pane, it acts on the pane with the keyboard.
• isc status and isc notify never guess. Outside a pane they need --pane.
• If two projects share a name, a command acts on the first one listed.
• Errors go to standard error as isc: …, with exit status 1.
• Every command accepts --socket PATH. It names the daemon's socket, in place of $INSENSICAL_SOCKET and the default.
• isc --help and isc COMMAND --help describe the commands. isc --version prints the version of isc only.

Which commands start the daemon

A command about panes, tabs or projects starts the daemon if it isn't running. So does isc status explain, and so does isc restart-server when no daemon is running. These never start it: daemon, kill-server, version, status with a state, notify, integrate, shell-integration, config, completions, and the agents' hooks.

Listing

isc ls prints projects, tabs and panes. isc list is the same command. It marks the current project, tab and focused pane with *. A project's line shows its number, name and root. A tab's line shows its number, its name if it has one, and zoomed while a pane fills it. A pane's line shows its number, size in columns and rows, placement (tiled, floating or minimized), state, program, and name or title. If an update has been installed under the running daemon, isc ls says so on standard error.

isc ls --json prints everything the daemon knows. That's the stable format for scripts. No other command has --json, and no command speaks the daemon's protocol directly.

Running things

isc run [--cwd DIR] [--keep] [WHERE] [-- COMMAND…]

It runs a command in a new pane, or the shell if you don't give one, and prints pane:N. The working directory defaults to the one you run isc in. The places are mutually exclusive: you can give only one of --project, --new-project, --split and --float. Use --beside to name the pane to split when it isn't the one isc runs in or the focused one.

WHERE	Place
nothing	A new tab in the current project
--project NAME	A new tab in that project
--new-project [--name NAME]	A new project for the working directory
--split right|down [--beside PANE]	Beside a pane, sharing its space
--float [--rect X,Y,W,H]	Floating above the current tab

With --keep, the pane stays open when the command ends, so you can read what it printed. Press Enter in it, or run isc close, to close it.

Typing into a pane and reading it

• isc send PANE TEXT types text.
• isc key PANE KEY… presses keys by name: ctrl-c, enter, escape, shift-tab, space, a. They're encoded the way the program in the pane expects. Write a key as you would in [keys], with ctrl, shift, alt, cmd or super held. Several keys are pressed in order: isc key 3 escape : w q enter.
• isc capture PANE [--vt] prints the screen and scrollback. With --vt, colours and styles are included as escape sequences.

Waiting

isc wait PANE [--until STATE]… [--timeout SECONDS]

• It succeeds when the pane reaches one of the states you name with --until (idle, running, waiting, done, failed, closed), and prints which one.
• Without --until, it waits for done, failed, waiting or closed.
• The states it waits for without --until are the ones that end the pane working on its own.
• It fails if the pane closes before reaching a state you asked for, or if there's no such pane.
• It exits with status 124 if the time runs out. The time can be a fraction of a second.

pane=$(isc run -- claude -p "fix the failing test")
isc wait "${pane#pane:}" --timeout 1800 && isc capture "${pane#pane:}" | tail -20

Events

isc events prints what happens, one JSON object per line. Each has an event and usually a pane.

event	Other fields
opened, status	status, note, progress, program
closed
focus	pane is null when no pane has the keyboard
bell
notification	title, body
activate	You picked the pane from a notification

Attaching from a terminal

isc attach [PANE] shows a pane in the terminal you run it in, and sends what you type to it. Press Ctrl+] to leave.

• The terminal gets the pane's history and then the program's own output. Nothing is redrawn or re-encoded on the way, so the terminal's own scrollback, selection and search work on it.

• Whatever was on the terminal's screen before moves up into its history. When you leave, the terminal is restored: mouse reporting off, cursor shown, and so on. Leaving doesn't affect the pane or its program.

• The pane takes that terminal's size, for everyone looking at it, and follows it when the terminal is resized. See Two windows.

• You reach a pane on another machine the same way:

  ssh build-host isc attach 3

Other commands

• isc config prints a default settings file. isc completions SHELL prints completions for bash, zsh, fish, elvish or powershell. Neither touches the daemon. just install-local and the packages install the completions for bash, zsh and fish.

  isc completions fish > ~/.config/fish/completions/isc.fish
  isc completions zsh > ~/.local/share/zsh/site-functions/_isc    # any directory in $fpath
  isc completions bash > ~/.local/share/bash-completion/completions/isc

  The output is a few lines that make the shell ask isc each time you press Tab, so the suggestions match the session at that moment:

  • commands and their options, with what each does;
  • a pane by its number wherever a command takes one, with what it runs, its state if it has one, and its project. The pane you're typing the command in is left out, because it's the one used when you don't name one;
  • a tab by its number, with its name or what its panes run;
  • a project by its name, after --project;
  • the states isc status takes and the sides isc focus takes.

  Asking never starts the daemon. If none is running, you still get commands and options, but not panes, tabs or projects. It asks the daemon at the default socket or $INSENSICAL_SOCKET, not one given with --socket on the line you're typing. Completions saved from a version before this one list commands only, so you have to print them again.

• isc version prints this version and the running daemon's, and whether they can talk to each other.

• isc kill-server stops the daemon and every program it runs, and returns once the daemon is gone.

• isc restart-server [--yes] moves the daemon to this version with everything still running. If no daemon is running, it starts one. If you answer no, everything stays as it is and the command exits with status 1.