Yoshi 🍊

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

Installation

Install Yoshi AI globally via npx:

``bash
npx yoshi-ai
`

The package name is yoshi-ai.

$3

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

$3

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

$3

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

Once planned, start automated build:

Simple one-command start:
`bash
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:
`bash
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
bash ~/.config/opencode/yoshi/loop.sh
`

Claude Code:
`bash
bash ~/.claude/yoshi/loop.sh
`

Local installation:
`bash
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

$3

Want to change direction while loop is running?

`bash
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:

`bash
npx yoshi-ai
`

Run the installer again - it will overwrite existing configuration.

To start loop:
`bash
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

`bash
npm install
npm run install # Test installation
``