Skip to content

GUIDE.md

Latest commit

 

History

History
234 lines (184 loc) · 4.86 KB

GUIDE.md

File metadata and controls

234 lines (184 loc) · 4.86 KB
Raw

OpenCode Optimisation Guide

Complete system for running OpenCode efficiently: persistent state, adaptive routing, token savings, interruption survival.

Architecture

Human
↓
Laptop (orchestrator)
↓
SYSTEM/ (persistent memory)
↓
Adaptive routing engine
↓
Agents (specialized)
↓
SSH
↓
PC (heavy compute)
↓
Verification
↓
Compression
↓
Savepoint
↓
Resume

Core Principles

  1. Runtime first - prove stability before adding features
  2. Persistent state - never restart from zero
  3. Adaptive routing - cheapest model that solves the task
  4. Token efficiency - track and minimize every session
  5. Interruption survival - resume > restart
  6. Evidence over reasoning - test before thinking longer

File Structure

SYSTEM/
├── STATE.md              # Current status, blockers, next action
├── QUEUE.md              # Task queue with priorities
├── BLOCKERS.md           # Active failures and workarounds
├── DECISIONS.md          # Architectural choices with rationale
├── TEST_RESULTS.md       # Runtime stability proofs
├── ARCHITECTURE.md       # System design and component map
├── TOKEN_SAVINGS.md      # Token optimization tracking
├── SAVEPOINTS/           # Session checkpoints
│   └── YYYYMMDD_HHMM.md
└── MEMORY/
    ├── PERMANENT_MEMORY.md   # Improvement principles
    ├── LEARNED_PATTERNS.md   # Successful patterns
    └── FAILURES.md           # Failure records

How It Works

Session Start

  1. Read SYSTEM/STATE.md
  2. Check SYSTEM/BLOCKERS.md
  3. Resume from last savepoint
  4. Execute next queued task

During Session

  1. Use tools before reasoning (grep > logs > tests > think)
  2. Mark outputs: VERIFIED / ASSUMED / SPECULATIVE
  3. Append token savings after each optimization
  4. Create savepoint at milestones

Session End

  1. Update STATE.md with final status
  2. Compress if context grew large
  3. Create savepoint
  4. Update QUEUE.md

Adaptive Routing

Task
↓
Can tools solve it? → Yes → Use tools
↓ No
Cheapest model? → Yes → Use cheap model
↓ No
Verified? → Yes → Done
↓ No
Escalate → medium → strong → human

Decision output per task:

VERIFIED:
ASSUMED:
RISK:
CHEAPEST_MODEL:
NEXT_ACTION:
SAVEPOINT:

Token Optimization

Rules

  • No preamble, no postamble
  • Code > prose
  • Batch edits
  • Read only what's needed
  • Compress periodically
  • Track savings in TOKEN_SAVINGS.md

Savings Tracking

Format: Date | Action | ~Tokens saved | Method

Track:

  • One-time savings
  • Per-session recurring savings
  • Cumulative total

Runtime Configuration

opencode.jsonc

  • Model: opencode/qwen3.6-plus-free (free)
  • Auto-compaction: enabled
  • Prune: enabled
  • Tail turns: 2
  • Format: --format json for non-interactive

AGENTS.md

  • Behavior constraints
  • Token tracking requirements
  • Context handling rules

Phases

Phase 0: Runtime Proof (CRITICAL)

Tests:

  • Cold start
  • Long session (>1h)
  • Interruption recovery
  • SSH reconnect
  • Model failover
  • Multiple agents
  • Context compaction
  • Memory file update/reload

Output: SYSTEM/TEST_RESULTS.md

Phase 1: Persistent Layer (DONE)

  • SYSTEM/ directory structure
  • All persistent files
  • Savepoint system

Phase 2: Adaptive Routing (PLANNED)

  • Replace hardcoded model mapping
  • Decision engine per task
  • Escalation logic

Phase 3: Distributed Compute (PLANNED)

  • Laptop = orchestrator
  • PC = heavy compute
  • SSH connection

Phase 4: Agent Multiplication (PLANNED)

  • Explorer, Builder, Verifier, Compressor, Archivist, Coordinator

Phase 5: Self-Optimization (PLANNED)

  • Periodic review of waste
  • Compression
  • Deletion of obsolete

Phase 6: Failure Survival (PLANNED)

  • Crash recovery
  • Disconnect handling
  • Config corruption protection

Current Status

  • Runtime: 6 OpenCode instances running
  • Model: qwen3.6-plus-free (free)
  • Cost: 0
  • Phase: 0 (Runtime Proof)
  • Blockers: B001-B004 active
  • Token savings: ~2800 + ~300/session

Blockers

  • B001: opencode run without --format json hangs (HIGH) - WORKAROUND: use --format json
  • B002: opencode debug config times out (MEDIUM) - WORKAROUND: use debug startup/paths
  • B003: Snap package TTY confinement (MEDIUM) - INVESTIGATING
  • B004: Runtime reliability not conclusively verified (CRITICAL) - ACTIVE

Usage

  1. Clone this repo
  2. Copy SYSTEM/ to your project root
  3. Copy AGENTS.md to project root
  4. Copy opencode.jsonc to ~/.config/opencode/
  5. Start OpenCode
  6. Read SYSTEM/STATE.md before each session
  7. Follow the workflow

Notes

  • This is a living system - update files as you learn
  • Compression is required - don't let files grow unbounded
  • Failures are information - record them in MEMORY/FAILURES.md
  • Improvement includes subtraction - remove what doesn't work
  • Assume interruptions occur - maintain resume capability