Skip to content

The command line, isc ​

isc is the daemon and its command line in one binary. Anything you do in the window you can do from a shell, and scripts can wait for a pane or follow events. The full list of commands is in the reference.

Naming things ​

  • A pane is its number as isc ls prints it (3 or pane:3), or the name you gave it with isc rename or --name. A tab works the same way (7, tab:7 or its name). Names ignore case, and a number is always a number.
  • A project is its name or its number. If two projects share a name, the name means the first one listed. See Projects.
  • A layout command with no pane acts on the pane it's run in ($INSENSICAL_PANE), or outside any pane, the one with the keyboard. isc status and isc notify outside a pane need --pane. Every command takes --socket PATH in place of $INSENSICAL_SOCKET.
  • isc --help and isc COMMAND --help describe the commands. isc --version prints the version of isc only, with the commit it was built from when you built it from source, such as isc 0.7.0+bcb3964c.

Which commands start the daemon ​

A command about panes, tabs or projects starts the daemon if it isn't running. So do isc status explain, isc notify --test, isc notify --sinks, and isc restart-server.

These never start it: daemon, kill-server, version, status with a state, notify with a title, integrate, shell-integration, config, completions, host and the agents' hooks. With --host, the same holds on the other machine.

Nothing is written to a log file. Where you read what insensical says depends on what started it:

Started byWhere it prints
iscWhere you ran it
The windowWhatever started the window. Run insensical in a terminal to read it. Mistakes in the settings file show here and in the settings sheet
The user unitjournalctl --user -u insensical
On demand, by a window or commandNowhere. Stop the daemon and run isc daemon in a terminal

Listing ​

isc ls (or isc list) shows your projects, tabs and panes, and marks the current project, tab and focused pane with *.

  • A project's line has its number, name and root, and asleep while it sleeps.
  • A tab's line has its number, its name if it has one, and zoomed while a pane fills it.
  • A pane's line has its number, state, program, directory (~ for home), name or title, and what its state is about, each after two spaces. Empty parts are left out.

Sometimes more follows: floating or minimized; what a waiting pane waits for and how long (wants permission, 2h); the name a program gives itself, in brackets; how many things it reports; opened by pane:N; and keeps agents out. Scripts should read isc ls --json for these. If an update was installed under the running daemon, isc ls says so on standard error.

text
* project:5  api  /home/you/code/api
    tab:4  zoomed
      * pane:3  waiting  node  ~/code/api  Refactor the auth middleware  Allow the edit to session.rs?  wants permission, 2h  (claude-code)
        pane:6  idle  nvim  ~/code/api  src/session.rs  opened by pane:3
  * tab:8  servers
      * pane:10  idle  fish  ~/code/api  floating
        pane:7  waiting  cargo  ~/code/api  minimized
  project:9  web  /home/you/code/web  asleep
      tab:12
        pane:11  idle  fish  ~/code/web

These narrow the list. Given together, a pane must fit them all. The command fails with nothing listed when none fits.

OptionLists
--program NAMEPanes running that program, by process name (psql) or the name it reports (claude-code), in any case
--state STATEPanes in that state: idle, running, waiting, done or failed. isc ls --state waiting is everything waiting for you
--openedPanes opened by the pane isc runs in
--herePanes of the tab the pane isc runs in

isc ls --json prints everything the daemon knows and is the stable format for scripts. isc usage, isc clients and isc api take --json too, and isc integrate --status always prints JSON.

Running things ​

isc run opens a command in a new pane, or your shell if you give none, and prints pane:N.

sh
isc run [--cwd DIR] [--keep] [--name NAME] [--background] [--wait] [--json] [WHERE] [-- COMMAND…]

The working directory is the one you run isc in. Give only one place, as WHERE in every isc command. With --split, --beside names the pane when it isn't the one isc runs in or the focused one.

--keep leaves the pane open when the command ends. Press Enter in it, or run isc close, to close it.

isc run and isc split share these options:

OptionDoes
--waitWaits for the command to end, then prints the end of its output (up to 4 KB of whole lines) and a last line with its status (exit 7, or exit 7, 1980 earlier lines left out). It exits with that status, so isc run --wait -- make test && echo passed works. The pane closes afterwards unless you add --keep. If you stop isc while it waits, the pane stays open
--jsonPrints {"pane":12,"tab":7} in place of pane:N. With --wait it's printed once the command ends, with status, output and, when lines were left out, left_out

