Skip to content

quickstart.md

Latest commit

 

History

History
99 lines (69 loc) · 5.48 KB

quickstart.md

File metadata and controls

99 lines (69 loc) · 5.48 KB
Raw

Relo quickstart (Linux)

1. Install

Needs Go (version in core/go.mod), Node.js 20+, VS Code, and opencode 2.x on PATH.

make dev        # builds core, packages .vsix, installs into VS Code

Without the VS Code CLI, make vsix only builds extension/relo-code-<ver>.vsix. Install it manually with code --install-extension extension/relo-code-0.1.0.vsix --force.

2. Check the environment

make preflight  # or: sh scripts/doctor.sh   (read-only, never restarts OpenCode)

Exit code is non-zero only on hard failures (Go, Node, OpenCode, extension missing).

3. Open a folder and run Relo

  1. code /path/to/project, then reload the window (Ctrl+Shift+P, "Developer: Reload Window").
  2. Ctrl+Shift+P, then pick a command starting with Relo:, e.g. Relo: Open, Relo: New Session, Relo: Run Task, Relo: Plan Task, Relo: Review Changes, Relo: Open Logs.
  3. Ctrl+Shift+. (or Cmd+Shift+. on macOS) opens the Relo view.

4. Configure models

Settings (Ctrl+,, search relo.):

  • relo.primaryModel, relo.tier1Model, relo.tier2Model (format provider/model). Tier 2 is the cheap one: trivial and easy tasks and probes go there, medium, complex and hard tasks to Tier 1, expert tasks to the Primary model.
  • relo.routing.byDifficulty (advanced mode: one model per level trivial|easy|medium|complex|hard|expert; complex falls back to the hard model when unset), relo.routing.escalate
  • Token saving: relo.efficiency.preset (Saving level: off|auto|max), relo.efficiency.voice (Reply brevity), relo.efficiency.craft (Minimal code)
  • relo.runtime (opencode or mock), relo.openCode.path
  • relo.claudeCode.enabled, relo.claudeCode.path: run agents on your installed Claude Code CLI (below)

Pick models with Relo: Select Primary Model / Select Tier 1 Model / Select Tier 2 Model, or in Settings, Models.

Relo runs its own private OpenCode, separate from any OpenCode you have installed. It does not read your OpenCode config, sessions or logins, and OpenCode's built-in providers are switched off. The only models you see are the ones you add under Settings, Providers (an OpenAI- or Anthropic-compatible endpoint plus an API key). Relo keeps OpenCode's state in ~/.config/relo-code/opencode. Your own OpenCode is never touched.

Each model in the provider form has an Images setting: Auto, Sees images, or Text only. Auto uses what the endpoint reports, or a guess from the model id, which the model pickers mark as "guessed from the name". Set it for the models you use for UI work. Agents on a model that sees can view screenshots and reference images with relo_image, and tasks the Primary marks as visual go to such a model. See vision.md.

Each model also has an API setting, for a router that serves both APIs at one URL. Claude reached in the OpenAI format loses its thinking between tool steps: the format cannot carry the thinking's signature, so the router drops it and Claude works its plan out again from nothing on every step (40-60k output tokens and 4-7 minutes per step at xhigh). Setting the model to Anthropic API ("kind": "anthropic" on the model in relo.providers) keeps the thinking, where the router passes Anthropic's format through unchanged, as it does for an Anthropic API key.

Not with 9router on a Claude subscription login: 9router renames every tool there (shell to shell_ide) and, in 9router 0.5.104, does not rename them back when it streams Anthropic's format, so every tool call fails. Keep such models on the OpenAI format and give them efforts ("efforts": ["low", "medium", "high"]) and a level in relo.models.efforts: the router's own default (9router's thinking setting, often xhigh) applies only when a request names no effort. OpenCode does not send a none level, so thinking can be lowered this way, not turned off.

To run Claude with its thinking kept, use Claude Code instead: install and sign in to the claude CLI, turn on relo.claudeCode.enabled (Settings, Claude Code), and pick claude-code/... models for any role. Relo runs one CLI per agent with Relo's prompt and only the role's tools, on the CLI's own sign-in and plan limits. On a test task that was half the tokens of Claude Code's own defaults. See claude-code.md.

5. Zero-cost smoke test

Add a provider that costs nothing (a local server such as Ollama or LM Studio works), pick its model for Primary, Tier 1 and Tier 2, then run Relo: New Session and send a small task.

To test against OpenCode's own free models instead, set the environment variable RELO_SHARE_OPENCODE=1 before starting VS Code. That turns isolation off: Relo then uses your normal OpenCode setup and its full model catalog. This is for development only.

6. UI-only testing (mock runtime)

No OpenCode, no model calls:

  • Settings: relo.runtime = mock, or
  • Launch config Run Extension (mock runtime) (F5), or
  • RELO_RUNTIME=mock code ., or core flag -runtime mock.

7. Logs

  • VS Code: Relo: Open Logs (Output channel named "Relo"). Core logs go to stderr, shown there.
  • Core run standalone: extension/bin/relo-core-linux-amd64 -workspace . -log-level debug.
  • Workspace state: <workspace>/.relo/relo.db.

8. Develop

  • F5 Run Extension builds core, extension and webview first (make build).
  • make test, make lint, sh scripts/check.sh before committing.

9. Report issues

Open an issue with: sh scripts/doctor.sh output, the "Relo" output channel log, OS, and steps to reproduce. Remove API keys before posting.