sto-band

<img src="docs/banner.png" alt="braingent-sto" width="100%">

<img alt="Python" src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white"> <img alt="React" src="https://img.shields.io/badge/React-61DAFB?style=flat-square&logo=react&logoColor=black"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white"> <img alt="MCP" src="https://img.shields.io/badge/MCP-E38742?style=flat-square&logo=anthropic&logoColor=white">

<a href="#why-it-exists"><b>Why it exists</b></a> &nbsp;•&nbsp; <a href="#features">Features</a> &nbsp;•&nbsp; <a href="#stack">Stack</a> &nbsp;•&nbsp; <a href="#structure">Structure</a> &nbsp;•&nbsp; <a href="#setup">Setup</a> &nbsp;•&nbsp; <a href="#commands">Commands</a>

braingent-sto turns a private git repository into the substrate that Claude Code is missing: your ~/.claude config, your skills and plugins, the memories your agent writes, and the transcripts of every session, all synced between machines with two keystrokes. No daemon, no API key, no third-party service — a Python stdlib backend, git, and a terminal UI.

Why it exists

Claude Code still has no native way to sync config and skills across machines, and no cloud sync for skills, settings and memory. The ecosystem answers with three separate families of tools:

Claude Code's own auto memory is part of the same gap: it writes plain markdown into ~/.claude/projects/<repo>/memory/, and the docs are explicit that those files "are not shared across machines or cloud environments".

STO is the union of the three, on one substrate. Every artifact is plain text in your own repo — memories are markdown with frontmatter, sessions are trimmed and redacted JSONL, config is the real files. You can read them, grep them, edit them by hand, and roll them back with git revert.

Features

• Built on the native memory, not beside it. No second memory store, no protocol to paste into CLAUDE.md, nothing new to teach the model: Claude Code writes its auto memory as markdown, and STO mirrors those exact files between machines.
• One repo, everything in it. sto push exports sessions, memories, ~/.claude modules and your vault, commits and pushes. sto pull applies them on the other machine — including installing missing plugins and marketplaces.
• Modular sync. Pick exactly which parts of ~/.claude travel: claude-md, settings, keybindings, skills, agents, hooks, plugins. Memories, sessions and vault always travel.
• Redaction on export. Session transcripts are trimmed to what a reader needs (prompts, tool names, errors) and scrubbed of API-key-shaped strings before they ever hit a commit.
• Resumable conversations. Every session another machine pushed can be brought here with sto resume <id> (or e on the Sessions tab, per row or per project): it is filed under the path this machine registered for the project (w), so claude --resume and /resume find it. Without a sto keep it is rebuilt from the trimmed export as text-only turns (tool outputs are gone, the conversation is not); sto keep <id> archives one transcript untrimmed and gzipped when the full tool history matters.
• Terminal UI (sto ui). Five tabs — Home, Sessions, Memory, Config, Help — built on Textual over the same engine the CLI uses: no HTTP in between, no second copy of any rule. Runs the same on Windows and Linux, and uv borrows Textual in a throwaway environment when it is not installed. The footer lists the verbs that work on the tab you are standing on, and nothing else.
• Live push/pull progress. Every step of a sync reports itself (exporting sessions → staging → committing → pushing to origin) with a spinner, instead of freezing the screen until git returns.
• Memory graph. A real graph of your memories: one node per memory, one per project, edges from [[wikilinks]]. Opens as a chrome-less window with a project/type/machine sidebar, click-to-inspect detail panel and search. Built from the same files the repo syncs, so it shows every machine and every session, not just this one.
• Config parity at a glance. The Home dashboard shows what is local-only, what is in the repo but not installed, and which plugins are missing on this machine.
• Plan usage. Live limit bars and the last days of token spend, straight from ccusage when it is installed.
• Bilingual chrome. English by default, Spanish one keystroke away — commands never change, only what they print.
• Optional web app. A React dashboard over the same backend, for when a terminal is not enough.

Structure

braingent-sto/
├── scripts/
│   ├── sessions_server.py   # engine: sessions, memory, config sync, git — stdlib only
│   ├── cli.py               # `sto` — presentation over the engine
│   ├── tui_app.py           # the TUI (Textual), over the same engine
│   ├── ui_data.py           # computed state both front-ends read
│   ├── i18n.py              # every user-facing string, en/es
│   ├── memory_graph.html    # graph window template (canvas 2D, no CDN)
│   ├── dream_extract.py     # transcript parsing and redaction
│   ├── install_sto_cli.sh   # installs `sto` on Linux/macOS: ~/.local/bin + PATH
│   ├── install_sto_cli.ps1  # the same on Windows: both PowerShell profiles
│   └── test_*.py            # the suite: no framework, no fixtures
├── app/                     # React + Vite dashboard (optional)
├── knowledge/               # what travels: sessions/, memory/, config/
├── vault/                   # curated knowledge: raw/ → wiki/ → outputs/
├── start.sh                 # launcher: backend + app + `sto`, Ctrl+C stops both
└── start.cmd                # the same on Windows, from a double click

Stack

