okiro 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,11 @@
 # 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 with different approaches, then compare and promote the best one.
+
+## Why?
+
+When you're unsure which approach is best: Tailwind vs custom tokens, TanStack vs lightweight fetch layer, or even different architectural patterns, you can have multiple AI agents work on isolated copies of your code simultaneously. Compare the results side-by-side, pick the winner, and merge it back.
 
 ## Install
 
@@ -10,58 +15,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"
 ```
 
-Okiro clones your project using APFS copy-on-write (macOS) or reflinks (Linux). Clones are instant and use zero disk space until files change.
+### Cleanup
 
-Each AI session (Claude Code, Cursor, Opencode, etc.) works in its own sandbox without knowing it's sandboxed.
+```bash
+okiro status               # Show active variations
+okiro cleanup              # Remove all variation workspaces
+```
+
+## How it works
 
-## Commands
+1. **Efficient cloning** — Uses APFS clones on macOS and btrfs reflinks on Linux for instant, space-efficient copies. Falls back to rsync elsewhere.
 
-| 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 |
+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.
 
-## AI Integration
+3. **Smart diffing** — Only tracks meaningful changes, ignoring `node_modules`, `.git`, `dist`, etc.
 
-With `--prompt`, okiro creates `AGENTS.md` and `.cursor/rules` in each variation with your directions. The AI picks these up automatically.
+4. **Non-destructive** — Your original codebase is never touched until you explicitly `promote`.
+
+## 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"
 
-## Requirements
+# Enter directions when prompted:
+#   var-1: use Better Auth
+#   var-2: use Clerk
+#   var-3: roll our own with JWT + cookies
 
-- Node.js 18+
-- macOS 10.13+ or Linux
+# Open each variation in a separate Cursor window
+# Let the AI agents cook...
+
+# Compare results
+okiro compare
+
+# 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.2",
+  "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",