⚠️ Please note: This app is under active development.
It is riddled with bugs. Everything is subject to change.

🧠 koad:io

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

---

🧭 Reason

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

---

⚡ Status

[BUG SALAD]
Use at your own curiosity. It works. But only mostly. Maybe.

---

🔍 koad:io at a glance

• 🧱 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

---

🛠 Directory layout (typical)

.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 layer

Each 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)

---

📦 Local Meteor Packages

koad:io supports local Meteor packages via METEOR_PACKAGE_DIRS.

Set in ~/.koad-io/.env:

METEOR_PACKAGE_DIRS=$HOME/.ecoincore/packages:$HOME/.koad-io/packages

This allows:

• Custom packages in ~/.koad-io/packages/
• eCoinCore packages in ~/.ecoincore/packages/
• Entity-specific packages in ~/.alice/packages/

---

🗄️ MongoDB Modes

With MongoDB (Centralized)

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

Without MongoDB (Isolated)

Each Meteor app creates minimongo in .local/meteor/

• App is isolated from other apps
• No shared data
• Good for testing/prototyping

---

✍️ Example usage

# 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

---

🌐 Philosophy

• 🚫 No cloud, ever
• 🔐 Identity-first
• 🧱 Modular, file-based, reproducible
• 🧠 Designed for thinkers, hackers, and sovereign operators

---

💬 Community

Come hang out in the #io:koad.sh room — share flows, scripts, bugs, ideas.

---

🪪 License

MIT — Yours to fork, break, and rebuild.

“I am an amateur. This might all be shit. It's too early to tell.” — @you, wisely

---

🐇 Want to See How Deep the Rabbit Hole Goes?

Commands

Some folks fear the command line. But we know the truth:

The magic lives here.

If you're comfortable with bash, koad:io will make perfect sense. If not — well, maybe someone will build a UI for you. Eventually.

---

🧠 Example: Potential koad:io Commands

Start a site:

alice start site kingofalldata.com

Open Element (Matrix) as Alice:

alice open element

SSH into "toronto" as Alice:

alice ssh toronto

koad:io doesn’t ship with commands. You build your own — intimately, intentionally.

📚 Read more

---

🔗 Chain Reactions: How a Command is Processed

Every command execution goes through a deterministic path of evaluation:

1. Call an entity wrapper → alice start, alice hello, etc.

2. No arguments? → Run hooks/executed-without-arguments.sh → Launches: opencode --agent "$ENTITY" --model "$OPENCODE_MODEL" ./ → This opens the entity as an AI agent in opencode!

3. Set environment:

   • ENTITY=alice
   • CWD=$PWD

4. Call core CLI wrapper: → ~/.koad-io/bin/koad-io $@

5. Load environments (if present):

   • ~/.koad-io/.env
   • ~/.$ENTITY/.env
   • ~/.$ENTITY/.credentials

6. Find the command script:

   • ~/.koad-io/commands/
   • ~/.$ENTITY/commands/
   • $CWD/commands/
   • ./$COMMAND.sh

7. Load local env (if needed):

   • $CWD/.env
   • $CWD/.credentials

8. Execute command.sh with full context.

---

🧪 Examples

Example 1:

alice probe domain koad.sh

Breaks down to:

set -a
source ~/.koad-io/.env
source ~/.alice/.env
~/.koad-io/commands/probe/domain/command.sh koad.sh

Example 2:

alice archive video https://www.youtube.com/watch?v=dQw4w9WgXcQ

Breaks 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/inbound or the path in KOAD_IO_ARCHIVE_FOLDER.

KOAD_IO_ARCHIVE_FOLDER=$HOME/.alice/archive/inbound

---

⚙️ Install koad:io

1. Install dependencies:

   • starship
   • node-volume-manager

2. Clone the repo:

git clone https://github.com/koad/io.git ~/.koad-io

3. Add it to your PATH (append to ~/.bashrc):

[ -d ~/.koad-io/bin ] && export PATH=$PATH:$HOME/.koad-io/bin

One-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/bin

---

👤 Create Your First Entity

Option 1: Clone Alice (Recommended)

git clone https://github.com/koad/alice.git ~/.alice
koad-io init alice

Creates the alice command, skips key generation.

Option 2: Gestate New Entity (Full)

koad-io gestate myentity

Creates from scratch with keys, directories, and wrapper.

Option 3: Gestate from Entity (Inherits)

If running from an existing entity:

alice gestate newentity

Copies skeletons, commands, packages from mother entity!

---

Back this up. Store it somewhere ridiculously safe.

---

🛠 Create Commands

Start here:

• Bash Cheatsheet
• Browse ./commands/ for prototypes

🔄 Global Command Example

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.sh

Run from anywhere:

alice hello
alice hello arg1 arg2

---

👤 Entity-Specific Command

mkdir ~/.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.sh

Run only with Alice:

alice hello

---

📁 Folder-Specific Command

cd ~/some/random/folder/
cat <<EOF > hello.sh
#!/usr/bin/env bash
echo "hi there, \$ENTITY here!"
echo "args: \$@"
EOF
chmod +x hello.sh

Then:

alice hello

---

koad:io isn’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.

---

🔹 Preloaded Commands

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:

📦 Base Commands

• 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

---

💬 Language-Specific Examples

Use these to see how to write koad:io commands in different languages:

• bash
• javascript
• python
• rust
• go

---

🔍 Try It: Example Command

Run the base example:

alice example

Sample 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 go

Each one is a minimal, working prototype in its language — meant to inspire your own tools.

---

💀 Skeletons: Project Templates

Skeletons provide precise, reproducible starting points for projects.

How It Works

1. Create skeleton in ~/.koad-io/skeletons/<name>/
2. Structure: skeleton/ folder + control/ scripts
3. Run alice spawn <name> to deploy to current folder

Available Skeletons

• bare — Minimal Meteor app
• interface — UI-focused project
• lighthouse — Lighthouse-related

Control Scripts

• control/pre-install — runs before copying
• control/install — main setup
• control/post-install — runs after copying

Meteor is Swappable

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.

---

🧠 Example Entity: Alice

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.

Contributing

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.

🤝 Support

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 bash users 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

License

koad-io is licensed under the GPL License.