β οΈ Please note: This app is under active development. It is riddled with bugs. Everything is subject to change.
tldr: An organizational tool for your mind's eye.
koad:io is a sovereign, local-first command-and-control framework for automating your digital life. It keeps identity, environment, and intent as files and folders you own, so your scripts, your services, and your notes stay composable, auditable, and yours to move.
The rule underneath it is one sentence: think once per idea, encode it as a named shard, wire it in β and never think about the mechanics of it again. The system remembers so you don't have to.
"Your systems need to be faster than you (can) think." β adapted from Getting Things Done
Fork it before you clone it. This repository is a moving target: the thing you clone is the framework on a running machine, it changes shape often, and local edits will eventually meet a rewrite. A fork is yours to steer;
upstreamis yours to pull from when you want what changed.
By saving a task as a command, and saving its working context as an entity,
I can:
- π Remember how you did a thing
- π Replay it later, identically
- β³ Audit your decisions and assumptions
- π Keep your stuff together as simple files and folders
- π§ Internalize the structure of your work
- π¦ Package or pass projects on as-is
- π Visualize the state and focus areas of your system
That list is the whole product. Everything below it exists to make one of those seven lines true on a machine you own.
- π§± Entities β containers for env variables, commands, and keys
- π§Ύ Commands β repeatable tasks saved as scripts
- π§ Context-aware execution β auto-loads
.env, keys, and project scopes - π Identity-backed assertions β sign, verify, and log in with your own keys
- π Everything is a file β readable, diffable, yours, and on your disk
- π§° No cloud required β no service holds your mind for you
Everything in koad:io is a named shard at a different scale:
| Shard type | What it is |
|---|---|
| Commands | Named operational verbs β remembered procedures |
| Entities | Containers of identity, context, and capability |
| Primers | Orientation documents β how a folder works, for a person or a program |
| Packages | Portable application components β composable building blocks |
| Bonds | Signed capability grants β explicit trust declarations |
| Harnesses | Named execution surfaces β how an entity runs |
| Skills | On-demand capability packages |
The apps themselves are thin shells. The real system lives in packages β each
one an independent repository, resolved through KOAD_IO_PACKAGE_DIRS:
KOAD_IO_PACKAGE_DIRS=$HOME/where/you/keep/packagesAn entity may also keep packages of its own in ~/.<entity>/packages/. The
framework tree ships no Meteor packages of its own, so the skeleton you clone
contains structure and runtime β never someone else's product code.
Each package declares its own scope. Each command declares its own contract. Each entity declares its own identity. And the system wires them together through a deterministic cascade.
This means:
- You never have to remember how things get wired together
- Each part can be read, and understood, on its own
- Each component is auditable, portable, and replaceable
- Adding capability means dropping in a shard, not refactoring an app
koad:io was born in 2014 β long before AI agents, before "coding assistants," before the current wave of synthetic intelligence. But the game it plays started in 1997 β when social networks and public statements started piling up, and a choice emerged:
Publish to the public surface, or maintain your own rights.
Rights are responsibilities. And the responsibility of sovereignty is this: everything you put on a platform you don't control becomes permanent, searchable, and weaponizable. Not by you. By whoever owns the database.
koad:io rejects that at the foundation. Instead:
- The filesystem is your cognitive prosthetic
- Commands are remembered procedures
- Entities are externalized working patterns
- Bonds are explicit trust, not implicit permission
- Packages are portable components, not monolithic apps
- Silence is a feature β you build, the system remembers, nobody else gets a copy
Synthetic intelligence arrived later, and it did not change what koad:io is. It changed who else can operate it β an afterthought in the honest sense, which is why it is documented near the end of this page rather than at the top.
~/.koad-io/ β Framework: cascade, commands, hooks, helpers, harness, daemon
~/.<entity>/ β Entity: identity, keys, memories, commands, trust bonds
Every command runs through the entity launcher (<entity> <cmd> [args]). The launcher fires the env cascade before any script executes:
~/.koad-io/.env β Framework defaults
~/.<entity>/.env β Entity overrides
~/.<entity>/.credentials β Entity secrets β never in git
./commands/.env β Command-local overrides
By the time a command runs, every variable β ports, bind addresses, database URLs, domain names β is already resolved. The cascade is the contract. Running a tool directly (skipping the launcher) breaks it.
alice whoamiExpands to:
set -a
source ~/.koad-io/.env
source ~/.alice/.env
source ~/.alice/.credentials
~/.koad-io/commands/whoami/command.shRun the same verb outside the launcher and it degrades to the system whoami β
there is no entity to report. That is the contract, visible in one command.
No guessing. No configuration drift. No remembering.
Entities are containers of context β each one holds:
- Identity (GPG keys, SSH keys, fingerprints)
- Environment (
.env,.credentials) - Commands (entity-specific operational verbs)
- Memories (saved context, destination notes)
- Trust bonds (signed capability grants from other entities)
- Skills (on-demand capabilities)
- Briefs, flights, and operational state
An entity is a working persona β a projection of how one part of your work happens. You keep one for yourself, and one for each role you want held apart: a builder, an auditor, a correspondent, a set of hands for the machine. It is a place to keep that role's identity, environment, and commands together, so the work can be replayed, audited, or handed over.
How many you keep, and what you call them, is yours.
koad:io was not built for a synthetic intelligence. It was built so that a person could keep their own memory in files. But a substrate that already knows where your identity, your commands, and your context live is exactly what a synthetic collaborator needs in order to be useful β and exactly what makes it dangerous to hand over carelessly. Two halves make that safe.
- Tool visibility follows resolved bond scope
- Tool execution is refused by path, extension, and grant checks
- Read, write, and exec lanes are scoped per bond
- Commands can be granted one at a time, not as the whole cascade
- Dispatch targets are restricted by bond
- Shell calls are rerouted to typed, auditable tools
- Results are scrubbed β secrets never reach the model
The gate answers what a collaborator may attempt. What it did is a different question, and one the framework does not answer on its own: attribution starts here β every action is taken as an entity, under a bond, inside a session β and the surfaces that keep the record run beside the framework rather than inside it.
Together: constrained embodiment, auditable custody. A collaborator does not get to act unattributed.
[BUG SALAD]
Use at your own curiosity. It works. But only mostly. Maybe.
koad:io is a living system. The substrate (commands, entities, cascade, packages) is stable. The AI integration layer (pi harness, bond gate, control surface) is evolving fast. Things break, change shape, and get reorganized.
The framework carries a contract suite. Each file exists because a real defect reached a live install, and the suite is what stops it coming back:
bash ~/.koad-io/test/all # everything, ~100s
bash ~/.koad-io/test/all --fast # the shell contracts only, ~2s
bash ~/.koad-io/test/all --list # what runs, and how it is tieredThe runner discovers test/*.test.sh and test/*.test.mjs β a new suite runs
the day it lands, without editing the runner. It exits non-zero on any
unrecorded failure. Paths resolve from the runner itself, so every mode is
cwd-independent except --staged, which reads the git index of the repository
that contains your current directory β run it from inside ~/.koad-io.
Committing to the shared root runs the suite first. Fast tier always, the
slow acceptance suites only when a staged path falls in that suite's declared
surface (test/all --staged). A red suite that is not in the known-failing set
refuses the commit. An unmapped slow suite also refuses rather than being
silently skipped. The gate has no per-commit override of its own.
test/known-failing.txt is a dated, owned, reasoned list of failures the gate
tolerates while they are being fixed. An entry is an admission, not a
dismissal. A red suite that is recorded there does not block a commit; a red
suite that is not recorded does. The file's header carries the full eight-rule
contract; two rules matter most in daily use:
- Rule 6 β the tolerance is withdrawn for the surface you touch. If a staged path falls in an entry's declared surface, that suite must pass for this commit. You cannot edit around a known failure.
- Rule 4 β a recorded failure that starts passing is announced, never silent, so entries cannot rot into permanent lies. Delete the entry once it is fixed.
An entry whose suite no longer exists is flagged stale, and one older than 30 days warns on every run. The whole set is printed on every run: a standing confession, not a mute.
~/.koad-io is not a checkout of the framework β on a running machine it is
the framework, and there is no deploy step between "committed" and every
entity's next command. So the substrate declares its own check, and the git
command arms it on every invocation:
| Piece | Where it lives | Whose job |
|---|---|---|
| the declaration | ~/.koad-io/koad-io.check β one executable file at the repo root |
this repo's |
| the arming | ~/.forge/commands/git/gate.sh β -c core.hooksPath=<derived>/hooks |
the command's |
| the hook | ~/.forge/commands/git/hooks/pre-commit |
the command's |
koad-io git commit β and commit, which hands off to it β arms that layer
for the one invocation, so the hook fires on the tree actually being committed.
The hook runs koad-io.check from the repository toplevel; the declaration runs
test/all --staged, which decides the tier. Nothing is installed by hand and
there is no symlink to forget: a gate armed by hand is not armed.
Ask what would happen here, without committing:
koad-io git armedIt prints the hooks path and the hook's mode bit, whether this repo declares a check, and whether the declaration would run β it measures, it does not judge.
Bare git commit runs none of this, and that is deliberate: the door is the
path entities actually take. git commit --no-verify skips the hook because git
never invokes it β git's own flag on a lane the door does not own. On the door's
lane, --no-verify and -n are refused by name rather than half-honoured.
The hook steps aside for a rebase/merge/cherry-pick/revert in progress β those re-apply commits that already ran the suite when they were authored.
The root is two things at once: a tree you can clone, and β on a running machine β
the place where the console, the desktop widget, the passenger metadata, the
workspace skeletons, the lighthouse, and the sovereign's own me/ are checked out
beside it as separate repositories. The listing therefore differs machine to
machine, and a diagram of it goes stale by the next commit.
The inventory that knows the answer is PRIMER.md β walked,
dated, and corrected against the disk. Trust it over any tree drawn here.
.alice/
βββ id/ # GPG keys, SSH keys, fingerprints
βββ commands/ # Entity-specific commands
βββ memories/ # Saved context
βββ trust/bonds/ # Signed capability grants (.md.asc)
βββ skills/ # On-demand capabilities
βββ briefs/ # Active briefings
βββ destinations/ # Prior-visit notes per host/path
βββ packages/ # Entity-specific packages
βββ .env # Entity identity + config
βββ .credentials # Entity credentials
βββ hooks/ # Entity lifecycle hooks
βββ .local/ # Local state (harness sessions, runtime)
# Who is on the line
alice whoami
# Derive a stable content id from a human name
alice generate cid "Addison Cameron-Huff"
# Deploy a skeleton into an empty directory
cd ~/Workspace
mkdir my-project && cd my-project
alice spawn bare
koad:ioships a small set of plumbing verbs. The rest β the ones your work actually runs on β you name and write yourself.
- No cloud, ever. Your keys, your data, and your substrate stay on hardware you control.
- Identity-first. Bonds are explicit and auditable. The constitution lives in the gate, never in the prompt.
- Modular, file-based, reproducible. Files and folders are the external mind. Locality makes memory at scale possible.
- Think once, encode forever. Every saved command, entity, package, and bond is an idea you never have to think about again.
- Silence is a feature. Everything you put on a platform you don't control becomes permanent and weaponizable. Build on your own hardware. Nobody else gets a copy.
- Rights are responsibilities. The responsibility of sovereignty is choosing what to publish and what to keep.
- Designed for thinkers, hackers, and sovereign operators. A $200 laptop, harnessed correctly, is enough to throne up.
install.mdβ stand a kingdom up: prerequisites, gestation, first entityGLOSSARY.mdβ the words this system uses, defined onceKOAD_IO.mdβ the layer every entity loads before anything elsePRIMER.mdβ the framework inventory: what is here, walked and dated- Commands guide
- kingofalldata.com β the public storefront
- alice repo β a complete, working entity
Come hang out in the #io:koad.sh room β share flows, scripts, bugs, ideas.
Four tiers, one thesis: AGPL-3.0 at the core, 0BSD at the outskirts, the
Kingdom License on published entity templates, CC0 on documentation.
LICENSING.md owns the terms β this page only points at it.
"I am an amateur. This might all be shit. It's too early to tell." β @you, wisely