Where smith keeps its files

The shell data dir, the core data dir, the desk dir, the work home, run copies and check caches on Linux and Windows, and what is safe to delete.

Smith has two data dirs, not one: the desktop shell's and the core's. Windows entries are not verified on a Windows host. "Not checked" means the source does not settle it.

01everything smith writes#

Windows cells are from code only. "Not checked" means the code does not settle it.

02shell-data#

Chosen by shellDataDir (desktop/update-logic.js). Order: $SMITH_DESK_HOME if set; else on Windows Electron's userData; else on Linux $XDG_DATA_HOME/smith, falling back to ~/.local/share/smith.

It holds logs/app.log (restarted past 5 MB, the previous one kept as app.log.1; desktop/main.js), projects.json, desktop.json, handoff.json and crashes/. Safe to delete: not checked.

03data#

A different folder from the shell's. deskDataDir (internal/cli/desk.go) uses desk.json data_dir if set, else config.Dir() (internal/config/config.go).

It holds the built-in tracker store tickets/tickets.db (ticketsDBPath, internal/cli/desk_backup.go) and the search model models/bge-small-en-v1.5 (DefaultLocalModelDir, internal/tickets/embed/local.go). Safe to delete: not checked. Deleting tickets.db removes the built-in tracker's tickets.

04projects#

<project>/.smith/desk (internal/cli/desk.go), the same on both systems. It holds:

• desk.json.
• projects/<tracker>/<project id>.json, the local halves (internal/desk/projects.go).
• conversations/.
• patch/, the default patch folder. --patch-root or desk.json patch_root overrides it.

Templates live in <project>/.smith, not in the desk dir. Safe to delete: not checked.

desk.json search

search is a block in desk.json that picks what embeds text for ticket search. It is global only (no per-project value) and live-reloaded.

• runs_on takes built_in (the default) or ollama.
• ollama_url defaults to http://localhost:11434.
• ollama_model defaults to bge-m3.

A failed ollama probe leaves search keyword only. It never falls back to the built-in model by itself.

05tracker record#

The record is not a file in the desk dir. For the built-in tracker it sits in <core data dir>/tickets/tickets.db. For a remote tracker it lives on that tracker's host (internal/cli/desk.go).

06work home and work clones#

The work home is fixed at <user home>/smith-work (NewProjects, internal/cli/desk.go); no setting was found. A project's workspace defaults to <work home>/<name> (internal/desk/projects.go). Safe to delete: not checked.

07runs#

RunWorktreesDir (internal/service/run_worktree.go) gives <checkout>.runs. Each run gets a git worktree at <checkout>.runs/<first 12 characters of the launch id> (runWorktree). Only a git checkout of its own with a commit gets one (MakesRunWorktrees); any other folder is built in place, one run at a time.

Smith removes a run's worktree and branch by itself (worktreeLeftovers, sweepWorktrees, internal/desk/leftovers.go) when the core starts, after a sync, and after a landed run ends. It does so only when the run is not live, the tree is clean (untracked files count; a changed file byte-identical to main counts as clean), and either the branch is already in main, every commit on it is in main under another hash, or its ticket is done. It uses git worktree remove, then git branch -d. It adds --force to the tree only after checking again that every changed file is byte-identical to main, and -D to the branch only when every commit is in main under another hash or the ticket is done; a branch that is just an ancestor of main keeps -d. If git still refuses, the tree stays and isn't counted. It posts one line to the project's manager chat only when something was removed. It keeps, and never touches: live runs; a failed or stopped run's tree, which is what continue reuses; dirty trees; unlanded commits on a ticket that isn't done; and the asset-* mounts, trees no run record names, and any tree modified in the last hour. Removing a tree by hand is safe only when it is clean and its branch is in main: from the clone, run git worktree remove <path> then git branch -d <branch>. Never rm -rf alone; if you did, git worktree prune clears the dead entry.

08check caches#

<os.UserCacheDir>/smith/checks/{gocache,golangci-lint} (internal/service/patch_checks.go).

They persist across runs. They are caches, created again as needed (MkdirAll), so safe to delete. The check HOME is a fresh temp dir removed after the check.

09logs#

<shell data dir>/logs/app.log holds the shell's events and the core's output. The core's stderr reaches it as [core] … lines (desktop/main.js keep). It is restarted past 5 MB, the old one kept as app.log.1.

A failed go shows in the card thread and in app.log as smith: couldn't start <entry>: <error>. Search app.log for couldn't start. For a saved-context folder error, see retained context and troubleshooting.

10report outbox#

A problem report is written to <core data dir>/outbox/ before anything is posted: <stamp>-<rand>-<kind>.multipart is the body and <stamp>-<rand>-<kind>.json beside it says how the sends went. The sidecar holds kind, content_type, created_at, attempts, next_at, last_status (0 means the address gave no answer) and last_error. A report the intake refused for good (400 or 413) moves to outbox/failed/. Both are in the core data dir, not the shell data dir, and backups don't copy them.

A report that is waiting is tried again once at launch and then every hour. A pressed send posts its new report at once and ignores the backlog's next_at. A retry pass posts the due reports oldest first, stops at the first answer that isn't a 202 and posts at most 15, half of the intake's 30 reports an hour per install. After a failed try the next one waits:

• 429: the intake's Retry-After, at most 1 hour.
• anything else, or no answer: 1 minute doubled for each earlier attempt, at most 1 hour.
• 401: the key is kept; a second 401 ten minutes or more later forgets it, and the reports stay in the outbox until the install is linked again.

Every send that isn't a 202 writes a line to app.log (search smith report:), and a retry pass that had something due writes one more:

• smith report: send <stem> (<kind>) → <status or no answer>: <words>; next try <time>. A 401 ends ; key refused and a 400 or 413 ends ; moved to outbox/failed.
• smith report: retry pass: <n> due, <sent> sent, stopped at <stem> (<status>), or stopped at the cap of 15, or nothing after sent when every due report went. A pass with nothing due writes nothing.

The key is never in app.log or on a card. The card for a report that waits says why: