A flight recorder and planning desk for your Omarchy machine.
Seldon keeps a plain-Markdown logbook of everything that changes on your Omarchy system: packages, config files, themes, plugins, snapshots and Omarchy updates. You plan changes as cases. Seldon matches what actually happened against those cases and shows every change nobody planned as drift, so you can explain it. A bar pill and one window, the desk, show the picture in the Omarchy shell: today, the changelog, your cases, the charts of the Prime Radiant and a graph of your machine's memory. Seldon only records: it never installs anything, never changes your system and never blocks a command.
The name comes from Hari Seldon in Asimov's Foundation: the Plan predicts, and a crisis is where reality leaves it.
Why · Features · Quick start · Tour · Install options · Documentation · Status · Contributing
Omarchy is built for working with AI agents. On a developer's machine,
agents and people install packages, edit configs and switch themes every
day. After a few weeks nobody can say why the system looks the way it
does. pacman.log and journalctl have the facts but not the reasons. A
hand-written changelog has the reasons, until you stop writing it. Seldon
keeps both in one place: the facts it collects itself, and the reasons
you or your agents give.
- Six collectors read pacman, snapper, Omarchy, plugins, the theme and your watched config files into an append-only ledger. A capture never records the same change twice.
- You plan a change as a case: a Markdown file with a zone (green, yellow, red), a risk class and a plan. It moves from queued to active, verification and completed.
- A change that no case covers is drift. You link it to a case, explain it or dismiss it, from the terminal or the desk; or your agent proposes it for all open changes and you apply the proposal.
- Claude Code's hooks, or one
seldon hookcommand for any other agent, record each changing command with the agent's name and the active case, for agent sessions inside the logbook and for the sessions Seldon starts (from~/Work, as Omarchy's own agent). The hooks sit in~/.claude/settings.jsonand do nothing in your other sessions unlessconfig.tomlsets[hooks] scope = "all". Every logbook carries anAGENTS.mdwith the rules agents follow there. - In the Omarchy shell, a bar pill counts active cases and crises. The desk opens over your desktop at the width you choose: nine sections on number keys, from Today and the Changelog (which also counts the other changes without a case) to the Prime Radiant's charts and the graph, all in your Omarchy theme.
- The logbook is Markdown and YAML in
~/Seldon, a git repository and, if you want, an Obsidian vault.seldon rebuildwrites a guide that turns a fresh install into this machine again. Nothing leaves your machine.
You need Omarchy 4 and a terminal. Nothing here needs sudo. Three
steps, about two minutes.
The engine is one program, seldon.
AUR package: coming soon. Until then install the engine from GitHub (below).
install.sh downloads the static seldon binary of a release, checks it
against the release's SHA256SUMS and refuses on a mismatch, then
installs ~/.local/bin/seldon (and the alias jax-seldon). It runs as
your user and never asks for root. With the GitHub CLI (gh) installed
and logged in, it also checks that the release workflow of this
repository built the download (gh attestation verify); without gh it
says that only the checksum was checked, and --require-verified makes
it refuse instead (SECURITY.md).
Checked form — download, read, verify, run:
cd "$(mktemp -d)"
curl -fsSLO https://github.com/JohnAndrewsX/jax-seldon/releases/latest/download/install.sh
curl -fsSLO https://github.com/JohnAndrewsX/jax-seldon/releases/latest/download/SHA256SUMS
less install.sh # read what it does
sha256sum -c --ignore-missing SHA256SUMS && bash install.shOne-liner — the script still verifies the engine against SHA256SUMS;
only the script itself goes unchecked:
curl -fsSL https://github.com/JohnAndrewsX/jax-seldon/releases/latest/download/install.sh | bashCheck it with seldon --version. If your shell says command not found,
open a new terminal: Omarchy puts ~/.local/bin on your PATH when a
shell starts.
seldon initIt asks one question, where the logbook lives (~/Seldon by default),
and takes the defaults for the rest: the first capture looks back 90 days
and records that as history "before Seldon", without asking.
seldon init --defaults asks nothing; seldon init --ask is the full
wizard. Then check the setup:
seldon doctorEvery line should say ok. On Omarchy, snapper may say degraded:
your user cannot read snapshots yet. Seldon works without them. doctor
prints the one command that allows it; it changes the root snapper
config, so Seldon never runs it for you.
omarchy plugin add https://github.com/JohnAndrewsX/jax-seldon-plugin.git --enableOmarchy asks before it clones the plugin. A pill with the Seldon mark then appears on the right of the bar: a left click opens the desk at Today, a middle click at the Prime Radiant. Seldon records the plugin's installation as routine history, not as drift. You can also add the plugin first: its setup card on Today installs the engine and creates the logbook for you, one button each (Getting started).
When something is missing, the desk says so in its header's chip and offers the fix as one click:
| State | The desk shows | One click |
|---|---|---|
| Engine missing | the setup card's step 1, "Install the engine" (or "Seldon engine missing" once it was there) | Install: install.sh from the release, in a terminal you see |
| Logbook not initialised | the setup card's step 2, "Create the logbook" | Create logbook: seldon init --defaults in a terminal |
| Index missing or unreadable | "No index yet" / "Index unreadable" | Build index: seldon status writes it |
| Index stale (older than 2 h) | "Index is stale" | Capture now |
The full list, contract mismatch and restart notice included, is in the plugin README.
Change something without telling Seldon first. Omarchy's ~/.bashrc has
a place for your own aliases; one line there is quick and easy to undo.
Then ask Seldon what it saw:
echo "alias gs='git status'" >> ~/.bashrc
seldon capture
seldon driftyellow 2026-10-09 19:22 config/config-change ~/.bashrc 01M4GV0KZY6ZYF5BBTFT5DXZ48
1 open drift item(s), 0 crisis
The change is drift: no case covers it. It is no crisis, so the pill
stays as it was: by default its number after the mark counts crises
only. The desk's header counts it under attention; the plugin
setting driftInBar set to all counts it in the bar too. The plugin
captures by itself every 15 minutes; seldon capture just saves you the
wait. Explain the change with the event id from the last column:
seldon drift explain <EVENT> -- "A short git status"Seldon records your reason as a completed case and the drift is gone. Some changes are no drift at all: a theme switch, a plugin toggle, a system upgrade and adding Seldon's own plugin are routine history. The next change you plan first:
seldon plan new --area shell -- "Remove the gs alias again"
seldon plan start <ID>
seldon log --case <ID> -- "Removing the gs alias again"plan new prints the case id. Delete the alias line from ~/.bashrc,
run seldon capture again and link the new change to the case with
seldon drift link <EVENT> <ID>. Close the case with
seldon plan verify <ID> and seldon plan done <ID>. A change an agent
makes through the hooks carries the active case on its own.
Open the desk and press 2 for the Changelog: both changes, the note
and every step of the case are there. 7 shows the Prime Radiant, 8
the graph. Each step is also a git commit in your logbook:
git -C ~/Seldon log --oneline.
The full walk-through, with the output of every command, is Getting started.
Options (with the one-liner: | bash -s -- --unit):
| Option | Effect |
|---|---|
--version vX.Y.Z |
that release instead of the latest |
--prefix DIR |
install into DIR/bin instead of ~/.local/bin |
--unit |
also install the optional watcher unit into ~/.config/systemd/user/ (installed, not enabled; see engine/systemd/README.md) |
--force |
replace a seldon (or unit) the script did not install, such as a self-built binary; without it the script refuses and changes nothing |
--require-verified |
install only when gh verified the download's build provenance; refuses when gh is missing or not logged in, or for a release up to v0.1.1 (made before attestations) |
--skip-provenance |
do not ask gh; only the checksum is checked (a note says so). For a gh that fails on its own, for example behind a proxy; not with --require-verified |
--uninstall |
remove what the script installed (give the same --prefix) |
- Update: run
install.shagain, either form. It replacesseldonwhen the release is newer; with the same version it changes nothing. Update the plugin withomarchy plugin update jax.seldon, then restart the shell withomarchy-restart-shell: until it restarts, the shell keeps running the old plugin code. The plugin then shows "Restart the shell to finish the update" with a Restart shell button; a plugin version without this notice shows nothing, so restart after every update. From 0.1.x to 0.2.0, update the engine and the plugin together (index contract 2); from 0.2.x, 0.3.x or 0.4.0 to 0.4.1 the order does not matter: what changed. - Remove:
bash install.sh --uninstall, or with the one-liner… | bash -s -- --uninstall. It removes exactly the files it installed (a file you changed since is kept, and it says so). Your logbook,~/.config/seldon/and~/.local/state/seldon/stay. Remove the plugin withomarchy plugin remove jax.seldon.
Once the package is live:
omarchy pkg aur add jax-seldon # install
yay -S jax-seldon # update
omarchy pkg drop jax-seldon # removeInstall from one source only: both put a seldon on your PATH.
| You want to | Read |
|---|---|
| Use Seldon, step by step | User guide: English · Deutsch |
| Get going in fifteen minutes | Getting started · Erste Schritte |
| Know every pill and desk key | Plugin README · Keybindings |
| Let an AI agent work in your logbook | Agent guide · llms.txt |
| Understand how it works | Concept · specs for the logbook, engine, plugin and the contract · decisions |
| Work on Seldon itself | Contributing · Development |
| See what changed | Changelog · Versioning |
An AI agent started inside a logbook follows that logbook's AGENTS.md;
an agent working on this repository follows the repository's
AGENTS.md.
v0.4.1: Seldon works on Omarchy's edge channel (Qt 6.12) as on stable;
edge's own packages and a channel switch are recognised, and the
settings files Omarchy writes itself are routine. v0.4.0 made the agent
hooks return within a millisecond in a session that has nothing to do
with Seldon, put Work's header buttons on keys and a word beside every
coloured stripe, and taught the redaction to read the commands inside
$(…), backticks and <(…). v0.3.0 brought the other desk buttons by
key, an index that stays under 1 MB on a very large logbook, and the
short agent skill. The index format is still contract 2, as since
v0.2.0, which made the desk. Before 1.0.0 a
minor release may still change the CLI, the logbook layout or the
contract; the changelog then says so under Breaking.
Next: the AUR package, the listing in the Omarchy plugin directory and
the update-impact report; then 1.0.0.
Issues and pull requests are welcome. Please open an issue before you
write anything larger than a fix, so it does not collide with planned
work. CONTRIBUTING.md has the build (just check),
the rules and how review works; everyone taking part follows the
Code of Conduct.
Report a vulnerability privately through GitHub's vulnerability reporting, never in a public issue. SECURITY.md has the scope and the alternative by e-mail. The engine has no network code and needs no root. The plugin runs inside the Omarchy shell; what it reads and runs is listed in its README.
MIT © JohnAndrewsX. Plugin id jax.seldon, AUR package
jax-seldon.
- Omarchy and its shell, which Seldon is built for.
- Quickshell and Hyprland, which the plugin runs on.
- Isaac Asimov's Foundation, for the name and the Prime Radiant.
- Keep a Changelog and the Contributor Covenant, which this repository follows.
- The Rust crates the engine is built from, listed in
engine/Cargo.toml.