# Getting Started

GoodVibes Agent is the installable `1.0.x` personal operator assistant TUI for GoodVibes.

## Requirements

- Bun `1.3.10` or newer.
- A connected GoodVibes host compatible with the exact `@pellux/goodvibes-sdk@0.33.36` pin in `package.json`.
- Connected-host token/config state accepted by that host.

Agent does not launch or manage the connected host.

## Install From Package

```sh
bun add -g @pellux/goodvibes-agent
goodvibes-agent --help
goodvibes-agent
```

If `goodvibes-agent` is not on `PATH`:

```sh
export PATH="$(bun pm bin -g):$PATH"
goodvibes-agent --help
```

`goodvibes-agent` starts the interactive TUI. On a fresh Agent home, setup opens first. After setup is applied, the TUI opens directly into the Agent workspace.

## Run From Source

```sh
git clone https://github.com/mgd34msu/goodvibes-agent.git
cd goodvibes-agent
bun install
bun run dev
```

## First Run

Use the interactive workspace first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable mirrors.

Primary first-run areas:

- Setup: provider/model, connected-host compatibility, Agent Knowledge readiness, profiles, support bundles, subscriptions, and auth review.
- Home: normal chat, operator briefing, model selection, and health.
- Knowledge: isolated Agent Knowledge status, ask/search, inspection, and confirmed ingest.
- Memory & Skills: local memory, notes, personas, skills, routines, and learned behavior capture.
- Channels: companion pairing, channel readiness, notification targets, and confirmed sends.
- Voice & Media: TTS setup, image input, and confirmed generated media.
- Work & Automation: work-plan tracking, approvals, schedules, reminders, and explicit operator actions.

Press `/` inside the Agent workspace to search actions by name, category, command, or detail.

## Model Access

The main Agent model can use the same user-facing harness through Agent-owned tools. Use `agent_harness mode:"summary"` for a compact map, then drill into plural catalogs or single-item inspect modes.

Default discovery is intentionally compact:

- plural modes return ids, labels, counts, safe state, and route hints;
- singular modes return detailed policy and lookup metadata;
- `includeParameters:true` adds schemas, editor fields, model routes, parameter hints, release artifact data, redacted log tail, and detail that would be too large for normal discovery.

Common model routes:

| Need | Tool Or Mode |
| --- | --- |
| Workspace actions | `agent_harness workspace_actions`, `workspace_action`, `run_workspace_action` |
| Slash commands | `agent_harness commands`, `command`, `run_command` |
| Settings | `agent_harness settings`, `get_setting`, `set_setting`, `reset_setting` |
| Visible UI | `agent_harness panels`, `ui_surfaces`, `open_panel`, `open_ui_surface` |
| Keybindings | `agent_harness shortcuts`, `keybindings`, `keybinding`, `run_keybinding`, `set_keybinding` |
| Agent Knowledge | `agent_knowledge`, `agent_knowledge_ingest` |
| Local memory/notes/personas/skills/routines | `agent_local_registry` or confirmed workspace actions |
| Work plan | `agent_work_plan` |
| Channels, notifications, reminders, media | `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, `agent_media_generate` |
| Operator state/actions | `agent_operator_briefing`, `agent_operator_action`, `operator_methods` |
| Connected host/daemon posture | `service_posture`, `connected_host`, `connected_host_status`, `daemon`, `daemon_status` |

All effects require explicit user request and confirmation. Ambiguous lookup is refused with candidates.

## Isolated Agent Profiles

Use a separate Agent home for isolated local state:

```sh
GOODVIBES_AGENT_HOME=/path/to/agent-home goodvibes-agent
```

Use named Agent profiles from Agent Workspace -> Profiles. Scriptable equivalents:

```sh
goodvibes-agent profiles templates
goodvibes-agent profiles create household --template household --yes
goodvibes-agent profiles use household --yes
goodvibes-agent --agent-profile household
goodvibes-agent profiles templates export research ./research-starter.json --yes
goodvibes-agent profiles templates import ./research-starter.json --yes
```

Named profiles isolate Agent-local config, sessions, memory, notes, personas, skills, routines, and setup state. They do not start or isolate the connected host.

## Local Behavior

Memory, notes, personas, routines, and Agent skills are local to GoodVibes Agent. They do not write into default knowledge or other product segments.

Use the workspace first:

- Memory & Skills -> Create memory, Create note, or Capture learned behavior.
- Notes -> Create notes for source triage, temporary decisions, and operator handoff.
- Personas -> Create, inspect, activate, review, stale, or delete.
- Skills -> Create, enable/disable, review, bundle, or delete.
- Routines -> Create, start in chat, review receipts, or explicitly promote to a connected schedule.
- Work -> Add work item, review work plan, and update status.

Starting a routine records local usage and prints its steps in the main conversation. It does not start background automation. Promotion to a connected schedule is separate, explicit, confirmation-gated, and keeps Agent Knowledge isolated.

## Knowledge And Artifacts

Use Agent Workspace -> Knowledge for source-backed Agent Knowledge. The valid route family is:

```text
/api/goodvibes-agent/knowledge/*
```

Agent commands fail closed if the route is unavailable or a successful-looking response exposes default-scope metadata.

Use Agent Workspace -> Research for read-only web research and URL inspection. Research requests do not ingest sources. Use confirmed Agent Knowledge ingest actions when a reviewed source should become durable.

Use the Artifacts area and Voice & Media workspace for images, source files, generated media, and exported sessions. Generated media returns artifact ids and metadata, not inline base64.

## Connected Host

Start the owning GoodVibes host before using connected features. Agent expects:

```text
http://127.0.0.1:3421
```

Override for one launch:

```sh
goodvibes-agent --runtime-url http://host:port
```

Persistent shell/session override:

```sh
export GOODVIBES_AGENT_RUNTIME_URL=http://host:port
```

Host diagnostics:

- Agent Workspace -> Home -> Host compatibility
- Agent Workspace -> Home -> Doctor diagnostics
- Agent Workspace -> Home -> Review health
- `goodvibes-agent status --json`
- `goodvibes-agent doctor`
- `goodvibes-agent compat`

Model-visible diagnostics are `service_posture`, `service_endpoint`, `connected_host`, `connected_host_status`, `connected_host_capability`, `daemon`, and `daemon_status`. These are read-only and do not expose host lifecycle control.

## Current Product Notes

Agent uses the GoodVibes terminal shell, renderer, input, fullscreen workspace, command registry, and release foundation. The active policy is serial/proactive by default, blocks hidden Agent-owned job fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning Agent into a coding TUI.
