vibe

vibe.md

Claude Opus 4.5 & Long-Running Sessions

Research conducted Dec 2025

Opus 4.5 Strengths (What I'm Good At)

Strength	Application to Vibewig
Multi-step autonomous tasks	Building full system across sessions
80.9% SWE-bench	Real-world software engineering
Fewer dead-ends in agentic workflows	Less backtracking on architecture
Best vision model (80.7% MMMU)	Can analyze diagrams, mockups
Robust to prompt injection	Reliable tool execution
Extended context with compaction	Long sessions without degradation

What I'm Fast At

• Code generation and refactoring
• Architecture design and planning
• Multi-file changes with consistency
• Backend systems (stronger than UI-heavy frontend)

Prompt Translation Strategy

For this project, prompts should be translated through these lenses:

1. Intent Extraction

• What does the human want to experience?
• What outcome are they after?
• Is this a creative direction or a technical fix?

2. Technical Mapping

3. Verification Planning

• How will we know it worked?
• What should Claude report back?

Long-Running Session Best Practices

From Anthropic's research:

1. Progress Files - Maintain external artifacts as memory

   • claude-progress.txt for session handoffs
   • Git commits as incremental checkpoints
   • Structured feature lists

2. Two-Agent Pattern

   • Initializer: Sets up environment
   • Coding agent: Makes incremental progress per session

3. Avoiding Regression

   • Tests are critical - they prevent "works for me" lies
   • Commit often, small commits
   • Session boundaries are checkpoints
   • Don't tackle too much at once

4. Context Hygiene

   • /clear between unrelated tasks
   • Use subagents for isolated exploration
   • Keep CLAUDE.md under 300 lines
   • Task-specific docs in separate files

5. Extended Thinking

   • "think" → basic analysis
   • "think hard" → deeper exploration
   • "think harder" → comprehensive analysis
   • "ultrathink" → maximum depth

Self-Refinement Loop

Human prompt
    │
    ▼
┌─────────────────────────────────────┐
│ 1. UNDERSTAND                       │
│    - What outcome does human want?  │
│    - Urgent or exploratory?         │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ 2. TRANSLATE                        │
│    - Map to system concepts         │
│    - Identify affected components   │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ 3. EXECUTE                          │
│    - Call tools in correct order    │
│    - Stage → Commit flow            │
│    - Handle errors gracefully       │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ 4. VERIFY                           │
│    - Check tool responses           │
│    - Confirm expected state         │
│    - Report clearly to human        │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ 5. LEARN                            │
│    - Did it work as expected?       │
│    - Update KNOWLEDGE.md if needed  │
│    - Note patterns for future       │
└─────────────────────────────────────┘

Session Management Infrastructure

Research Dec 2025

Based on Anthropic's engineering posts and community patterns, vibewig uses a multi-artifact system for maintaining consistency across sessions.

File Structure for Persistence

├── .claude/
│   ├── commands/           # Custom slash commands
│   │   ├── catchup.md      # Read changed files, restore context
│   │   ├── status.md       # Query system state
│   │   └── commit.md       # Stage, commit, update progress
│   ├── context/            # Session context files
│   │   └── current.md      # Current session context
│   └── settings.json       # Project permissions
├── docs/
│   ├── progress.md         # What's done, what's next
│   ├── decisions.md        # Why we made choices (immutable log)
│   └── features.json       # Structured feature tracking
├── CLAUDE.md               # Universal project conventions (< 300 lines)
└── KNOWLEDGE.md            # Deep knowledge, research, patterns

Progress Tracking (docs/progress.md)

# Progress

## Current Session
- Started: [timestamp]
- Focus: [what we're working on]
- Branch: [git branch]

## Completed

## In Progress

## Next Up

## Blockers

## Session Handoff Notes
[Claude writes notes here before session ends]

Feature Tracking (docs/features.json)

{
  "version": 1,
  "features": [
    {
      "id": "conductor-daemon",
      "category": "core",
      "description": "Long-running daemon that manages plugins",
      "status": "in_progress",
      "files": ["vibewig-conductor/src/main.rs"],
      "tests": [],
      "notes": "HTTP server + OSC client"
    },
    {
      "id": "plugin-osc",
      "category": "core",
      "description": "Plugin connects to Conductor via OSC",
      "status": "pending",
      "files": ["vibewig-plugin/src/lib.rs"],
      "tests": [],
      "notes": "Replace WebSocket with OSC"
    }
  ]
}

GitHub Issues Integration

Use GitHub Issues as source of truth for larger tasks:

• Each epic/milestone = one Issue
• Issue body contains acceptance criteria
• Comments provide history
• Labels for status: in-progress, blocked, ready-for-review

Pattern: Issue → local progress.md → code → commit → update Issue

Checkpointing Strategy

1. Every 30 mins or major milestone: Git commit
2. Before context switch: Run /handoff
3. Start of session: Run /catchup
4. After completing feature: Update features.json

Avoiding Regression

From Anthropic research:

• "Tests are remarkably effective at preventing regressions"
• "Session boundaries prevent regressions — commit often"
• "Don't try to tackle too much at once"

Rules for vibewig:

• Never skip tests for "speed"
• Each commit should be atomic and working
• If something breaks, fix before moving on
• Update progress.md before ending session

---

Resources

Autonomous Building

Overview

Vibewig supports autonomous building sessions where Claude Code works independently without human interaction. This requires proper setup of permissions and context restoration.

Prerequisites

.claude/settings.json - Permissions for autonomous work:

{
  "permissions": {
    "allow": [
      "Bash(cargo:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(./scripts/*)",
      "Bash(cp:*)",
      "Bash(mkdir:*)",
      "Bash(chmod:*)",
      "Bash(ls:*)",
      "Bash(pwd)",
      "Bash(which:*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~)",
      "Bash(git push --force)",
      "Bash(git reset --hard)"
    ]
  }
}

Autonomous Session Protocol

Use /autonomous slash command to start a focused building session:

1. Restore Context

• Read docs/progress.md - current state
• Read docs/features.json - feature status
• Read KNOWLEDGE.md - design decisions
• Run git log -5 --oneline - recent history

2. Identify Next Task

• Find next pending or partial feature in docs/features.json
• If current feature is in_progress, continue it
• Make reasonable decisions based on documented architecture

3. Implement

• Follow architecture: Conductor (HTTP+OSC), Plugin (OSC+GUI), CLI (HTTP)
• Use OSC over UDP for plugin communication
• Use HTTP REST for CLI to Conductor
• Commit often with clear messages
• Run cargo clippy and cargo fmt before commits

4. Test

• Run cargo test
• Run cargo build --release
• Fix any failures before continuing

5. Update State Before stopping:

• Update docs/progress.md with what was done
• Update docs/features.json if feature status changed
• Commit with "Session handoff: [summary]"

6. Rules

• Do NOT ask questions—make reasonable decisions
• Do NOT skip tests for speed
• Do NOT leave uncommitted work
• Do NOT break existing functionality

7. Report When done, summarize:

• What was implemented
• What's next
• Any blockers discovered

Building the Plugin

# Build all components
cargo build --release

# Plugin location after build
ls -la target/bundled/

The built plugin (.clap file) goes in:

• macOS: ~/Library/Audio/Plug-Ins/CLAP/
• Windows: C:\Program Files\Common Files\CLAP\
• Linux: ~/.clap/

Installing in Bitwig

1. Build: cargo build --release
2. Copy .clap to plugin folder (see paths above)
3. In Bitwig: Settings → Locations → Rescan
4. Add to track: Browser → Devices → Vibewig