Yoshi 🍊

The Council + Ralph Loop for AI-driven software development with OpenCode and Claude Code.

Installation

Install Yoshi AI globally via npx:

npx yoshi-ai

The package name is yoshi-ai.

Interactive Setup

The installer will guide you through:

1. Choose Installation Scope

   • Global (~/.config/) - Available to all projects
   • Local (.opencode/) - Available to this project only

2. Choose AI Tool

   • OpenCode
   • Claude Code

3. Choose Model Configuration

   • Use OpenCode default (Recommended)
     • Agents will use whatever model you've set in your OpenCode/Claude Code settings
     • Works with any provider/model
   • Specify custom models
     • Set different models for each agent
     • Provider-specific IDs (e.g., anthropic/claude-3-5-sonnet-20240620)

Usage

1. Start a New Project

cd my-project
opencode  # or 'claude' if using Claude Code

2. The Council (Use Tab Key)

Press Tab to cycle through primary agents:

Step 1: Vision (yoshi-vision)

• Defines features, user personas, and scope
• Creates PRD.json
• Asks: "What problem are we solving?", "Who is it for?"

Step 2: Stack (yoshi-stack)

• Defines technology choices and architecture
• Creates TECH_SPEC.md
• Asks: "Which frontend?", "Database choice?", "Auth provider?"

Step 3: Planner (yoshi-planner)

• Breaks down requirements into executable tasks
• Creates TASKS.json and STATE.md
• Generates sequential build plan

3. The Ralph Loop

Once planned, start automated build:

Simple one-command start:

npx yoshi-ai ralph

This will:

• Prompt you to select AI tool (opencode or claude)
• Show nice ASCII art
• Start → build process

Or specify tool directly:

npx yoshi-ai ralph --tool opencode
npx yoshi-ai ralph --tool claude

This will:

• Find your loop.sh script automatically
• Show nice ASCII art
• Start the build process

Or run script directly:

OpenCode:

bash ~/.config/opencode/yoshi/loop.sh

Claude Code:

bash ~/.claude/yoshi/loop.sh

Local installation:

bash .opencode/yoshi/loop.sh
# or
bash .claude/yoshi/loop.sh

The loop:

• Runs tasks one by one with fresh context
• Commits each task automatically
• Updates STATE.md with decisions
• Tags releases when complete

4. Intervene (Optional)

Want to change direction while loop is running?

echo "Use shadcn/ui for components, not default HTML" > FEEDBACK.md

The next task will read FEEDBACK.md and follow your instructions.

After task runs, feedback is archived to FEEDBACK.processed.md.

Smart Behavior

All agents check for existing files and prompt with selectable options:

Vision agent: "Found PRD.json" → Review, Update, or Recreate? Stack agent: "Found TECH_SPEC.md" → Review, Update, or Recreate? Planner agent: "Found TASKS.json" → Review, Extend, or Regenerate?

This makes it easy to iterate on existing projects.

Reconfiguration

To change models or switch AI tools:

npx yoshi-ai

Run the installer again - it will overwrite existing configuration.

To start loop:

npx yoshi-ai ralph

This is cleaner than remembering the loop script path!

Philosophy

The Council: Different agents for different expertise

• Vision = Creative (temp 0.8)
• Stack = Conservative (temp 0.1)
• Planner = Focused (temp 0.2)

The Ralph Loop: Fresh context every iteration

• Each task in a new process
• Zero context accumulation
• Git commits = source of truth

Requirements

• OpenCode CLI or Claude Code
• Node.js
• jq

Development

npm install
npm run install  # Test installation