Northern Commander

State files

What the application remembers by itself, beside your own files in ~/.northern-commander/. You never need to open these; this page says what is kept, when, and what you can do with it.

File Holds Written Schema
session.json Where you left off: each pane, its tabs and the window As it changes session
history.json Where each pane has been, the commands you ran, the files you agreed to run, and where you left each file As it changes history
recents.json What you typed into each field that remembers, and how the last archive was made As you type an entry, and as you make an archive recents
consent.json Your answers about reports, updates and the license As you answer consent
reports.json What reports are sent under As reports are sent reports
greeting.json What the screens shown at start have said: Full Disk Access offered, What’s new, the overdue reminder As they are shown greeting
tools.json Where the programs features can use, such as jq, were found, and Homebrew As they are looked for tools
backups.json What the last backup left out As you take a backup backups
restore.json A restore waiting for the next start As you ask for one restore
logs/ A log of each run As the application runs —
crash-reports/ Reports of crashes, errors, freezes and stalls waiting for your answer As one happens —
shell-integration/ Scripts the built-in terminal’s shells read As a shell starts —

As the application quits, whatever is not written yet is written — also when it is told to stop by the system, with nobody to answer a question.

session.json

Where you left off, so the next start opens the same way:

  • each pane’s folder, its order and whether that is reversed, its view, and each view’s options — the columns the full view hides and those it shows that are off until chosen, how many columns the brief view runs across, how large the thumbnail view’s tiles are, which size the usage view sorts by;
  • what each pane’s side was showing: its own listing, or the info pane or the preview pane or the folder tree in its place;
  • each pane’s other tabs, in order, each with its folder, order, view, cursor and history. They open where they were left, whatever a pane’s setting says;
  • which pane was active;
  • the window’s place and size, and whether it was maximized. Full screen and minimized are not kept: a maximized window keeps the size it goes back to.

Written as any of it changes; the window once it has stood still for half a second, so a drag is one write. A pane showing search results is kept at the folder it was in before, since the results cannot be made again.

As the application starts, each pane opens at a folder given at launch; else at its setting, Left pane starts in or Right pane starts in; and by default where this file says. A folder that has gone opens at home. The window goes on the display holding most of where it was, no larger than that display, or centered on the main one.

An example
{
  "version": 1,
  "left": {
    "location": "/Users/you/Projects", "provider": "filesystem", "order": "size", "reversed": true, "view": "brief",
    "views": { "full": { "hidden": { "filesystem": ["time"] }, "shown": { "filesystem": ["ondisk"] } }, "brief": { "columns": 4 }, "thumbnails": { "size": "small" }, "usage": { "by": "ondisk" } }
  },
  "right": {
    "location": "/", "provider": "volumes", "order": "name", "reversed": false, "view": "full",
    "views": { "full": { "hidden": {}, "shown": {} }, "brief": { "columns": 3 }, "thumbnails": { "size": "small" }, "usage": { "by": "length" } }
  },
  "active": "left",
  "window": { "x": 120, "y": 80, "width": 1100, "height": 700, "maximized": false }
}

x and y are the screen’s own pixels; width and height are points.

history.json

Four lists, each written as it changes:

