okiro 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,20 @@
 # okiro
+起きろ
 
-Sandboxed AI coding variations. Generate N approaches, compare diffs, promote the winner.
+Spawn ephemeral, parallel variations of your codebase. Let multiple AI agents tackle the same task, compare results, promote the best.
+
+## Why?
+
+AI agents don’t always get it right the first time.
+okiro lets you see multiple real implementations before choosing which one belongs in your codebase.
+
+## What is this exactly?
+
+okiro does not run AI agents for you.
+
+It creates isolated workspaces so tools like Cursor, Claude, Codex, or any other agent can work independently in parallel without touching your main codebase.
+
+Think of it as cheap, disposable branches that are easy to diff and easy to throw away.
 
 ## Install
 
@@ -10,58 +24,73 @@ npm install -g okiro
 
 ## Usage
 
+### Create variations
+
 ```bash
-okiro 3                  # Create 3 sandboxed variations
-okiro 3 --prompt         # With AI directions per variation
-okiro status             # See what changed
-okiro compare            # Visual diff viewer
-okiro promote var-2      # Apply winning variation
-okiro cleanup            # Remove all variations
+okiro 3                    # Create 3 copies of your codebase
+okiro 3 --prompt           # Create 3, prompt for direction per variation
+okiro 3 --prompt "add dark mode"  # Base task + per-variation directions
 ```
 
-## How it works
+When using `--prompt`, okiro writes instructions to `AGENTS.md` and `.cursor/rules` so AI agents in each workspace know their specific approach.
+
+### Compare changes
 
+```bash
+okiro compare              # Open diff viewer in browser
+okiro diff var-1           # CLI diff: original vs var-1
+okiro diff var-1 var-2     # CLI diff: var-1 vs var-2
 ```
-Your Project              Sandboxed Variations
-────────────              ────────────────────
-/my-app/                  ~/.okiro/projects/my-app/
-├── src/                  ├── var-1/  ← AI writes here
-└── ...                   ├── var-2/  ← AI writes here
-                          └── var-3/  ← AI writes here
+
+### Pick a winner
+
+```bash
+okiro promote var-2        # Apply var-2's changes to original
+okiro promote var-2 -c     # Promote and git commit
+okiro promote var-2 -c "feat: dark mode using Tailwind"
+```
+
+### Cleanup
+
+```bash
+okiro status               # Show active variations
+okiro cleanup              # Remove all variation workspaces
 ```
 
-Okiro clones your project using APFS copy-on-write (macOS) or reflinks (Linux). Clones are instant and use zero disk space until files change.
+## How it works
 
-Each AI session (Claude Code, Cursor, Opencode, etc.) works in its own sandbox without knowing it's sandboxed.
+1. **Efficient cloning** — Uses APFS clones on macOS and btrfs reflinks on Linux for instant, space-efficient copies. Falls back to rsync elsewhere.
 
-## Commands
+2. **Isolated workspaces** — Each variation is a full copy at `~/.okiro/<project>/var-N/`. Open them in separate editor windows, run different agents, go wild.
 
-| Command | Description |
-|---------|-------------|
-| `okiro <n>` | Create n variations, open terminals |
-| `okiro status` | Show variations and changed files |
-| `okiro diff var-1` | CLI diff against original |
-| `okiro compare` | Web diff viewer (split/unified, syntax highlighting) |
-| `okiro promote var-2` | Copy changes to your project |
-| `okiro promote var-2 --commit "msg"` | Promote and git commit |
-| `okiro cleanup` | Remove all variations |
+3. **Smart diffing** — Only tracks meaningful changes, ignoring `node_modules`, `.git`, `dist`, etc.
 
-## AI Integration
+4. **Non-destructive** — Your original codebase is never touched until you explicitly `promote`.
 
-With `--prompt`, okiro creates `AGENTS.md` and `.cursor/rules` in each variation with your directions. The AI picks these up automatically.
+## Example workflow
 
 ```bash
-okiro 3 --prompt "Refactor the auth module"
-# Then enter a direction for each variation:
-#   var-1: Use JWT
-#   var-2: Use sessions
-#   var-3: Use OAuth
-```
+# You want to add authentication but aren't sure about the approach
+cd my-app
+okiro 3 --prompt "add user authentication"
+
+# Enter directions when prompted:
+#   var-1: use Better Auth
+#   var-2: use Clerk
+#   var-3: roll our own with JWT + cookies
+
+# Open each variation in a separate Cursor window
+# Let the AI agents cook...
 
-## Requirements
+# Compare results
+okiro compare
 
-- Node.js 18+
-- macOS 10.13+ or Linux
+# var-1 looks cleanest, promote it
+okiro promote var-1 -c "feat: add auth via Better Auth"
+
+# Clean up
+okiro cleanup
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "okiro",
-  "version": "0.1.1",
-  "description": "Ephemeral code variation previews for AI-assisted development",
+  "version": "0.1.3",
+  "description": "Spawn parallel AI coding variations, compare approaches, promote the winner",
   "type": "module",
   "bin": {
     "okiro": "./dist/index.js"
@@ -39,7 +39,6 @@
     "variations",
     "preview",
     "diff",
-    "ephemeral",
     "cli",
     "claude",
     "cursor",