⚠️ 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 encapsulates identity, environment, and intent — letting you structure your scripts, services, and thoughts as composable, auditable entities.
At its core, koad:io is a modular CLI toolchain designed to manage:
- ⚙️ Reusable commands and workflows
- 🔐 Identity-backed assertions
- 📂 Project- and context-scoped environments
- 🗂️ Data and service organization across machines, devices, and personas
Whether you're managing shell scripts, building full-stack apps, or signing cryptographic login requests — koad:io helps you keep the whole thing structured, shareable, and verifiable.
“Your systems need to be faster than you (can) think.”
— adapted from Getting Things Done
By saving a task as a command, and saving its working context as an entity, I can:
- 📜 Remember how I did a thing
- 🔁 Replay it later, identically
- ⏳ Audit my decisions and assumptions
- 🗃 Keep my stuff together as simple files and folders
- 🧠 Internalize the structure of my work
- 📦 Package or pass projects on as-is
- 👁 Visualize the state and focus areas of my system
[BUG SALAD]
Use at your own curiosity. It works. But only mostly. Maybe.
- 🧱 Entities = containers for env variables, commands, and keys
- 🧾 Commands = repeatable tasks saved as bash scripts
- 🧠 Context-aware execution = auto-loads
.env, keys, and project scopes - 📜 PGP assertion system = sign/verify/login flows via GPG
- 🔗 Meteor integration = talk to local/remote daemons with verifiable identity
- 🧰 No cloud required = all data is stored locally
.koad-io/
├── bin/ # Entrypoint commands (alice, koad, etc.)
├── commands/ # Global command templates
├── packages/ # Local Meteor packages
├── skeletons/ # Project templates
├── hooks/ # Execution hooks
├── .env # Global koad-wide vars
├── .credentials # Private credentials (not in git)
└── .aliases # Optional alias layerEach entity has its own world:
.alice/
├── id/ # GPG keys (pub+priv), SSH keys
├── commands/ # Persona-level commands
├── skills/ # opencode skills
├── memories/ # Context memories
├── skeletons/ # Custom project templates
├── packages/ # Entity-specific Meteor packages
├── .env # Local config
├── .credentials # Entity credentials
├── hooks/ # Optional pre/post exec scripts
└── .local/ # Local data (minimongo if no MongoDB)koad:io supports local Meteor packages via METEOR_PACKAGE_DIRS.
Set in ~/.koad-io/.env:
METEOR_PACKAGE_DIRS=$HOME/.ecoincore/packages:$HOME/.koad-io/packagesThis allows:
- Custom packages in
~/.koad-io/packages/ - eCoinCore packages in
~/.ecoincore/packages/ - Entity-specific packages in
~/.alice/packages/
Set MONGO_URL in entity's .env:
MONGO_URL=mongodb://localhost:3001/mydb- All apps share same database
- Single login via Meteor Accounts + OAuth
- Apps can share data
Each Meteor app creates minimongo in .local/meteor/
- App is isolated from other apps
- No shared data
- Good for testing/prototyping
# Login via SSH to a different device
alice ssh crapple
# Sign a message with alice's key
alice sign "I am the sovereign."
# Generate a login assertion for a domain
alice generate login wonderland.koad.sh
# Generate a login assertion for a domain and deliver it
alice login wonderland.koad.sh [session id]Or pipe anything into a clipboarded GPG clearsign:
echo "hello world" | alice sign- 🚫 No cloud, ever
- 🔐 Identity-first
- 🧱 Modular, file-based, reproducible
- 🧠 Designed for thinkers, hackers, and sovereign operators
Come hang out in the
#io:koad.sh room — share flows, scripts, bugs, ideas.
MIT — Yours to fork, break, and rebuild.
“I am an amateur. This might all be shit. It's too early to tell.” — @you, wisely
Some folks fear the command line. But we know the truth:
If you're comfortable with bash, koad:io will make perfect sense.
If not — well, maybe someone will build a UI for you. Eventually.
Start a site:
alice start site kingofalldata.comOpen Element (Matrix) as Alice:
alice open elementSSH into "toronto" as Alice:
alice ssh toronto
koad:iodoesn’t ship with commands. You build your own — intimately, intentionally.
Every command execution goes through a deterministic path of evaluation:
-
Call an entity wrapper →
alice start,alice hello, etc. -
No arguments? → Run
hooks/executed-without-arguments.sh→ Harness selected byKOAD_IO_ENTITY_HARNESS(default:opencode, team entities setclaude) → Opens the entity as an interactive AI session — or runs non-interactively whenPROMPT=is set → Seehooks/PRIMER.mdfor full documentation -
Set environment:
ENTITY=aliceCWD=$PWD
-
Call core CLI wrapper: →
~/.koad-io/bin/koad-io $@ -
Load environments (if present):
~/.koad-io/.env~/.$ENTITY/.env~/.$ENTITY/.credentials
-
Find the command script:
~/.koad-io/commands/~/.$ENTITY/commands/$CWD/commands/./$COMMAND.sh
-
Load local env (if needed):
$CWD/.env$CWD/.credentials
-
Execute command.sh with full context.
Example 1:
alice probe domain koad.shBreaks down to:
set -a
source ~/.koad-io/.env
source ~/.alice/.env
~/.koad-io/commands/probe/domain/command.sh koad.shExample 2:
alice archive video https://www.youtube.com/watch?v=dQw4w9WgXcQBreaks down to:
set -a
source ~/.koad-io/.env
source ~/.alice/.env
~/.koad-io/commands/archive/video.sh https://www.youtube.com/watch?v=...Will store output in
~/.alice/archive/inboundor the path inKOAD_IO_ARCHIVE_FOLDER.
KOAD_IO_ARCHIVE_FOLDER=$HOME/.alice/archive/inbound-
Install dependencies:
-
Clone the repo:
git clone https://github.com/koad/io.git ~/.koad-io- Add it to your
PATH(append to~/.bashrc):
[ -d ~/.koad-io/bin ] && export PATH=$PATH:$HOME/.koad-io/binOne-liner install:
git clone https://github.com/koad/io.git ~/.koad-io && echo -e "\n\n[ -d ~/.koad-io/bin ] && export PATH=\$PATH:\$HOME/.koad-io/bin\n" >> ~/.bashrc && export PATH=$PATH:$HOME/.koad-io/binmacOS uses zsh by default. Profile file is ~/.zshrc, not ~/.bashrc.
1. Install nvm (Node Version Manager):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bashnvm appends itself to ~/.zshrc automatically. Reload your shell:
source ~/.zshrc2. Install Node.js and Claude Code:
nvm install 24
nvm use 24
npm install -g @anthropic-ai/claude-codeClaude Code will be available at ~/.nvm/versions/node/<version>/bin/claude.
3. Clone koad:io and add to PATH:
git clone https://github.com/koad/io.git ~/.koad-io
echo '\n[ -d ~/.koad-io/bin ] && export PATH=$PATH:$HOME/.koad-io/bin' >> ~/.zshrc
source ~/.zshrcOne-liner install (macOS/zsh):
git clone https://github.com/koad/io.git ~/.koad-io && echo '\n[ -d ~/.koad-io/bin ] && export PATH=$PATH:$HOME/.koad-io/bin' >> ~/.zshrc && export PATH=$PATH:$HOME/.koad-io/bin4. Verify the install:
which koad-io # should show ~/.koad-io/bin/koad-io
koad-io --version
claude --version # confirm Claude Code is accessiblemacOS gotchas:
- Homebrew PATH: If you use Homebrew (
/opt/homebrew/bin), it's added to~/.zshrcby the Homebrew installer. No manual action needed, but ensure it appears before the nvm block. - Apple Silicon (M1/M2/M3): Homebrew installs to
/opt/homebrew/(not/usr/local/). This is already handled by the Homebrew installer. - nvm + zsh: If
nvmisn't found after install, check that~/.zshrccontains the nvm init block and runsource ~/.zshrc. - System node conflict: macOS may ship a system Node.js or have one from Homebrew. Always use
nvm use <version>to ensure the correct Node.js is active. Runwhich nodeto confirm you're using the nvm-managed version.
git clone https://github.com/koad/alice.git ~/.alice
koad-io init aliceCreates the alice command, skips key generation.
koad-io gestate myentityCreates from scratch with keys, directories, and wrapper.
If running from an existing entity:
alice gestate newentityCopies skeletons, commands, packages from mother entity!
Back this up. Store it somewhere ridiculously safe.
Start here:
- Bash Cheatsheet
- Browse
./commands/for prototypes
mkdir ~/.koad-io/commands/hello
cd ~/.koad-io/commands/hello
cat <<EOF > command.sh
#!/usr/bin/env bash
echo "hi there, \$ENTITY here!"
echo "args: \$@"
EOF
chmod +x command.shRun from anywhere:
alice hello
alice hello arg1 arg2mkdir ~/.alice/commands/hello
cd ~/.alice/commands/hello
cat <<EOF > command.sh
#!/usr/bin/env bash
echo "hi there, \$ENTITY here!"
echo "args: \$@"
EOF
chmod +x command.shRun only with Alice:
alice hellocd ~/some/random/folder/
cat <<EOF > hello.sh
#!/usr/bin/env bash
echo "hi there, \$ENTITY here!"
echo "args: \$@"
EOF
chmod +x hello.shThen:
alice hello
koad:ioisn’t just CLI automation — it’s a system for embedding memory into code, and shaping your tools around your mental model.
Now go build yours. Your entity is listening.
Check the commands/ folder — there's not a lot preloaded. And that's intentional.
You're meant to build this your way. But here's what's included by default:
- gestate — create new entity (full: keys + dirs + wrapper)
- init — initialize existing folder (skip keys, create wrapper)
- spawn — deploy skeleton to current folder
- whoami — introspect the current environment
- example — explore supported patterns
Use these to see how to write koad:io commands in different languages:
Run the base example:
alice exampleSample output:
see how these examples work by taking a peek into the ~/.koad-io/commands/example folder
this output is created by the file ~/.koad-io/commands/example/command.sh
Run language-specific demos:
alice example bash
alice example javascript
alice example python
alice example rust
alice example goEach one is a minimal, working prototype in its language — meant to inspire your own tools.
Skeletons provide precise, reproducible starting points for projects.
- Create skeleton in
~/.koad-io/skeletons/<name>/ - Structure:
skeleton/folder +control/scripts - Run
alice spawn <name>to deploy to current folder
- bare — Minimal Meteor app
- interface — UI-focused project
- lighthouse — Lighthouse-related
control/pre-install— runs before copyingcontrol/install— main setupcontrol/post-install— runs after copying
Meteor is the default compiler, but you can replace it with:
- Vite
- webpack
- Any build tool
Just modify the skeleton's install script. Skeletons bring context — not random starts, but precise ones.
Need inspiration? Explore the Alice repo — a complete, working entity built with koad:io.
Alice is designed to showcase the real-world utility and creativity behind the koad:io approach.
🛰 Check it out, fork it, remix it — and build your own synthetic intelligence system.
koad-io is an open-source project, and contributions are always welcome. If you'd like to contribute to koad-io, please take a look at our contributing guidelines for more information.
As mentioned above, I am an amateur;
I have been using computers for a long time, programming for a long time; but, I totally suck in a lot of ways.
I'd appreciate any feedback from any seasoned
bashusers out there!
Contributions, issues, and feature requests are welcome!
Give a ⭐️ if you like this project!
P.S. somebody somewhere, sometime, will create a voice controller for this,. so keep that in mind when creating commands. You have full control, imagine if you were able to teach siri over time (for yourself); it would be amazing.
/koad