A pane you open from inside another pane remembers that pane as its opener. isc close --opened, run in that pane, closes every pane it opened and every pane those opened, so an agent can tidy up without touching your panes. A pane you've typed into or focused stays, with what it opened, and the command says pane:9 left open: the user is using it. isc close --opened 3 does the same for pane 3.

isc do NAME runs a command by name: one of your own from [commands] in the settings file on this machine (see Changing keys), or one of the commands in the reference.

sh
isc do tests            # your own
isc do split-right      # one that exists already
isc --host build do tests
  • Steps run in order on the daemon the command is for. If one fails, isc do stops there, says which step, and exits with an error.
  • A command only an interface can do, such as palette or copy, is refused, and so is a list at the step that holds one.
  • A step that would end something running, such as close-tab, is refused unless you say --yes.

Typing into a pane and reading it ​

CommandDoes
isc send PANE TEXTTypes text. If it starts with one of isc's own options (--host, --rights, --socket), put -- first: isc send 3 -- --host. The same goes for a title given to isc notify, which also has --test, --sinks and --pane
isc key PANE KEY…Presses keys by name, in order: isc key 3 escape : w q enter. Write a key as in [keys]: ctrl-c, enter, escape, shift-tab, space, a, with ctrl, shift, alt, cmd or super held

isc upload, isc ask, isc capture and isc history are in every isc command.

Uploading. isc upload PANE FILE… sends files to the pane's machine and types each path at the cursor with a space after it, as if you'd dragged the file in, and presses nothing else. isc upload prints where each file was kept: .insensical-uploads in the pane's directory, made on first use with a .gitignore that keeps it out of git. Files are limited to 50 MB, and a file keeps its name without replacing another.

Asking. What isc ask waits for depends on the pane:

  • At a shell that marks its commands, it waits until the command ends, prints the end of its output with a closing line as isc capture --last does, and exits with the command's status: isc ask build 'make test'.
  • Anywhere else, such as a database prompt, it waits until the pane has printed nothing for a second (--quiet SECONDS changes that) and prints what came after the line: at most 4 KB with the end kept, and a closing line with a --since token. isc ask psql '\dt'. An answer that pauses for longer is cut short.

isc ask --timeout SECONDS gives up with status 124. --anyway types into a busy pane.

Capturing. isc capture PANE prints at most 4 KB, the end kept. Control characters print as escapes like \u{1b}, and trailing spaces and empty lines are left out. It always closes with a line starting --: how many earlier lines were left out, if any, and a token to read on from, as in -- 1980 earlier lines left out; --since 3fa2c1d0.

OptionPrints
--allAll of it
--screenOnly what's in view
--tail NOnly the last N lines
--last [N]Only what the latest command printed, without its prompt. The closing line says how it ended (exit 1, or running). --last 2 is the one before. It goes by the marks your shell writes around each command (see Commands that fail, and short commands) and says so when the shell writes none. The output of a pane's last 20 commands is held, so --last 21 says it's no longer held
--grep PATTERNOnly lines matching a regular expression. --context N adds N lines around each. With no match it prints only the closing line and exits with 1
--since TOKENOnly what came after the read whose closing line gave the token, so reading a log again prints nothing twice. A pane keeps its last 8 reads; if the place is gone, all of it is printed and the closing line says so
--vtAll of it with colours and styles as escape sequences. It takes none of the other options

Options combine: isc capture 4 --last --grep error --context 2. --since can't be used with --last or --screen.

What was run in a pane. isc history PANE prints the commands run there, newest last: when it started, how long it ran, how it ended (exit 1, or running), the directory, and what was typed.

text
14:02:11  1.2s  exit 0  ~/code/api  cargo fmt
14:02:20  38s  exit 101  ~/code/api  cargo test
14:03:05  4m12s  running  ~/code/api  npm run dev

It prints at most 4 KB, the newest kept, then a line saying how many earlier ones were left out. --all prints all the last 100. --json prints them with times in milliseconds since 1970.

Waiting ​

sh
isc wait PANE [--until STATE]… [--timeout SECONDS]
  • It waits for the states named in every isc command and prints which one it reached.
  • It exits with 124 when time runs out. The time can be a fraction of a second. inf is refused.
