Sessions and projects.

A session is a conversation with Nilux in a project folder; a chat is one without a folder. The sidebar lists them: projects and their sessions while Agent is on, your chats while Chat is on. Sessions you started in the terminal are there too.

Projects

The projects you worked in with Nilux, in the app or in the terminal, and the folders you open, are listed under Projects. Under each are its sessions, pinned ones first, then the most recent: five of them, with View all for the rest. Sessions that are running always show. When the app starts, only the project you worked in last is unfolded. Click a project's name to fold or unfold it.

• + beside Projects: Open a folder… (Command+O) adds a project, New group makes a group to sort projects into.
• + on a project starts a new session there.
• A project's menu (…): Show in Finder, Move to group, Project settings… and Remove from list. Removing only takes it off the list until something new happens in it; nothing on disk changes.
• A group's menu: Rename group, Add a folder to this group… and Remove group; its projects stay, in no group.

Sessions

A session's row shows its name and when it was last used, or what it is doing while it runs:

• Starting.
• Working (Answering in a chat).
• Waiting: it waits for you, to approve something or to answer a question.
• Done: it finished while you were looking elsewhere.
• Failed: it stopped; Restart in the row's menu starts it again.
• Asleep: see Running sessions and sleep below.

The row's menu (…) has:

• Open side by side (in Agent): the session in a pane beside the one you are in.
• Pin (P): a pinned session stays at the top of its list, and is never deleted for its age.
• Rename (R): Enter saves, Esc keeps the old name. An empty name takes your name off: the session shows the name Nilux gave it again, or its first message.
• Rewind…: go back to an earlier message; see Working in a conversation.
• Delete (D): after you confirm, the session is deleted from ~/.nilux, so the terminal will not find it either. This cannot be undone.

The letter keys work while the menu is open. To delete several sessions at once, press Select several (the box beside Projects or Chats), tick them and press Delete.

Once a reply has something to name, Nilux names the session in a few words (Name sessions automatically in Settings). Sessions you have not used for 30 days are deleted; pinned sessions are kept.

Search

Search at the top of the sidebar (Command+K) finds sessions and chats by their names and by what was said in them, in every project, sessions from the terminal included. Narrow it to All, the project you are in, All projects or Chats. ↑ and ↓ choose, Enter opens, Command+Enter opens the session side by side.

Several sessions at once

Sessions go on working while you look at another one, and the sidebar shows what each is doing. In Agent you can also have several side by side:

• Command+\ opens a pane beside the one you are in, Command+Shift+\ one below it.
• Open side by side in a session's menu, or drag a session from the sidebar onto the panes and let go where it should open: in a pane, or beside it on any side.
• Command+1 to Command+9 move to a pane.
• With more than one pane, each pane's bar has buttons to split it and to close it. Closing a pane leaves its session running.

The window holds as many panes as fit, up to 12, three to a column. A chat is shown one at a time, across the whole window.

Back and Forward in the title bar (Option+←, Option+→) go through the sessions the pane you are in has shown.

Running sessions and sleep

Each running session is its own process on your Mac. A session you are not looking at goes to sleep once its cache has expired, so sleeping costs nothing extra: it keeps its history, shows Asleep in the sidebar, and wakes when you open it. Sessions on screen never sleep.

In Settings → Sessions, Sleep idle sessions can be set to Never, and Running at once sets how many sessions may run (6 unless you change it). Past that number, sessions whose cache has expired sleep first, then those idle longest.

Quitting Nilux, or closing its window, stops what the sessions are doing; if any is still working, Nilux asks first. The next time you open it, the sessions you had open come back where they were, asleep until you look at them.

Chats

In Chat, New chat starts a conversation without a project. Web search and reading pages are always on; files on your Mac and commands are not. Attach pictures, PDFs and text files to a message instead. A chat keeps no memory: memory belongs to projects.

Temporary, on the chat's starting screen, makes the next chat temporary: it is not saved, and it is deleted when you close it (Close session in its row's menu). While it is open, it is marked Temporary.

While you are in Chat, a session in Agent that waits for you is announced at the top of the sidebar: Agent waiting for approval. Click it to go there.

Project settings

Project settings… in a project's menu holds what belongs to that project rather than to the app:

• Group: where the project sits in the sidebar.
• Isolated project: for work that must not mix with anything else, such as a client's project. Nilux then cannot search or read conversations outside it, keeps no project memory for it, and loads only the project's own nilux.md, skills and agents, none of yours.
• Project memory and Memory folder: whether Nilux keeps notes for this project, and where. See Project memory.
• Imports from outside the project: lets the project's nilux.md files and rules load files from outside it with @. A session takes it up when it starts.
• Folders outside the project: Add folder… lets Nilux work in another folder as in the project. It reads and changes files there without asking, and Auto mode treats the folder like the project.

Isolation and the folders are saved in the project's own .nilux folder, so Nilux in the terminal honours them too. A session that is already open keeps its isolation until it starts again; added folders apply at once.

Trusting a folder

The first time you open a folder, or a session starts in one, Nilux asks Trust this folder?: it can read, change and run files there. If the folder's own settings already allow some actions, or other folders, you see them before you answer. Choose Yes, trust this folder or No, don't open. Trust given to your home folder, to a folder that contains it, or to a whole disk lasts only until you quit the app.

Settings → Trusted folders lists the folders you trust, with Remove to take one off.