Skip to content

Gald3r Longship -- the Agentic Focus Terminal

Longship is gald3r's interactive terminal UI: a full-screen, keyboard-driven "agentic focus terminal" you run in place of (or alongside) gald3r chat/gald3r run when you want a real conversational coding-agent surface instead of a scrolling REPL. The compiled binary is gald3r_longship; inside this repo its source is vendored as the gald3r_tui module (gald3r.ai/tui), integrated as part of the Go rewrite.

This page is written for someone using Longship, not building it -- see concepts.md for the ideas it shares with the rest of gald3r (CRASH, sessions, providers) and providers.md for provider setup, which Longship also depends on.

Launching it

Longship is not yet part of this repo's signed binary release pipeline (gald3r/gald3r-api ship signed binaries on every tagged release; Longship does not, yet -- an honest gap, not a hidden feature). Today you build it from source:

go build -o gald3r_longship ./gald3r_tui/cmd/gald3r_longship

Run from a clone of this repo (Go 1.26+; the module lives at gald3r_tui, package gald3r.ai/tui, already wired into this repo's go.work). That produces a gald3r_longship binary (gald3r_longship.exe on Windows) you can put on your PATH.

Before the interactive UI is useful you need at least one model provider configured:

gald3r_longship provider login <provider-id> -api-key <key>

(or pipe the key on stdin, or edit longship.config.json directly). Run gald3r_longship with no arguments after that -- it launches straight into the interactive UI, exactly the same as running gald3r_longship ui explicitly. Without a configured provider it fails fast with a clear message telling you to run provider login first, rather than opening to a UI that has nothing to talk to.

The interactive UI

What you get once it launches is a real conversational agent session, not a placeholder:

  • A scrolling conversation view with markdown and diff rendering for the agent's replies and tool output.
  • A permission/approval modal every time the agent wants to run a tool that needs your sign-off -- pass -skip-all at launch to auto-approve everything instead (useful for a sandboxed or CI-adjacent run, not recommended for anything touching real credentials).
  • A question modal for the cases where the agent needs to ask you something mid-turn rather than guessing.
  • Ctrl+P -- command palette (discoverable list of every action, including the ones below).
  • Ctrl+K -- model select: switch model/provider mid-session; the switch takes effect on the next turn, not retroactively.
  • Ctrl+G -- session select: jump between sessions for the current project without leaving the UI.
  • Ctrl+S -- settings, including an in-app OAuth login flow for providers that support it (xAI today), sharing the same credential store the provider CLI subcommand writes to.
  • Desktop notifications when the terminal loses focus, so a long-running turn does not go unnoticed.

Session state, provider credentials, and skills are all real and persisted -- nothing above is a mockup wired to fake data.

Key subcommands

Every subcommand accepts the same root flags (-workdir, -data-dir, -debug, -verbose, -backend-addr, -skip-all, -session, -continue) anywhere after the subcommand name.

Subcommand What it does
ui Launch the interactive terminal UI (the default with no subcommand given)
run One-shot, scriptable run: read a prompt, run one full agent turn cycle, print the result
acp Run a JSON-RPC Agent Client Protocol stdio server, so ACP hosts like Zed can embed Longship as an agent
provider login / logout / list -- manage model provider credentials
session list / show / rename / rm / new -- manage sessions
project info / list -- project-directory reporting and cross-project listing
catalog update -- refresh the model pricing/context-window catalog; discover -- probe a local inference server (Ollama, LM Studio, ...) and assess what it has loaded
usage Report estimated (or, where the provider reports it, actual) token usage/cost for a session
log -tail / -follow -- inspect Longship's own structured log
valk start / stop / status / ask / inquire / messages -- the Valkyrie world_tree connector (see coordination.md)
dashboard Live per-lane terminal dashboard over a local gald3r autopilot loop run's durable events ledger -- the free-tier visualizer, no world_tree required
schema Emit the configuration document's JSON Schema
version Print version/build information (-json for machine output)
backend Shared multi-client backend mode -- not yet implemented

A few worth seeing in more detail:

run with output formats -- -format text (default, final message only), -format json (full machine-consumable result), or -format stream-json (NDJSON, one event per line, in gald3r's canonical kernel/protocol event schema) for piping into another tool:

gald3r_longship run "explain what this repo does" -format json

One-shot mode has no terminal to prompt for approval, so it denies any tool call that would need one unless you pass -skip-all.

session list shows every session for the current working directory:

gald3r_longship session list

valk mirrors the gald3r valk surface for Longship's own process -- useful when you want Longship's agent runs visible to the same world_tree coordination layer your other gald3r tooling uses.

dashboard is the free-tier "swarm observability" visualizer (owner ruling 2026-08-07: "a swarm must never run dark for hours"): it renders a gald3r autopilot loop run as a per-lane terminal dashboard read entirely from that run's local, durable events ledger (JSONL under .gald3r/logs/) -- no world_tree connection or login needed.

gald3r_longship dashboard                    # active/last-known run, one static snapshot
gald3r_longship dashboard -follow            # keep redrawing every 2s (Ctrl+C to stop)
gald3r_longship dashboard 20260822T153000     # replay a specific run by stamp/prefix
gald3r_longship dashboard /path/to/other.jsonl  # replay ANY ledger file, from anywhere
gald3r_longship dashboard -json               # machine-readable snapshot instead of text

Each lane's block shows its status (running/completed/failed/killed/planned/pending), the last ledger event, and -- when the run has emitted liveness_snapshot events for it -- how long ago each of the four liveness channels (db/worktree/events/stdout) last showed activity, plus the liveness watchdog's own countdown. A run with no run_end line yet renders "IN PROGRESS", never an error -- reading a still-writing ledger mid-flight is the expected, common case.

How Longship relates to the gald3r CLI

gald3r chat, gald3r run, and gald3r acp still exist in the gald3r CLI, but they are explicitly labeled reference executors: a minimal, headless fallback for scripting or for environments where Longship is not installed. Longship is the first-party, canonical execution plane -- it is where the rich interactive terminal experience lives.

Underneath, run, ui, and acp all build and drive the exact same agent turn loop: the same tool catalog, hook engine, approval gate, and model provider router, just with a different front end (one-shot printer, full interactive TUI, or ACP JSON-RPC framing). Nothing about Longship reimplements agent logic separately per subcommand.

What Longship deliberately does not own is project coordination -- tasks, bugs, workspace linking, and platform setup stay with the gald3r control-plane CLI. Longship is the execution surface; gald3r is where you manage the work Longship executes.

Current status -- what's not there yet

  • backend (shared multi-client mode) is a registered subcommand that prints "not yet implemented" and exits -- it is not a hidden or half-working feature, it genuinely does nothing yet.
  • version -check (self-update checking) is not implemented yet: there is no release-feed URL or signed-artifact distribution mechanism wired up, and the command says so rather than silently no-op'ing or hitting a made-up endpoint.
  • provider login only supports storing a static API key from this specific CLI verb. A real interactive OAuth flow exists, but only inside the TUI's settings screen (Ctrl+S, currently for xAI) -- a non-interactive login command has no natural place to send you to a browser, so it says so plainly instead of pretending.
  • No signed release yet. Unlike gald3r/gald3r-api, Longship has no binary attached to this repo's tagged releases today -- building from source (see "Launching it" above) is the only path.
  • -format stream-json-legacy exists alongside the canonical stream-json format specifically to keep byte-for-byte compatibility with an older consumer's event schema while that consumer migrates -- prefer plain stream-json for anything new.