• Backend — Python 3.11+, standard library only. No pip install, no virtualenv, no server to keep alive for the CLI: cli.py imports the engine directly.
• Sync — plain git. Your repo, your remote, your history. Conflicts are git conflicts, and you already know how to resolve those.
• TUI — Textual. Same screens on Windows and Linux; uv borrows it in a throwaway environment when it is not installed.
• Graph — one HTML file, canvas 2D, hand-rolled force layout. Opens offline in a Chromium --app window.
• App — React 19, Vite 8, Tailwind 4, react-force-graph for the 2D/3D views.

Setup

git clone https://github.com/SimonOcampo1/braingent-sto.git
cd braingent-sto
sh scripts/install_sto_cli.sh                                          # Linux / macOS
powershell -ExecutionPolicy Bypass -File scripts/install_sto_cli.ps1   # Windows

Open a new terminal and you have sto. Now make the clone yours.

Every command below runs inside the braingent-sto/ folder you just cloned. The new GitHub repo is never cloned — you only need its URL.

1. Go to github.com/new and create an empty private repo, no README. Copy its URL.
2. The clone came from the public repo, so that one becomes upstream: ``bash git remote rename origin upstream ``
3. Your new repo becomes origin — the only remote that ever sees your knowledge: ``bash git remote add origin git@github.com:<you>/<your-repo>.git ``
4. Push the code to your repo, which also sets the branch to track it: ``bash git push -u origin main ``
5. Push your knowledge — sto push exports sessions, memories and the ~/.claude modules you chose, commits and pushes them: ``bash sto push ``

Steps 4 and 5 are both in the same folder: the first publishes the engine, the second publishes what the engine collected.

On every other machine

Here you do clone — and what you clone is your private repo, not the public one.

git clone git@github.com:<you>/<your-repo>.git
cd <your-repo>
sh scripts/install_sto_cli.sh                                          # Linux / macOS
powershell -ExecutionPolicy Bypass -File scripts/install_sto_cli.ps1   # Windows
sto pull     # brings and installs what the other machines have
sto push     # uploads the memories this machine already had

That machine almost certainly has months of memories of its own already — sto push picks them up on the first run, no setup, no import step. And pulling first is safe: a pull never overwrites a local memory you have not published yet.

From then on sto push / sto pull — or p / l inside sto ui — keep every machine identical. The same instructions live in sto ui › Config, next to the two remotes they are about.

Getting updates to the OS itself

sto update merges upstream into your repo. If you skipped the rename above it adds the remote itself, pointing at where the OS is published.

sto update            # what is available
sto update --apply    # bring it down   (or `u` inside `sto ui`)

Your memories cannot be overwritten by an update, and this is structural rather than a promise: the published repo has never held a single file under knowledge/memory/, so a merge has nothing to bring there.

If you made your repo by copying files instead of cloning or forking, the two histories share no commit and git refuses to merge — the home says so. sto update --link grafts them once, keeping every local file exactly as it is; from then on sto update is an ordinary merge.

Keep the repo private. It carries your session transcripts and memories.

Want the web app too? ./start.sh (start.cmd on Windows) installs the front-end dependencies, starts the backend and Vite, and opens the dashboard. On Linux and macOS both servers log to .sto-cache/ and Ctrl+C takes them down together.

Commands

Inside Claude Code: the sto-band mod

A band above the prompt with this project's chats to push and pull, whether this machine has a path for it, and the 5 h, weekly and context windows. Two buttons on the band, and the same as commands: sync chats (/sto sync) pulls, keeps and brings the project's chats, and pushes; sync memories (/sto mem) pulls and pushes, which is what moves the memories. With auto on (/sto auto toggles it, remembered across sessions) a session pulls when it opens and syncs the memories every 30 minutes. /sto alone refreshes the band.

/plugin install sto-band --marketplace SimonOcampo1/braingent-sto

Or, to have sto update update the mod too, add your clone as the marketplace: claude plugin marketplace add <your clone>, then the same /plugin install naming it, and /reload-plugins after each update.

What STO does not do

Honesty beats a feature matrix:

• No embeddings, no semantic recall. Search is lexical. If you want vector recall inside the agent loop, run claude-mem or engram alongside it — they solve a different problem.
• No MCP server. The agent does not query STO at runtime; STO moves the files Claude Code already reads.
• No memory system of its own. Claude Code's auto memory writes the files; STO makes them travel. Nothing is distilled by a background job.
• Windows-first by history, not by design. Engine, CLI, TUI, installer and launcher all run on Windows, Linux and macOS. What Windows still has alone is the double click: start.cmd opens from the file manager, start.sh expects a terminal.
• Single user. It syncs your machines. It is not a team knowledge base.

What is next

The parking lot lives in ROADMAP.md: an MCP server so the agent can query the repo mid-session, sync that reminds you (or runs itself), a cross-platform TUI, and a few smaller things — each with the smallest sketch that would do it.

Tests

cd scripts
python test_sessions_server.py && python test_dream_extract.py && python test_cli.py && python test_ui_data.py
uv run --no-project --with textual python test_tui_app.py

No framework, no fixtures, no mocks beyond swapping a function for a lambda. The TUI suite skips itself when textual is missing, which is how the first line stays runnable on a machine that never opted into it.