A session is one conversation in the store, ~/.nodecode/history.db.
Session ids
| Id | Session |
|---|
s- and up to 8 letters or digits | A session the shell opened. Example: s-K3F9Q2ZA. |
s-GATEWAY | The boot session of the background gateway. |
Cells name their own sessions. A session nobody typed in is never stored.
List and resume
| Do | How |
|---|
| List sessions | /sessions, /agents or Ctrl+S. |
| Leave a session running | Press Left on an empty composer. The picker opens. |
| Switch | Select a row. Press Enter. |
| Rename in the picker | Press F2 on a row. |
| Fold or unfold forks | Left and Right. |
| Resume from the command line | nodecode resume SESSION-ID |
a shell
nodecode resume s-K3F9Q2ZA
The shell prints the resume line when it exits: To resume: nodecode resume SESSION-ID. resume needs a terminal.
Rename
| Command | Does |
|---|
/rename | Shows the session's name. |
/rename NAME | Names the session. One line, 64 characters at most. |
/rename default | Gives back the name the first prompt made. |
A session has no name before its first prompt.
Export
/export [path] saves the session as Markdown. It works in the shell only.
| Argument | File written |
|---|
| None | A file named after the session, in the shell's folder. |
| A folder | That file name, inside the folder. |
| A file path | That path. |
| In the file | Left out |
|---|
| Prompts, answers, plans, one line per call | Reasoning, the output of calls |
Clear
| Where | /clear or /new does |
|---|
| Shell | Opens a fresh session in the shell's folder. The old session stays in /sessions. |
| Web page, chat room, eval | Moves this session back to its start. /redo returns. |
Fork
/fork opens a new session at the current head. The shell switches to it.
| Rule | Detail |
|---|
| History | The fork reads the parent's turns up to the fork point. Nothing is copied. |
| Later parent changes | A rewind in the parent does not change the fork. |
| Folder | The fork works in the parent's folder. |
Tree
/tree shows the session as a tree of turns. Alias: /checkpoints. Esc twice within 0.5 seconds opens it too.
| Key | Action |
|---|
| Typing | Search the rows. |
| Right | Show the tool calls of a turn. |
| Left | Hide them. |
| Enter on a turn | Opens the options below. |
| Enter on a tool call | Moves the head to that turn. Restores files to that call. |
| Option | Result |
|---|
| Continue from this turn | The head moves to the turn. Its answer is kept. New turns branch from it. |
| Rewind to before this message | The head moves before the turn. The prompt returns to the composer. |
| Rewind to before this message + code changes | The same, and the files are restored. Offered when a snapshot exists. |
The head row offers the rewinds only.
Undo and redo
| Command | Does |
|---|
/undo | Rewinds the last turn. |
/redo | Returns to the branch the last rewind left. |
| Where | /undo restores |
|---|
| Shell | The conversation and the files. |
| Web page, chat room, eval | The conversation only. Refused while a turn runs. |
A rewind deletes nothing. It records a head move. The branch you left stays in /tree.
Workspace snapshots
Nodecode captures the session's folder at turn and tool boundaries. Undo restores files from these captures.
| Fact | Value |
|---|
| Repository | A bare git repository at <cwd>/.nodecode/workspace_snapshots. |
| Tool | The git command. Without git there is no capture. The turn still runs. |
| Scope | Files under the session's folder. Writes elsewhere are not captured. |
| Restore | Per file. A file changed by something else is left alone. Nodecode reports the conflict. |
| Your repository | .nodecode/ can show in git status. Nodecode does not add it to .gitignore. |
| Off switch | "workspace": { "captures": false } in the config. Applies at the next start. |
After a crash
| Fact | Detail |
|---|
| Open turns | Each interrupted turn resumes at the next boot. |
| Unanswered tool calls | Each gets the result interrupted by process restart. |
| Limit | A turn is resumed on up to 3 boots. Then it is marked failed. |
| Cost | A resumed turn calls the model again. |
| Cancel | Esc stops a resumed turn like any other. |
Ephemeral
a shell
nodecode --ephemeral
| Fact | Detail |
|---|
| Store | A new file: nodecode-ephemeral-<pid>.db in the temp folder (TMPDIR). |
| Still shared | Config, layer, cells, memory and skills are the home's. |
| Layer | The layer is the set of definitions the agent wrote and kept. New ones still land in it. |
| Channels | Channel bots do not start. |
| Refused with | serve, resume and --store. |
For a throwaway organism, a whole running Nodecode with its own home, run HOME=$(mktemp -d) nodecode.