Repository navigation
v0.1.35-m7
Pre-releasePre-release. Linux amd64 is tested; Windows amd64 is tested in CI. The Linux arm64 and macOS binaries are built but not tested.
Update from any earlier v0.1 with backsight update apply: it takes a verified backup first and rolls back if a step fails. Then restart Claude Code and a running dashboard (Ctrl+C, then backsight dashboard). New install: see below.
- The server is unchanged (Hindsight 1.2.0): no server upgrade.
- The instruction set is unchanged (v16). The bank template, the plugin and the metrics index are unchanged.
config.tomlmay gain a[terminal]section, written by you only: an older backsight refuses it, so remove it before installing an older version.
What changed
backsight looked bleak at a terminal. It now has color and a splash there, and only there: what programs and Claude read is byte for byte what it was (#257).
A splash (#266): at an interactive terminal at least 72 columns wide, a command starts with the backsight logo beside a short panel about backsight itself, never about the project:
- the version and Hindsight's;
- the server's last answer, or since when it is silent;
- the setup (
host · docker,client of <host>,not set up yet · backsight setup); - the sessions and notes waiting to be sent;
- the last daily checks (
50 ok · 2 warn · 0 fail (last run 3h ago)); - a newer release, with the command that installs it.
It reads a few local files under a 50 ms budget, writes and creates nothing, and leaves out a line it cannot read in time. --no-splash or BACKSIGHT_SPLASH=0 hides it. [terminal] logo = "braille" draws a finer logo; a console that is not UTF-8 gets an ASCII one.
doctor,version,update check,update applyandstatswith its views are colored by meaning: green for ok, amber for a warning, red for a failure, cyan for a command to run, dim for times and ids. Every status keeps its word.- So are the step lines of
setup,connect,restore,update apply,server installandserver runtime, the plans and results ofsetup,connectanduninstall, and setup's questions. - On stderr,
backsight:before an error is red, andretain backfillandrestorecolor their progress. - Passphrase and secret prompts, and the commands whose output is a value to capture (
secret,server token,backup identity show,jobsand the hooks), are never colored.
For people only: color and the splash appear only when the stream is a terminal itself.
- A pipe, a redirect,
--json, a scheduled job (its Windows log too) and Claude Code's shell (CLAUDECODE) get plain text, unchanged. --color auto|always|never,BACKSIGHT_COLORandNO_COLORset it.FORCE_COLORandCLICOLOR_FORCEare ignored, so a shell profile cannot send color into Claude's commands.- On Windows the console's color mode is turned on for the command and put back after it, Ctrl-C included.
- Commands lists the classes; configuration lists the variables.
Install
On Linux:
curl -fsSL https://raw.githubusercontent.com/Barben360/backsight/main/scripts/install.sh | sh
backsight setupOn Windows x86_64, in PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Barben360/backsight/main/scripts/install.ps1 | iex"
backsight setupRequirements as for v0.1.22-m7. On Windows, Claude Code must find Git Bash: if Git for Windows is portable or installed in a place of your own, set CLAUDE_CODE_GIT_BASH_PATH to its bin\bash.exe (doctor's git-bash check gives the command).
Known limits
- Dashboard:
- Version switches and settings changes are marked on a day's page and on Releases only, not on every chart.
- The custom window goes back 13 months, as far as this PC keeps its history.
- Time to recall needs a few days of history, and 20 sessions before it shows times; it is judged (ok or watch) only from 100 sessions, and reads "too few" until then.
- A window, custom or typed in a URL, can span at most 400 days, between 2000 and 2099.
- Bank growth still counts a UTC day that straddles the window's start as a whole day.
- Memory yield needs four weeks: a week counts 28 days after it ends.
- On a window over 200 days, charts show no per-day values on hover, and "Show as a table" lists the latest 120 days.
- A week that is not complete shows no count of new memories.
- The project filter takes a typed name, not a pick from a list (the Projects page lists the names). The Projects list cannot be sorted. The context card names the session budget rather than showing its value.
- GPU reranker:
- It needs the Docker runtime, on the server's PC.
- Tested on one NVIDIA RTX A2000 (Linux) and one AMD Radeon 890M (Linux). Intel GPUs, macOS and Windows are not tested.
- Owner checks:
- The short-lived native units created during install, start and restore are not checked.
- On Windows, when neither
schtasksnor the task's file can be read, the task is driven as before.
retain resend-failed: it does not cover notes and sub-agent reports sent while extraction failed (the queue drops them once sent). A transcript rewritten or moved after its worktree was deleted loses the project recorded for those turns, so the session is then filed by today's rules.- The metrics index: an index already in write-ahead mode whose folder no longer allows it fails its writes until the state directory is back on a local disk.
stats daysreads a year of prompts with no index for it (about 0.1 s locally). - Import: a file the server keeps rejecting holds that folder's next files until it passes. The last tick before a cap can overshoot it by what was already in flight. A file deleted from the folder stays in the memory until
import purge. - Windows:
- WSL is not tested, and Windows on Arm has no binary.
- The native runtime is the only runtime there (
server runtime switchis refused). It serves this PC only, has no web UI, and starts with your logon, not at boot. backsight server statuskeeps showing the server's last refusal while it is stopped, until a start passes the check.- backsight's
.exefiles are not code-signed: SmartScreen or Smart App Control may warn about them. The install script checks the release signature before it runs anything.
- The terminal's look:
- On Windows, the splash draws the ASCII logo unless the console's code page is UTF-8 (65001;
chcp 65001): many consoles default to another one. - The views' tables (
stats <view>) and section headings are not colored yet, norsetup --undo's list. - The braille logo (
terminal.logo = "braille") needs a font with braille characters; the logo's dot can take two columns in an East Asian terminal.
- On Windows, the splash draws the ASCII logo unless the console's code page is UTF-8 (65001;
- A new install reads "learning" for its first week, and some numbers read "too few" until enough prompts and turns accumulate.
- Extraction cost needs a price: the built-in table's, or one set under
[llm]in the config file for another model (doctor'spricecheck says when none is known). The server reports token counts for all PCs together. - On native, PostgreSQL is 18.1 with pgvector 0.8.5, where the Docker image runs 18.6 with 0.8.7;
backup verifyruns in the runtime that will restore. - On Windows, the commands the dashboard and
stats --jsonoffer to copy are quoted for PowerShell; run through Git Bash, a name holding an apostrophe comes out without it. - Claude cannot run
/reload-plugins: after an update from the session, you type it. - A LAN address carries the API key in clear; a tailnet address encrypts it.
- The shared part of a session continued on two PCs may be stored twice.
- Several PCs: a PC sends its figures once a UTC day, up to the day before, so another PC's today is not in all PCs until the next day; the others' figures are fetched every 6 hours. A PC counts in a window by the noon (UTC) of each of its days. The other PCs send no project, session or memory: Projects, Sessions and Memories stay this PC's, and a project filter does not narrow the others (
other PCs: not filtered). The verdict stays this PC's. Speed across PCs is a range from time buckets, never an exact time, and the PCs' figures are trusted as sent: nothing signs them. - The feedback database:
- The ledger lookup's speed is measured on Linux only: Windows has no bench yet.
- After a rollback to an older version and an update again, the counts that version added catch up at the first tick.
- In a rare race during an update or a rollback, an older version can leave one tick's shows out of its
ledger.json; this version's next tick counts them.
Report problems at https://github.com/Barben360/backsight/issues, after reading the diagnostic backsight report prints, or ask Claude /backsight:doctor. Report vulnerabilities privately, as https://github.com/Barben360/backsight/blob/main/SECURITY.md describes.