PARALLAX ENGINE

OpenCode plugin -- protocol enforcement, mode switching (plan/build/debug/horizon), structured reasoning traces, friction-loop verification, and autonomous long-horizon supervision.

Install

npx parallax-opencode

Restart OpenCode. The plugin hooks and tools are auto-loaded.

The plugin stores runtime state at ~/.parallax/ (plugin process runs from user home directory).

What It Does

Two Agent Modes

The plugin provides two agent tabs, switch between them with [Tab]:

PARALLAX AGENT -- Protocol Enforcement (6 steps)

The Parallax agent follows a structured reasoning protocol before writing code. The plugin enforces this via the tool.execute.before hook:

Mode Switching

Friction Loop

After every write, the plugin auto-runs project verification. On failure, it decrements a retry counter. After 3 consecutive failures, it blocks further writes until the issue is resolved.

Trace Recording

Every session produces a structured reasoning trace -- phases, writes, verification results. The AI can export it to JSON or generate a PR-ready markdown summary.

The 4 Invariants

Based on @acidgreenservers AGENTS.md

HORIZON AGENT -- Autonomous Long-Horizon Supervisor

The Horizon agent is a self-driving project supervisor for multi-hour/multi-day tasks. It plans, researches, executes, self-tests, and self-iterates until a goal is 100% complete without needing mid-execution user input.

Workflow

Self-Check Evaluation (6 Dimensions)

After every sub-agent, Horizon scores output across 6 weighted dimensions:

Pass threshold: >= 75% weighted score. Automatic retry on failure (up to 3 cycles).

Autonomous Decision Engine

When Horizon encounters ambiguity, it autonomously:

1. Identifies the ambiguity
2. Researches (web search, codebase, project conventions)
3. Decides using best-guess heuristics (preferring conservative defaults)
4. Documents the decision in decisions.jsonl for post-hoc review
5. Proceeds without blocking

Autonomy Levels

Plugin Tools

These are called by the AI in OpenCode chat:

Parallax Tools (9)

Horizon Tools (18)

Session Management

Plan Management

Feature/Milestone Tracking

Decision Audit

Research Cache

Session-Scoped Skills

Trace Archiving

Configuration

CLI (CI Only)

The parallax CLI is for CI pipelines and automation, not for interactive use:

parallax gate --min-score 70       # CI coherence gate (exit code 0/1)
parallax pre-commit                # Git pre-commit hook wrapper
parallax init                      # Create .parallax/ config dir
npx parallax-opencode              # Install the plugin (alias for init)

Architecture

Parallax Agent (system prompt)
  |
  +-- Plugin hooks (8)
  |     event                       --> session ID + agent switches
  |     tool.execute.before         --> protocol enforcement + friction + design doc gate
  |     tool.execute.after          --> auto-verify + trace recording + state persistence
  |     experimental.chat.system.transform --> protocol status + mode skill + agent context
  |     experimental.session.compacting     --> state preservation + trace export
  |     shell.env                   --> PARALLAX_MODE, PARALLAX_SESSION_ID in shell
  |
  +-- Parallax custom tools (9)
  |     parallax_verify, parallax_analyze, parallax_checkin,
  |     parallax_plan / _build / _debug,
  |     parallax_trace_export / _pr_comment / _view
  |
  +-- Horizon custom tools (18)
  |     horizon_init_session, horizon_list_sessions, horizon_session_status,
  |     horizon_write_plan, horizon_read_plan, horizon_write_state, horizon_read_state,
  |     horizon_update_feature, horizon_update_milestone,
  |     horizon_append_decision, horizon_read_decisions,
  |     horizon_write_research, horizon_read_research,
  |     horizon_create_skill, horizon_list_skills,
  |     horizon_save_trace,
  |     horizon_config,
  |     horizon_evaluate_subagent
  |
  +-- Parallax State (~/.parallax/)
  |     state.json                  protocol state (immediate on checkins)
  |     traces/                     per-session JSON traces
  |     scores.jsonl                append-only score history
  |     config.json                 per-project config (optional)
  |
  +-- Horizon State (~/.parallax/horizon/)
        config.json                global Horizon config
        index.json                 session UUID -> goal summaries
        sessions/<uuid>/
          plan.json                structured plan (milestones + features)
          state.json               orchestration state
          decisions.jsonl          auto-decision audit log
          research/
            findings.md            synthesized research summary
            sources.json           URL references with key excerpts
          skills/<name>/SKILL.md   session-scoped skills
          traces/                  sub-agent trace exports

Project Config

Create .parallax/config.json in your project root:

{
  "strictness": "standard",
  "minScore": 70,
  "designDocRequired": false,
  "trivialPatterns": ["*.md", "*.json"],
  "highRiskPatterns": ["**/auth/**", "**/*.env*"]
}

Source Layout

parallax_plugin/
  agents/
    parallax.md                   # Parallax agent definition
    horizon.md                    # Horizon agent definition
  src/
    plugin.ts                     # Plugin (~1900 lines, 27 tools)
    types.ts                      # Shared types (includes Horizon types)
    horizon.ts                    # Horizon persistence module (512 lines)
    detect.ts                     # Project detection
    trace.ts                      # Trace recording + export
    score.ts                      # Coherence score + analytics
    cli.ts                        # CLI (CI only)
    tests/
      trace.test.ts               # 6 tests
      protocol.test.ts            # 5 tests
      score.test.ts               # 5 tests
      detect.test.ts              # 7 tests
      friction.test.ts            # 7 tests
      horizon.test.ts             # 26 tests
  dist-standalone/                # Bundled plugin (~76KB)
  skills/
    parallax/                     # Parallax protocol skills
    parallax-plan/                # PLAN mode skill
    parallax-debug/               # DEBUG mode skill
    horizon/                      # Horizon autonomous supervisor skill
  scripts/
    install.mjs                   # Local install script
    publish.mjs                   # npm publish script

License

MIT (c) @Master0fFate