Projects and the sidebar
Projects group your work, and the sidebar lets you see all of it and jump to any part.
Projects
A project is a name, an optional root directory, and tabs. It stays until you close it, even with nothing running, and comes back after the daemon restarts.
Closing a tab or a project asks first, because it kills every program in it. The window lists the panes that would close (just a count above six). Enter, "Close tab" or "Close project" closes. Escape, "Keep it" or a click outside doesn't. A project with nothing running closes without asking. Closing a pane doesn't ask, and neither do isc tab close or isc project close.
Opening one. Press Ctrl+Shift+N, or click the project's name in the top bar. You're asked for:
- Name, optional. With a directory and no name, the project is named after the directory. With neither, it's given a name.
- Directory, where its tabs open. It starts as the directory of the pane you're in. Type a path beginning with
/or~, or leave it empty for none. For a project on this computer, Choose beside it opens your system's folder picker.
Under the directory, the folders in the directory typed so far are listed, six at a time with the rest a scroll away, those that start with what you've typed after the last / (hidden ones once you type a dot). Nothing is marked while you type. Down and Up mark one; Right, or a click, goes into it, and the list shows its folders; Left, at the end of a path that ends in /, goes up one. Enter on a marked folder takes it as the directory; Escape takes the mark away. A line under the list says which of these keys work at the moment.
If the path doesn't exist but could, the button reads "Make the directory". Enter asks once more ("Make it and create"), and Enter again makes it, and any missing ones above it, on the machine the project is for (permissions 755 less your umask), then opens the project. If it can't be made, the card says why and nothing is made.
Tab and Shift+Tab go round the card's controls: the machine, the name, the directory, Choose, Cancel and Create. They never leave the card. Enter with no folder marked, or "Create", makes the project and opens a shell in it. Escape, "Cancel" or a click outside makes nothing.
Ctrl+Shift+S (⇧⌘S on a Mac) puts the keyboard in the sidebar's field, showing the sidebar if hidden (with tabs = "top" it opens the palette instead). That field only narrows the tree: Enter on an existing project's name goes there, and nothing typed makes a project.
From the command line:
isc project new [DIR] [--name NAME] [--make]
isc run --new-projectA DIR that isn't there is refused, and nothing opens. --make creates it first, with the ones above it, on the machine the command is for. On this machine, . or a name like app means from the directory you're in. On another machine, give it from / or ~. To open a project with all its tabs and panes at once, see A project in a file.
| New | Opens in |
|---|---|
| Tab | The project's root. With no root, the directory of the project's front pane, and your home directory only if there's none. |
| Split | The directory of the pane it splits |
| Floating pane | The focused pane's directory |
A project's name doesn't follow its panes. Tab and pane rows show where they really are.
Renaming. Choose "Name and icon" in the project's menu, run isc project rename OLD NEW, or choose "Rename this project" in the palette. Enter keeps the name, Escape leaves the old one, and an empty name isn't allowed. If the row isn't on screen, the Name and icon card asks.
A project's icon. Every project has a tile beside its name: by default the first letter of the name on a colour that comes from the name. To change it, press the tile on the project's sidebar row, or choose "Name and icon" in its menu. That card holds the name and the icon together. Each icon you pick shows at once. "Save" (Enter) keeps the name and the icon; "Cancel" (Escape), or a click outside the card, puts both back as they were. "Save" can't be pressed while the name is empty.
- Icon: type to find a mark, such as
git,rustordocker. The first is the letter. Next are insensical's own tiles:folder,code,web,database,docs,mobile,package,rocket,lab,server,design,chartandshield. After them are the marks programs are shown by, each on its maker's card, just as a program's tile is. - Colour of the letter: one of ten colours, or "From the name" for the one it had. Only the letter takes a colour. A program's mark keeps its maker's colour, and insensical's own tiles and your SVGs keep theirs, so the row is faded while one of them is picked.
- "Use an SVG" takes a
.svgfile of yours, 256 KB at most, drawn whole in a square. A copy is kept in~/.config/insensical/icons/. A drawing with an<image>in it, or a gzip-packed one, isn't taken. - "Reset" goes back to the letter and the name's colour.
From the command line, isc project icon NAME --mark rust, --colour '#ff8800' for the letter, or --svg logo.svg. What you leave out is cleared, so isc project icon NAME alone resets it. The file is read where you run the command, so isc --host build project icon api --svg logo.svg takes a logo.svg from this machine.
| To | Do |
|---|---|
| Put projects in order | Drag a project's row onto another's, or isc project move NAME INDEX (counted from 0) |
| Close | Press the cross on its row (asks first), or isc project close NAME |
| Move between projects | Ctrl+Alt+PageDown or Ctrl+Alt+PageUp, click a row, or isc project select NAME |
On the command line, a project is its name, or its number as isc ls prints it (4 or project:4). Two projects can share a name; the name then means the first listed, and the number tells them apart. A number always means that project.
Putting a project to sleep
A project you aren't working on still holds what its programs hold: a few megabytes for a shell, several hundred for an agent. Putting it to sleep ends its programs and keeps everything else.
- Tabs, splits, floating and minimized panes stay, and so does what each pane showed. In the sidebar the heading says
asleepand its rows are dimmed. - Waking it puts a shell in each pane, in its directory, under what it showed. What ran there is typed at the prompt for you to run again with Enter: an agent's own resume command, once, if it was still working when the project went to sleep, otherwise the command the pane was started with. This is also what happens to every pane when the daemon restarts (section 17).
- A project that's asleep when the daemon stops, or moves to a new version, is still asleep afterwards, with everything it kept.
To sleep one, hover its heading and press the sleep mark; or choose "Put this project to sleep, or wake it" in the palette (command sleep-project, no default key); or run isc project sleep NAME. The window shows what would end and asks first. To wake it, select it and press Enter or Wake it, or use the same mark, command or isc project wake NAME.
- insensical never puts a project to sleep by itself.
- You can't start a pane in a sleeping project. Wake it first.
- Closing a sleeping project removes it and what was kept of its panes.
- With
keep-scrollback = falsea waking project has its panes and directories but not what they showed.
The sidebar
The sidebar is a tree of project, tab and pane. It shows while tabs = "sidebar", and Ctrl+Shift+B hides and shows it. Drag its right edge to change its width, from 190 to 520 pixels (at least 240 are left for the panes).
| Row | Shows |
|---|---|
| Project | Its icon and the name. On the right: memory its programs hold, and its pane count. Folded, instead: how many of its panes need you, with the most urgent mark. |
| Tab | The tab's deck of tiles, then its name, or what its focused pane is called. Folded, on the right: its most urgent pane's mark. |
| Pane | The program's icon, then what the pane is called. On the right: a mark if floating or minimized, and its state. |
What a pane is called is the same in the sidebar, on a dock chip, in the palette and in a close question:
- the name you gave it, if any;
- otherwise the title its program set, unless it's a shell;
- otherwise the program and the last part of its directory, such as
nvim · api. A shell is called by its directory alone, such asapi. The home directory is~.
- A tab with one pane and no name has no row: its pane's row stands in for it.
- A pane with something to say shows it on a second line, starting with the state in the state's colour: "wants permission", "asks a question", "needs you to sign in", "waiting", "failed" or "done". The program's own words follow. Hover for the whole text.
- A working pane shows progress and words after its name when they fit, as in "40% · Pushing image", and on their own line when they don't.
- A row says how long its pane has needed you:
nowfor the first minute, then2m,1h,3d. After ten minutes the figure turns bold in the waiting colour. - Click a row to go to it. Click a minimized pane's row to bring the pane back.
- What an agent started in another tab is listed under it, one level in. What it started in its own tab stays beside it, with the rest of that tab's panes. A tab whose panes all sit under their agents has no row of its own. Folding the agent's tab or project folds its team.
Sharing. "Share this project" in a project's menu shares the project with a guest, or lists who has it: see Sharing one project or one terminal. A shared project always shows an eye, or a keyboard if a guest can type in it.
Naming. Choose "Rename" in the row's menu. Enter keeps the name, Escape leaves the old one. For a tab or pane, an empty name removes the name. Names survive a restart and appear in the tab strip, the pane's header, notifications and isc ls.
- From the command line:
isc tab rename TAB NAMEorisc rename PANE NAME. - From the palette: "Name this pane" or "Name this tab" (
name-pane,name-tab, no default keys). Where the name isn't written on screen, a "Rename pane" or "Rename tab" card asks. Its empty field shows what the pane or tab goes by without a name.
Folding. Point at a project or tab row and its icon turns into a fold arrow: click the arrow to hide what's under it, or to show it again. With the keys, Left and Right fold and unfold the row you're on. Every project starts folded, so a long list reads by name first. When a pane comes to the front, however you got there, its project unfolds, unless you folded that project yourself: what you fold stays folded. The next window opens with projects and tabs folded as you left them. While the filter has text, matches show even inside something folded.
The pane in front sits on a raised, outlined row. Its pane row carries it when you can see it; if its tab is folded, the tab row does, and if its project is folded, the project row does. The project and tab above that row have bold names, and the tree lines that lead to it are drawn stronger than the rest.
Filtering. Type in "Find a project or pane" (Ctrl+Shift+S) to narrow the tree to projects, tabs and panes whose name, title, program or directory contains what you typed. Case doesn't matter. When nothing matches, "Clear the search" empties the field.
What is listed. In Settings > Interface > Layout, "Tree view" lists what each project holds, joined by tree lines. Under it, Tabs and Panes choose the levels: both (the default), tabs only, or panes only. One of them always stays on. In a file that is sidebar = ["tabs", "panes"]; an empty sidebar = [] is reported as a problem and both are used. With Tree view off (sidebar-tree = false), each project lists its tabs flat beneath it, with no tree lines and no pane rows, and Tabs and Panes keep their values until you turn it back on. Folding a project still works.
Showing only activity. Press Activity at the head of the sidebar (All goes back), or choose "Show only activity in the sidebar, or everything" in the palette (activity, Ctrl+Shift+Y), to list only panes that are agents or have something to say. Shells, editors and monitors go. Press All and everything is back. The window remembers your choice. With nothing to list it says "Nothing is working or waiting.", with "Show everything".
Each row shows the pane's name, how long it has been as it is, and under the name its state and what its program says, as wants permission · Allow the edit?. An agent another agent started says whose it is, as waiting · from Claude, and one that started others counts them, as working · 3 started. Press a row to go to that pane. In each project, panes that need you come first, then those at work, then finished, then agents at rest.
- A long command at a shell that marks its commands (
isc shell-integrationsets bash and zsh up) gets a row with what you typed and how long it has run. - A finished or failed pane stays until you look at it. A waiting pane stays until its program says otherwise. If the program is gone and the row is stale, point at it and press the arrow "Forget what this pane's program said it was doing".
The filter and arrows work as in the full list. Folds and the sidebar setting don't apply. Set activity-idle = false to leave out agents at rest. Two commands walk the list from anywhere, round at the ends and across machines: next-activity (Ctrl+Shift+J) and previous-activity (Ctrl+Alt+/). While the sidebar shows activity, Ctrl+Shift+A goes to the next pane that needs you or has finished.
With tabs = "top" the button is in the bar and the list shows beside the panes while it's on. The interface in a terminal has the same list: see The whole interface in a terminal. So does the page isc hub serves (see "In a browser"), though there agents at rest are always listed, and there's no filter or forget arrow.
From the keyboard. Ctrl+Shift+S (⇧⌘S on a Mac, leader e) puts the keyboard in the field. Down and Up move a highlight through the rows, or the matches after you've typed. Left folds the highlighted project or tab, Right unfolds it. Enter goes to the row and gives the keyboard back to the pane; with none highlighted, it goes to the project whose name you typed. Escape leaves the field.
Drag a row to put it in order. A project dragged onto another takes its place, and a tab dragged onto another tab of the same project takes that tab's place. A one-pane tab with no name is dragged by its pane's row. Panes aren't ordered here.