sh
pane=$(isc run -- claude -p "fix the failing test")
isc wait "${pane#pane:}" --timeout 1800 && isc capture "${pane#pane:}" | tail -20

Or wait for one specific thing. Give one of these, and none with --until. Each fails if the pane closes first and exits with 124 on timeout.

OptionWaits for
--output PATTERNA line on the screen or in the history that matches a regular expression, and prints it. It succeeds at once if the line was printed before you asked. A line the pane's width broke in two is two lines, so wait for a shorter piece. Colours don't matter
--promptThe command running at the shell to end, by your shell's marks. It prints the end of the output and a closing line as isc capture --last does, and exits with the command's status. With nothing running, it does that at once for the last command. A shell that writes no marks is an error
--quiet SECONDSThe pane to print nothing for that long
--addressThe pane to show an address on this machine with a port (localhost:5173, 127.0.0.1:8000, 0.0.0.0:3000, [::1]:4000). It prints the last one shown, as http://localhost:5173/. One printed before you asked counts
sh
pane=$(isc run -- npm run dev)
isc wait "${pane#pane:}" --output "ready in" --timeout 60 && xdg-open http://localhost:5173

Agents. These start an agent and wait for it. See Agents.

sh
isc agent start claude|codex|gemini TASK [--split right|down | --tab] [--front] [--cwd DIR] [--name NAME] [--json]
isc agent start claude|codex|gemini QUESTION --quiet [--cwd DIR] [--timeout SECONDS]
isc agent wait PANE [--timeout SECONDS] [--all]
isc agent reply PANE [--all]
isc agent tell PANE MESSAGE
isc agent answer PANE yes|no|TEXT
  • isc agent start opens the agent in a new tab, or beside your pane with --split, with TASK as its first prompt, and prints pane:N. The keyboard stays where it is unless you give --front. It refuses an agent whose hooks aren't set up, and a --name that an open agent pane already has.
  • With --quiet it runs the agent's own one-question mode on this machine, with no pane, prints only the answer and exits with the agent's status.
  • isc agent wait waits until the agent's turn ends, then prints done or failed with its reply, or waiting with its question. It waits 30 minutes unless you give --timeout, then exits with 124. It fails sooner, saying why, if the agent's hooks have said nothing 30 seconds after it started.
  • A reply is cut to its last 4 KB, with a closing line saying how many lines were left out, unless you say --all.
  • isc agent answer prints the state the agent moved on to, and fails if it still asks 10 seconds later.
  • All of them take --host, except --quiet.

Any request, as JSON ​

Everything the window does is a request to the daemon, and isc api sends one. Use it for what the commands don't cover.

sh
isc api '"State"'                                  # the whole state, as `isc ls --json` gives it
isc api '{"Mute":{"pane":3,"on":true}}'
isc api '{"Float":{"pane":3,"rect":{"x":0.5,"y":0.1,"w":0.45,"h":0.8}}}'
echo '{"Zoom":{"tab":2,"on":true}}' | isc api

