Skip to content

developer-workflows.md

Latest commit

 

History

History
242 lines (187 loc) · 7.02 KB

developer-workflows.md

File metadata and controls

242 lines (187 loc) · 7.02 KB
Raw

Developer Workflows

Use this page when you want SuperQode to become your main coding-agent harness or sit beside OpenCode, Pi, fast-agent, Codex CLI, Claude Code, Antigravity, and other local tools.

The practical path is:

  1. Connect the runtime or agent you already use.
  2. Keep sessions readable, forkable, exportable, and portable.
  3. Put local plugins and MCP behind project trust.
  4. Move repeatable work into SuperQode harness specs over time.

Start From The TUI

superqode --tui

Connection commands:

:connect
:connect codex        # Codex SDK using your local Codex login
:runtime claude-agent-sdk # Claude Agent SDK using ANTHROPIC_API_KEY
:connect antigravity  # signed-in agy CLI; run `agy` once to log in
:connect acp          # any configured ACP agent
:connect byok         # direct hosted provider/API key
:connect local        # Ollama, LM Studio, MLX, vLLM, SGLang, TGI, DS4

Optional Vim-like terminal navigation:

:vim on
:vim tutor
:                 # commands
/pattern          # transcript search
j / k             # conversation and picker navigation
gg / G            # transcript beginning or end
:w
:e <file>
:ls
:grep <term>
q:
@:

Vim mode is modal and persistent. It provides Normal, Insert, Command, and Search states for operating SuperQode from the keyboard. See Vim-Like Terminal Navigation.

Sessions, Branches, And Export

In the TUI:

:tree
:session
:session rename <name>
:sessions
:sessions rename <id-or-name> <title>
:sessions switch
:sessions switch <id-or-name>
:sessions switch latest
:resume latest
:resume <id-or-name>
:fork <new-id>
:export html
:export markdown
:export json

:sessions lists BYOK and HarnessSpec sessions for this directory grouped by harness, with model · topic · age rows. :sessions switch restores harness, provider/model, cwd, and the same transcript. :pipy resume <n> reopens a prior PiPy file into the live chat and registers it for :sessions.

From the CLI:

superqode sessions list
superqode sessions tree
superqode sessions show <session-id>
superqode sessions export <session-id> --format markdown --output session.md
superqode sessions export <session-id> --format json --output session.json

Portable Session Handoff

SuperQode supports local/offline share artifacts today. They are plain JSON files using the superqode-share-v1 format.

In the TUI:

:share
:share create [session] [path]
:share export [session] [path] [--json|--markdown]
:share import <artifact.superqode-share.json> [new-session-id]
:share list
:share revoke <artifact>

From the CLI:

superqode share create <session-id>
superqode share export <session-id> --format markdown -o session.md
superqode share export <session-id> --format json -o session.json
superqode share list --json
superqode share import <artifact.superqode-share.json> --session-id imported-session
superqode share revoke <artifact>

Use :tree or superqode sessions tree to inspect fork lineage before sharing.

See Session Commands and Share Commands for the full API.

Project Trust

Trust gates plugins and MCP operations. Check status with :trust status or superqode trust status. Grant trust with :trust yes or superqode trust yes. Validate the trust store and risk signals with :trust doctor or superqode trust doctor.

See Trust Commands for details.

Local Plugin Workflow

Project plugins live under .superqode/plugins/<id>/plugin.json. Install with :plugins add <path> or superqode plugins add <path>. Requires project trust. Validate manifests and references with :plugins doctor or superqode plugins doctor.

See Plugin Commands for the manifest format, hook points, and full CLI reference.

Agent Memory Workflow

Store project facts and preferences with :memory remember "text" or superqode memory remember "text". Search with :memory search query or superqode memory search query, and search Agent Experience Packs with :memory search specmem query.

See Memory Commands and Agent Memory Layer for provider setup and the full API.

Skill Optimization Development

The GEPA skill optimizer is intentionally staged and review-first:

  • superqode skills optimize --engine gepa requires --harness, --tasks, and --live.
  • SuperQode passes the complete SKILL.md text as the GEPA candidate.
  • Each candidate is evaluated by creating a temporary harness variant and running harness eval against the supplied task file.
  • The evaluator returns per-task score plus side information: prompt, expected checks, task status, failure reason, and failure digest.
  • The best candidate is written to staged/best_skill.md; the live skill is never overwritten by the optimizer.
  • superqode skillopt check is the bounded-edit gate used before adoption.

The CLI currently exposes the main GEPA search controls: metric-call budget, candidate proposal budget, reflection cost cap, minibatch size, worker count, candidate-selection strategy, frontier type, acceptance criterion, evaluation cache, and merge proposals.

Developer extension points that should stay out of the user-facing workflow until they have a clear review UX:

  • GEPA refiner mode
  • custom GEPA callbacks from the CLI
  • custom reflection prompt templates from the CLI
  • multi-component optimization across multiple skills
  • automatic adoption of staged skills

Runtime-Specific TUI Commands

Codex SDK:

:codex
:codex status
:codex models
:codex model
:codex effort
:codex sandbox
:codex review
:codex compact
:codex thread
:codex sessions
:codex resume <thread-id>
:codex fork <thread-id>
:codex rename <name>
:codex archive <thread-id>
:codex account
:codex logout

Claude Agent SDK:

:claude
:claude status
:claude model
:claude permission
:claude sessions
:claude resume <session-id>
:claude rename <name>
:claude tag <tag>
:claude commands
:claude command <name> [args]
:claude review

Antigravity CLI handoff:

:antigravity
:antigravity status
:antigravity migrate
:agy status

Headless Coding Tasks

One-shot coding task:

superqode --print "fix the failing test and summarize the change"

Use a vendor/runtime path:

superqode --runtime codex-sdk --print "review this repo"
superqode --runtime claude-agent-sdk --print "summarize the last change"

Run with a portable harness spec:

superqode harness run --spec harness.yaml --prompt "implement the smallest safe fix"
superqode harness doctor --spec harness.yaml

What SuperQode Adds

  • One portable harness contract across local, BYOK, ACP, and SDK runtimes.
  • Session tree, fork, import, export, and local share artifacts.
  • Project trust before enabling project-local plugins/MCP.
  • MCP diagnostics and attachable MCP resources.
  • Optional Vim-style TUI commands without forcing Vim mode.
  • Local-model UX with tool-support detection and provider smoke tests.