~alter Obsidian

Your vault stays where you put it. The reading of it happens there too.

What is ~alter? · Install · Pairing a vault

What is ~alter?

You have been writing down how you think for years, and the vault holds all of it. The false starts are in there, the note you rewrote four times, the link you drew between two things nobody else would connect. Nothing else you have ever produced is a more honest account of your reasoning, and nothing outside that folder has ever read it as anything other than files.

That was the hard part and it is already finished, and what has never existed is a reader for it. The links, the tag depth, the folders you settled on and the rhythm you write at describe how you work far more precisely than anything you would put in a form.

~alter is a name you own outright, ~yourname, with a record under it drawn from work you actually did rather than claims you made about yourself. This plugin is the reader your vault has never had, and it runs on your own machine.

Your own rule holds over that record, and nothing in it is readable until you have said so, by folder class and ahead of time. Somebody confirming you exist pays nothing, somebody wanting more than that pays, and the payment lands with you. Taking a reader back out is one command and it is as local as everything else here.

The notes never move and the engine never reads what you wrote about, only the shape the writing left behind. What it works out is written back into the vault, in a file you can open, read line by line, and delete.

Go to truealter.com, find the genesis and the origin papers, and read all of
them. Then start a discussion with me in my own language, no jargon.

Ask me one question at a time and wait for my answer. Follow what I am curious
about, not the order the site is written in.

Do not only read the pages. Connect to their interface directly and call
get_started. That tells you where I am and what comes next, and we work the
rest of this from there.

If I have a ~handle I will give it to you. If I do not and I decide I want
one, set it up with me here.

What I want to understand is what ~Alter is, how it applies to me, and what it
means for everyone else. Find me somewhere in it, and not the version written
for people who work in technology. Find the life nearest mine and walk me
through it, including what it would cost me.

Try to prove them wrong. Go and find where they show their working, and if
something is unclear or does not hold up, say so.

What is ~alter Obsidian?

An Obsidian community plugin, id alter-obsidian-plugin, version 0.1.2, needing Obsidian 1.4.0 or later. It pairs a vault to your ~handle, reads the folders you have consented to, and writes what it found back into a ~Alter/ folder inside the same vault.

The reading is done by a small engine that ships inside the plugin. It is LLM-free and stdlib-only, with no network call, no model and no keyword lists, and it derives up to ten canonical signals about how you write rather than what you wrote about. Ten is the whole set, and most vaults will meet the floor on only a few of them.

It does not send your notes anywhere, and it cannot, because no code path in it reads a note body out to the wire. It never infers anything about your emotions, which is enforced by an exclusion list the engine checks before it computes rather than a filter applied afterwards. It does not replace the command line, which is where a handle is created and where a session lives.

The command line is the front door and this plugin sits behind it. alter pair obsidian is what installs it, and the plugin then reads the session that command already established, at ~/.config/alter/session.json. The local companion daemon is optional here. Pairing, consent and the opening reading all run without it, and it only carries streamed return events when it happens to be running.

Install

alter pair obsidian

The command needs three things. An ~alter session, so run alter login first, because pairing refuses to start without one rather than logging you in. Obsidian installed, with at least one vault it has registered. Obsidian 1.4.0 or later, since the plugin declares that as its minimum.

If you do not have the command line yet:

npx @truealter/cli pair obsidian

What it leaves behind is short. The plugin files, main.js, manifest.json and styles.css, land in <vault>/.obsidian/plugins/alter-obsidian-plugin/ and the plugin is marked enabled. Those files ship inside the CLI package, so nothing is downloaded for them. It also installs and enables coddingtonbear/obsidian-local-rest-api if that is not already in the vault, and that one is fetched from GitHub. Once pairing completes, a small token file is written to ~/.config/alter/obsidian/<vault-hash>/tokens.json at mode 0600.

Installing by hand

Supported, and harder. Use it on an air-gapped machine, one locked down by an IT policy, or a build you made yourself.