A request is one JSON value: a name alone if it takes nothing, or an object with the name as its key. The answer is JSON: "Done", {"Pane":7}, {"State":{…}}, {"Text":"…"}. "Clients", {"List":{"dir":"~/src","deep":false}} (a directory's names), "Hooks" and "Settings" are here too.

To see what's available, ask isc api. It sends nothing and starts no daemon.

sh
isc api                 # every request
isc api Float           # what one holds
isc api --json          # the same list, as JSON
isc api Float --json

With no request it lists every request: its name, the right it needs, and what it does. NAME is the request's name alone, without quotes; capitals don't matter, and hide-floats is HideFloats.

Float: Lifts a pane out of the layout to float, or moves one that floats. The rectangle is in fractions of the tab.
Needs the right to arrange.

  pane  a whole number
  rect  {x: a number, y: a number, w: a number, h: a number}

Example:  isc api '{"Float":{"pane":3,"rect":{"x":0.5,"y":0.1,"w":0.45,"h":0.8}}}'
Answers:  "Done"
  • --json gives name, needs, says, fields (each with name, is, optional and defaulted), example and answers.
  • isc api '"?"' fails and lists the names. So does piping in an empty standard input.

Events ​

isc events prints what happens, one JSON object per line. Each has an event and usually a pane. It ends if you stop reading for long enough; run it again.

eventOther fields
opened, statusstatus, note, progress, program, kind (permission, question, auth or null), app
kindThe same fields. What a waiting pane waits for changed, and its status, note and progress didn't
closed
focuspane is null when no pane has the keyboard
bell
notificationtitle, body
activateYou picked the pane from a notification
diddid (what was asked, such as mute or close), revision, and by: the client's number, its kind, its name and its pane. It has no pane of its own

did is printed after a client opened, closed, moved, named, muted, put to sleep, changed a daemon setting, or stopped something. It says who:

json
{"event":"did","did":"mute","revision":41,"by":{"client":12,"kind":"command-line","name":"desk","pane":null}}

by.pane is the pane the command was run in, when the daemon could check that, and null otherwise. Looking, typing and refused requests aren't reported.

Who is connected ​

isc clients shows who is connected to the daemon.

session:12  desk · App  0.7.0  look,type,arrange,manage  6 connections  pid 4121  looking at pane:3  for 512s
session:31  kitchen tablet · Browser  0.7.0  look,type  2 connections  pid 3990  through `isc proxy` (claimed, not verified)  for 40s

Each line is one session: a window, a browser, isc tui, or the hub's notifications. It has the session's number, the machine it's on (or a browser's device) and what it is, its version, what its connections can do between them, how many there are, the process at the other end of the socket, the pane it's looking at, and how long it's been connected.

  • A command you run, and a program in a pane, aren't listed.
  • A guest's browser, paired with isc hub device add --only, shows what it's kept to: only project 4 or only pane:12.
  • isc clients --json adds each session's scope ({"project": 4}, {"pane": 12}, or null for one that sees everything) and its connections.

Putting a session off. isc disconnect 12 (or session:12) ends every connection of that session: a window's panes and notifications go with it, and it connects again only when you press Enter in it. It needs the right to manage, and you can't end your own. With --host NAME it acts on that machine's server.

  • Each browser is a session of its own, named by its device: two browsers paired as the same device are two lines. Putting one off doesn't unpair it. To keep it out, remove its device with isc hub device rm, which ends all its sessions.

Rights. A connection has up to four:

RightLets it
lookSee projects, tabs and panes, each pane's screen and history, what programs use, who is connected, a directory's names, the daemon's settings (with notify-url and notify-command cut short), how the last notification sent outward went, and agents' hooks
typeType and paste into a pane, set the size it's shown at, and report a state or a notification for it
arrangeOpen a pane with any command, close, split, move, float, focus, name, mute, put to sleep and wake, and choose icons
manageStop the daemon, change its settings, add or remove agents' hooks, and send a test notification outward

You get all four unless you ask for fewer with --rights, before any command:

sh
isc --rights look ls
isc --rights look,type attach 3
  • A command that needs a right the connection wasn't given is refused, and says which. Typing without the right to type is dropped, silently.
  • look reads everything on every screen, including any password, key or token a program printed there. It changes nothing.
  • type, arrange and manage each let a client run programs as you. arrange opens a pane with any command, so it needs no type to run one. manage changes what the daemon runs. Give any of them only to what you'd give your account.

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. You reach a pane on another machine the same way:

sh
ssh build-host isc attach 3
isc --host build attach 3

The second runs isc here and needs the machine named first: see Other machines, over ssh.

Other commands ​

Every isc command is listed in the reference, including isc config, isc completions, isc version, isc kill-server, isc restart-server and isc upgrade. Two things it doesn't say:

  • isc restart-server starts a daemon if none is running. If you answer no, everything stays as it is and the command exits with status 1.
  • isc upgrade prints the command that updates insensical if a package or Homebrew installed it: see A new version installed underneath.

Shell completions. The packages install them for bash, zsh and fish. On a Mac they're also inside the application, in Contents/Resources/completions. To put them somewhere yourself:

sh
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

Tab then offers commands and their options, the session's live panes, tabs and projects wherever a command takes one, the states isc status takes, the sides isc focus takes, the devices and machines your hub has (for isc hub device rm, isc hub machine rm, ban and unban), the names under [hosts], and the commands isc do runs. A project whose name a shell wouldn't read as one plain word, or that another project shares, is offered by its number. A device or machine named that way isn't offered.

--host, --socket and --rights are offered only on commands that take them: isc upgrade and isc host take none of them, and isc daemon takes only --socket.

Asking never starts the daemon. It asks the daemon at the default socket or $INSENSICAL_SOCKET, not one given with --socket on the line you're typing.