panes
Where each pane has been — the list ⌥⌘[ shows. Most recent first, each place once, at most 50 a pane, each with the row the cursor was left on. A folder the pane only walked through is not in it, and a set of search results is offered for the run and never kept.
commands
The commands the shell in the built-in terminal ran, each with the folder it ran in, most recent first — the list ⌘F8 shows — and the ones you pinned. At most Commands remembered are kept; 0 keeps none. A lower limit applies to what is already kept at the next start.
ran
The files you agreed to run, each with its size and the time it was last written, most recent first. One whose size or time has changed since asks again.
places
Where you left each file in the viewer and the editor, most recent first, at most 500: the line, the cursor, a tree’s node, a table’s cell and column widths, a PDF’s page. A file left at its top has no row.
An example
{
  "version": 1,
  "panes": {
    "left": [{ "location": "/Users/you/Projects", "cursor": "/Users/you/Projects/notes.md" }],
    "right": [{ "location": "/", "provider": "volumes" }]
  },
  "commands": {
    "pinned": ["git commit -m \""],
    "recent": [{ "command": "make test", "directory": "/Users/you/Projects" }]
  },
  "ran": [{ "path": "/Users/you/bin/deploy.sh", "size": 120, "modified": "2026-10-18T09:15:00.0000000Z" }],
  "places": [{ "path": "/Users/you/Projects/notes.md", "line": 120, "cursor": { "line": 124, "column": 8 } }]
}

A place a cd in the terminal took the pane to is marked "terminal": true.

recents.json

What you typed into each field that remembers — a pattern, a folder to go to, a search — under the field’s name, most recent first, five a field. Two fields asking the same question share a list. Each entry is written the moment it is remembered, so a run that ends badly still keeps it.

Beside them, under choices, the format and level the last archive was made with, which the next one is offered. A format this version does not make is read as zip, at normal.

An example
{
  "version": 1,
  "fields": {
    "find-name": ["*.cs", "*.md"],
    "go-to-folder": ["/usr/local", "/tmp"]
  },
  "choices": {
    "create-archive": { "format": "tar.gz", "level": "smallest" }
  }
}

consent.json

Your answer to each question about something that leaves this Mac — crash-reports, usage-reports, updates — and to the licence, each with the version it was given in. Written the moment you answer: on the welcome, on the Privacy page of the settings, or in the question put about a crash. Turning on Check for new versions records a yes to updates as well.

  • An answer is yes or no; for crash reports, also ask or never. Only yes sends anything by itself.
  • A question you have not answered is absent, which is not the same as no: nothing is sent either way, but only an unanswered question is put again.
  • A question is put again when a new version changes what it means — that one alone.

It is not part of a backup: restoring it would answer for you.

reports.json

Kept only by a copy that sends reports, once you have agreed to one kind or chosen to be asked about crashes. What reports send is on Support.

  • The random identifier each kind of report is sent under — one for crash reports, one for usage — made the first time that kind is sent. They are kept apart so the two cannot be joined, and come from nothing about you or your Mac.
  • How far the system’s own crash reports have been read, and when the application last reported a crash itself, so none is sent twice.
  • When each error the application caught was last reported, and how many times it has happened since, so the same one is reported at most once a day. An error is named by a code worked out from where in the program it happened, and forgotten a week after its last report.
  • How many usage events were lost since the last report that got through.

greeting.json

What the screens shown at start have already said, so each says it no more often than it means to.

diskAccessOffered
How many times the screen offering the way to Full Disk Access has been shown while access was off. After two, it is not shown by itself again; the Privacy page of the settings still offers it.
whatsNewShown
The newest version whose What’s new has been shown, or that started with nothing to show.
oldVersionDismissed
The day Update overdue was last put aside. It comes back two weeks after that, while the version is still old.
updateChannelMoved
The version that set Versions to be offered to stable, which happens once, so a later choice of beta stands.

tools.json

Where the programs on the Tools page of the settings were last found. They are looked for again as the application starts, so this only stands until then.

looked
When they were last looked for.
homebrew
Where Homebrew’s brew is; absent where it was not found.
tools
Each program found, by name, with its path and, where Homebrew installed it, its version. A program that was not found is absent.

backups.json and restore.json

For Backups, which has the whole story.

backups.json
The parts the last backup you took was told to leave out, so the next one — and every scheduled one — leaves them out too. A part added by a newer version is taken.
restore.json
A restore you agreed to. The application starts again, and the new run carries it out before it reads anything the restore replaces. The request stays until the restore has finished, so one that is stopped partway is finished by the next start. That start empties the request before it tries, so a backup that stops the application costs two starts, not every start.

The folders

logs/
A folder for each run, named by when it started, such as 20260919-093012-4521, holding log.jsonl — one record a line — and small files that say whether the run ended properly. While the application is not responding, and crash reports are sent or asked about, hang.json there says what it was doing; it is reported and removed when it answers again, or at the next start. stall.json says the same of something you were left waiting for, and goes once that arrives or is reported. How much goes in is Log detail; each run is kept for Keep logs for, and the oldest go sooner once all of them pass 500 MB. While diagnostic detail is on, diagnostic-since beside them says when it was turned on, so a restart doesn’t start its clock again. Reading and sending them: Support.
crash-reports/
Only while crash reports are set to ask each time: each crash, each error the application caught, each time it stopped responding, and each thing it left you waiting for, exactly as it would be sent, waiting for your answer at the next start. At most five of each, none older than a week, and each is removed once it is sent or declined.
shell-integration/
The scripts that let a shell in the built-in terminal say which folder it is in and what it ran — for zsh, bash and fish. Written as a shell starts, unless you turned off Shell reports where it is; readable by you alone; and put back as they ship whenever they differ, so a change to them does not last. See the terminal.
backups/
Your backups, unless Backups folder names somewhere else.

What you can do with them

Delete one to make the application forget what it held. Quit first: a running copy holds these in memory, and writes them again.

Delete And the next start
session.json Opens each pane at home with one tab, unless its setting names a folder
history.json Has no pane history and no command history, asks again before running each file set to Run, and opens every file at its top
recents.json Has fields that remember nothing, and offers zip at normal for a new archive
consent.json Asks the welcome’s questions again; nothing is sent until you answer
reports.json Makes new identifiers the next time a report is sent
greeting.json Offers Full Disk Access again, while it is off; shows What’s new for every update since you agreed to the license; asks about an old version again; sets Versions to be offered to stable once more
tools.json Loses nothing: the programs are looked for again
backups.json Offers every part ticked for the next backup
restore.json Carries out no restore
logs/, crash-reports/, shell-integration/ Loses nothing it needs; crash reports waiting there are not sent

Edit one only if you must: they are not meant for it, and the application writes them as things change. Each schema, linked in the table above, says what every key means.

  • A file that is missing, unreadable, not JSON or not an object reads as empty, the log says why, and the next write replaces it. The application starts all the same. A part that is not the shape expected — panes that is not an object, say — is left out and written back untouched.
  • Every file starts with version, the shape it is written in. A version of the application that finds a newer shape reads what it can and writes the rest back as it was, and never lowers the number — so going back to an older version loses nothing a newer one wrote.
  • Two copies running at once each write only what they changed, onto what the file says at that moment: each keeps the other’s commands and entries, and for where a pane has been or where it was left, the last to change it wins.
  • Each is written beside itself and moved into place, so a write cut short leaves the file that was there.

Not kept

  • The journal of what was changed on the disk lasts for the run alone.
  • Search results in a pane are kept only as the search that made them, if you save it.