1. Clone this repo or download a release.
2. Copy the built main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/alter-obsidian-plugin/.
3. Enable the plugin under Settings, Community plugins.
4. Run Pair this vault to your ~handle from the command palette.

The folder name has to match the plugin id exactly or Obsidian will not load it.

Pairing a vault

1. Start the pairing from the command line

alter pair obsidian

It finds the vaults Obsidian knows about and asks which one you mean. Then it writes the plugin in, enables it, brings Obsidian to the front, and waits up to sixty seconds for the vault to report back. You can press q to stop waiting without losing the install.

2. Confirm your handle in Obsidian

The plugin reads your session, finds your handle, and shows you a modal naming it before anything is granted. Confirming sends one consent grant per folder class, obsidian-vault/journal and obsidian-vault/manual-note by default, each as its own row against your own session. There is no token to save and nothing to paste. When the grants land, ~Alter/PAIRING.md is written with the handle, a hash of the vault path, the timestamp and the four purposes recorded.

3. Open the reading it wrote

Use the ribbon icon, or the command palette, to open ~Alter/RETURN.md. The first time you open it, the plugin has already derived what it can from your vault and written the opening reading in. If nothing has met its floor yet it says so plainly and tells you what the floor is, which is at least twenty notes spanning fourteen days inside a folder you consented to. Nothing about that reading left the device.

4. Choose what gets read, in Settings

Settings, Community plugins, ~Alter. Five folder classes can be turned on separately: Journal/, Notes/, Meetings/, Reading/ and Daily/. A toggle grants or revokes immediately, and revoking needs nothing except the session you are already signed in to. Unpair from the same tab, and the ~Alter/ folder stays exactly as it is.

What lands in your vault

~Alter/
  .alter-managed          sentinel, with a do-not-edit frontmatter warning
  PAIRING.md              handle, vault path hash, granted_at, purposes, subtags
  RETURN.md               rolling synthesis, newest entry at the bottom
  INCOME.md               vault-sourced Identity Income ledger
  METHOD-AUDIT.ndjson     one append-only row per signal, showing its derivation
  THEMES/<slug>.md        emergent themes
  CONSEQUENCES/<date>.md  consequence previews before promotion

The folder name is fixed, because it is what ties this vault to your handle. Everything in it is written through Obsidian's own vault adapter rather than straight to disk, so whatever you have configured about where files go is respected. Editing anything inside ~Alter/ is at your own risk, since the plugin overwrites or merges those files on later runs.

What leaves this machine

Not your notes. The engine reads them, derives from them, and the only thing it ever produces for the wire is a capped list of signals: a trait name, a value, a confidence between 0.15 and 0.30, which folder class it came from, and a SHA-256 digest of the notes that contributed. The derivation itself stays here. METHOD-AUDIT.ndjson holds the observables, weights and calibration behind every signal, and the digest is the only link between that local row and anything sent.

Today it sends nothing at all. The egress path is written and tested, and no code in the plugin calls it yet, so the current release derives on device and writes to your vault and stops there. When it does start sending, it is the signals above and not a word you wrote.

Emotion is never inferred. The engine carries a hard exclusion list covering the whole affect and emotion family under EU AI Act Article 5(1)(d), and those traits are never computed rather than computed and then withheld. Five interpersonal and pressure traits are excluded on the same terms, because a folder of static notes carries no honest signal about how somebody handles pressure.

Confidence is capped at 0.30 no matter how much you have written, because a passive local document is weak evidence and the record should say so.

Mobile

The plugin declares isDesktopOnly: false, so it loads on iOS and Android without breaking. Pairing needs a desktop and tells you that when you try it, rather than failing quietly. Reading on mobile lands in a later release.

Building it yourself

npm install
npm run dev        # esbuild watch
npm run build      # production main.js
npm run test       # vitest
npm run lint
npm run typecheck

Thirteen of the twenty-eight TypeScript files here are tests, including boundary tests that fail if the trait engine ever imports something that could reach the network.