Kuuzuki v0.1.16: Enhanced AI Resilience and NPM Package Fixes
# Kuuzuki v0.1.16: Enhanced AI Resilience and NPM Package Fixes Published: August 1, 2025 We're excited to announce the release of Kuuzuki v0.1.16, which brings significant improvements to AI tool resilience, fixes critical npm package distribution issues, and achieves 95%+ parity with the original OpenCode project. This release represents a major step forward in making Kuuzuki a reliable, community-driven AI terminal assistant. ## 🎯 Key Highlights - AI Tool Resilience: Fixed crashes when AI uses invalid parameters - NPM Package Fix: Resolved "macros cannot be run from node_modules" error - OpenCode Parity: Achieved 95%+ compatibility with original OpenCode - Improved Stability: Fixed temporal dead zone and TypeScript compilation errors ## 🛠️ The TodoWrite Validation Error Fix ### The Problem One of the most frustrating issues users encountered was the AI assistant crashing when trying to use the TodoWrite tool with a "critical" priority level. The error message was cryptic: ``` Error: Invalid enum value. Expected 'high' | 'medium' | 'low', received 'critical' ``` This would cause the entire AI session to crash, losing context and progress. ### Root Cause Analysis The issue stemmed from a mismatch between what the AI naturally wanted to use (including "critical" priority for urgent tasks) and what our validation schema allowed. The TodoWrite tool used strict Zod schema validation that only accepted three priority levels: ```typescript // Before: Limited priority options priority: z.enum(["high", "medium", "low"]).describe("Priority level of the task") ``` ### The Solution We implemented a two-pronged approach to fix this: 1. Extended the schema to include "critical" as a valid priority: ```typescript // After: Including critical priority priority: z.enum(["high", "medium", "low", "critical"]).describe("Priority level of the task") ``` 2. Added validation middleware to gracefully handle invalid parameters: ```typescript // Validation middleware in session/index.ts try { if (item.parameters && 'parse' in item.parameters) { validatedArgs = item.parameters.parse(args) } } catch (validationError: any) { // For TodoWrite, default invalid priorities to 'medium' if (item.id === 'TodoWrite' && validationError.message?.includes('Invalid enum value')) { // Gracefully handle and fix invalid priorities validatedArgs = { ...args, todos: args.todos.map((todo: any) => ({ ...todo, priority: ['high', 'medium', 'low', 'critical'].includes(todo.priority) ? todo.priority : 'medium' })) } } } ``` This ensures that even if the AI uses an unexpected priority value, the tool will gracefully default to "medium" instead of crashing. ## 📦 NPM Package Distribution Fix ### The Discovery A critical issue was discovered when testing the npm package installation. Users installing Kuuzuki via npm would encounter: ```bash $ npm install -g kuuzuki $ kuuzuki --version error: For security reasons, macros cannot be run from node_modules. ``` ### Understanding the Problem The issue was that our npm package was shipping raw TypeScript source files containing Bun macros. When Bun tries to run these files from node_modules, it blocks macro execution for security reasons. Our package.json files configuration was: ```json "files": [ "bin/**/*", "binaries/**/*", "scripts/**/*", "README.md", "src/**/*.ts", // ❌ Raw TypeScript with Bun macros "src/**/*.txt" ] ``` ### The Fix We updated the package to include compiled JavaScript instead of raw TypeScript: ```json "files": [ "bin/**/*", "dist/**/*", // ✅ Bun-bundled JavaScript "dist-tsc/**/*", // ✅ TypeScript-compiled fallback "binaries/**/*", "scripts/**/*", "README.md" ] ``` The bin/kuuzuki.js launcher intelligently selects the best available version: 1. First tries dist/index.js (Bun-bundled, preferred) 2. Falls back to dist-tsc/index.js (TypeScript-compiled) 3. Only uses src/index.ts as last resort (with warning) ## 🔄 OpenCode Parity Restoration ### The Journey Kuuzuki started as a community fork of OpenCode with ambitious additional features. However, maintaining these extra features while keeping up with upstream changes proved challenging. In v0.1.16, we implemented a three-phase restoration to achieve 95%+ parity with OpenCode: #### Phase 1: Remove Development Complexity - Removed experimental features like memory graphs and telemetry collectors - Simplified command structure from 22 to 8 essential commands - Maintained kuuzuki branding and .agentrc support #### Phase 2: Remove Git Permissions System - Removed the complex git-permissions feature - Simplified configuration management - Improved startup performance #### Phase 3: Final Alignment - Synchronized tool implementations with OpenCode - Updated documentation - Achieved functional parity while keeping strategic kuuzuki features ### What We Kept - Kuuzuki branding: Community identity remains - *.agentrc support**: Enhanced agent configuration - NPM distribution: Easy installation via npm install -g kuuzuki - Community focus: Open to contributions and enhancements ## 🐛 Other Important Fixes ### Temporal Dead Zone Error Fixed a critical error where the mode variable was accessed before initialization: ```typescript // Before: mode accessed at line 814, but defined at line 814 const mode = await Mode.get(inputMode) // ReferenceError! // After: Moved initialization before first use const mode = await Mode.get(inputMode) // Line 715 // ... mode can now be safely used ``` ### TypeScript Compilation - Fixed 150+ type errors across the codebase - Updated module resolution to support @openauthjs/openauth - Removed references to deleted components - Ensured clean compilation with tsc --noEmit ## 🚀 Installation and Usage With v0.1.16, installation is now reliable: ```bash # Install globally npm install -g kuuzuki@0.1.16 # Verify installation kuuzuki --version # Start the terminal UI kuuzuki tui ``` ## 🔧 Technical Implementation Details ### Build Process The release now includes a proper build step that creates both Bun-bundled and TypeScript-compiled versions: ```bash # Bun bundle (preferred, fastest) bun run build:bun # Creates dist/index.js # TypeScript compilation (fallback) bun run build:tsc # Creates dist-tsc/index.js ``` ### Testing Approach We implemented comprehensive testing for the npm package: ```typescript // Test priority validation const testCases = [ { priority: "high", shouldPass: true }, { priority: "critical", shouldPass: true }, { priority: "urgent", shouldPass: false } // Gracefully handled ] ``` ### GitHub Actions Integration The release workflow automatically: - Builds binaries for all platforms - Creates properly structured npm packages - Publishes to npm with correct versioning - Generates GitHub releases with binaries ## 📚 Lessons Learned 1. Test the actual npm package: Our validation script tested the source directory, not the installed package. Always test the end-user experience. 2. Graceful error handling > strict validation: Instead of crashing on invalid input, provide sensible defaults and continue operation. 3. Maintain focus: While additional features are tempting, maintaining parity with upstream projects ensures long-term sustainability. 4. Community feedback is invaluable: The TodoWrite crash was reported by users who depend on the tool for their daily workflow. ## 🎯 What's Next ### Roadmap - v0.2.0: Enhanced MCP (Model Context Protocol) support - v0.3.0: Improved plugin system for community tools - v0.4.0: Performance optimizations for large codebases ### Contributing Kuuzuki is a community-driven project, and we welcome contributions: - Report issues: https://github.com/moikas-code/kuuzuki/issues - Submit PRs: Fork, branch, and propose changes - Join discussions: Share ideas for new features - Write tools: Extend Kuuzuki with custom tools ## 🙏 Acknowledgments Special thanks to: - The SST team for the original OpenCode project - Community members who reported the TodoWrite crash - Contributors who helped test the npm package fixes - Everyone using Kuuzuki in their daily development workflow ## 📦 Upgrading To upgrade to v0.1.16: ```bash # Uninstall old version (if needed) npm uninstall -g kuuzuki # Install new version npm install -g kuuzuki@0.1.16 # Verify the upgrade kuuzuki --version ``` ## 🔗 Resources - GitHub: https://github.com/moikas-code/kuuzuki - NPM: https://www.npmjs.com/package/kuuzuki - Issues: https://github.com/moikas-code/kuuzuki/issues - Original OpenCode: https://github.com/sst/opencode --- Kuuzuki v0.1.16 represents a significant milestone in our journey to provide a reliable, community-driven AI terminal assistant. With improved resilience, fixed npm distribution, and strong OpenCode compatibility, we're excited to see what you'll build with Kuuzuki! Happy coding! 🚀
From Mom's Kitchen to VitaK Tracker: Building a Warfarin Management App with AI
When my mom was prescribed warfarin, I watched her struggle with something that seemed impossibly complex: keeping track of vitamin K in her daily meals. Every doctor's visit brought the same stress about her INR levels, and every meal became a calculation exercise. That's when I realized technology could help solve a very human problem.
Mastering the Browser Network Tab: A Developer's Essential Guide
As web developers, we spend countless hours debugging issues, optimizing performance, and understanding how our applications communicate with servers. One of the most powerful tools at our disposal is often overlooked by beginners: the Network tab in browser developer tools. Let's dive deep into what this tool can do and when you should reach for it.
Picking your Vibe Coding Tool
What's up Vibe Coders? Let's dive into some tools that'll level up you coding game, because picking the right one can make or kill your creative vibe. With AI changing everyday giving us all these AI powered goodies like Cursor, v0.dev, framer.com, loveable.dev, rork.com, Claude Code, and Windsurf all popping off, it's easy to get lost in the sauce. Each with their own Pro's and Con's giving off it's own aura. To make things easier for you I'll break down a few tools I've been following or had a chance to use. Quick Vibes: What These Tools Are About Here’s the lowdown on these tools—think of it as your cheat sheet for Part 1 of "Get Started with Vibe Coding." They’re all about making coding smoother, faster, and downright fun, whether you’re live streaming or just kicking back with some code Cursor: Your AI Coding Sidekick Cursor’s an AI-powered editor that’s all about making you a more efficient and productive programmer. It predicts your edits, answers codebase questions, and lets you tweak code with a quick “hey, do this” prompt. Big dogs like Shopify use it, and I’m hooked especially with the Claude Code implementation for big wins. Personally If you aren’t using Claude Code in Cursor, you’re wasting time. It’s the ultimate vibe coding tool. Features: Code completion, AI chat with codebase smarts, rewrites, privacy mode. Vibe Fit: Devs who want speed, perfect for live fixes or builds. Link: Cursor Features v0.dev: Quick UI Magic v0.dev’s got that Vercel, NextJS sauce; you describe your UI, and it drops React code with Shadcn and Tailwind. It’s prototyping heaven, like a landing page in an hour. I’ve been mulling it over on X the strat starting in v0.dev, then moving to Cursor once you have a solid MVP. The platform has been experiencing changes lately recent implementing their design Mode, so they might be even more of a value add. Features: Text-to-UI, Figma hookup, full-stack ready. Vibe Fit: Front-end fiends and rapid prototypers. Link: v0.dev Loveable.dev: Chat-to-App Realness Loveable.dev’s like your AI coding buddy—chat what you want, and it builds full-stack apps with React and Vite. Integrates with Supabase and more. It’s new, but perfect for startups or solo vibes—just nail those prompts. Loveable is a project that I've seen other talk about and seen ads of but haven't had a chance to try out on my own. It looks like a solid app and can't wait to vibe code a project or two with it. I can see this being an app that works extremely well with designers who are needing to make apps with their Figma files. Features: Chat-built code, collab beta, integrations galore. Vibe Fit: Non-devs or fast prototype fans. Link: Lovable.dev Rork.com: Mobile in Minutes Rork’s AI spins up mobile apps fast with React Native. Describe it, and you’ve got navigation and login ready to go. It’s a mobile dev dream, especially for live demos or quick builds. This is another app that I haven't had much had the chance to try but wanted to add it to the list to give it a little more exposure and because I have also seen good things about the project so far. Features: Cross-platform apps, Expo testing, iOS/web support. Vibe Fit: Mobile prototyping without the fuss. Link: Rork Claude Code: Problem-Solving Pro Claude Code’s my go-to AI assistant—code gen, debugging, and codebase chats. It shines in Cursor, like I said on X, “Claude Code for the hard problems.” Keeps the vibe strong for complex live stuff. Claude Code is for sure my favorite out of all of these with cursor coming in second place. I use the 20x Max version of Claude Code with the cursor integration and this is by far the best decision I made. This blog is a result of the Claude Code and Cursor implementation, landing with about a 90% accuracy, there were a few files I had to edit my self , but the bulk of the project was handled by Claude and I can't wait to see what they come out with next. Features: Code creation, debugging, terminal vibes, codebase know-how. Vibe Fit: Devs tackling tough tasks on stream. Link: Claude Code Windsurf: Flow State Champ Windsurf’s an AI editor that keeps you locked in—auto-fixes, design-to-code, and smooth workflows. It’s Cursor’s cousin with a productivity edge. Haven’t shouted it out much, but it’s fire for live coding. This is another tool I've only heard good things about, wantd to add it to he list so that you all knew what your options were. Windsurf is similar to cursor in how it functions and a great tool for Jr's and Sr's who are already use to VSCode and want a tool that is more reliable that co-pilot. Features: AI autocomplete, in-editor chat, collab flow, privacy-first. Vibe Fit: Devs who want seamless coding vibes. Link: Windsurf Tool Vibes Comparison Tool What It Does AI Vibes? Best For Coffee Needed? Cursor Code editing Yes Bug fixes, big builds Medium ☕☕ v0.dev UI generation Yes Prototyping, front-end Low ☕ Loveable.dev Full-stack apps Yes Non-devs, quick ideas Low ☕ Rork.com Mobile apps Yes Mobile prototyping Low ☕ Claude Code Coding assist, editing, planning Yes Tough stuff, debugging, big builds Medium ☕☕ Windsurf Code editing, flow Yes Live coding flow Medium ☕☕
Welcome
We have been developing a few things already using the power of AI to help Vibe Code some of my ideas that I've had stored in my mental vault, written in my journal, or long abandoned in a repo due to a bug or switching gears to tackle a new technology.