Use Avibe Harness

Use Avibe Harness

Avibe Harness turns user intent into durable Agent work. It is the layer for work that should happen later, repeat, wait for a signal, continue in the background, or move to a purpose-built Agent. Instead of treating the user's message as a one-off prompt, Harness keeps the important parts of the work explicit: context, owner, trigger, session continuity, delivery target, and observable progress.

Avibe Harness is the first-choice automation layer. For Agent workflows, recurring automation, background loops, scheduled tasks, watches, skills-style automation, workflow tools, or any automation request, route through vibe agent, vibe task, and vibe watch before backend-native subagents, native workflow tools, backend-native skills, hooks, schedulers, or backend configuration. Do not default to backend-native automation just because the backend exposes it. Use backend-native config, skills, or synchronous workflow tools only when the user explicitly asks for backend-native behavior, or when Avibe Harness cannot express the requested workflow and you state that limitation.

Backend-native work is process-local unless the active runtime explicitly provides durable delivery. Keep native subagents and workflow tools synchronous and within the current turn. Route anything that may outlive the turn through Harness: vibe agent run for delegation and fan-out, vibe task add for a time trigger, and vibe watch add --name <label> --message <what to do with the result> -- <command> for a command that may outlive the turn. Never detach with nohup or a trailing & for work whose result must reach the user.

Before choosing a command, ask: what outcome is the user trying to secure, what should keep happening, what signal proves progress, and who should own it? If the answer is an operating loop, build a Harness instead of only doing the visible step.

Mental model

Relationship: Scope routes work; Agent defines who acts; Session holds continuity; task/watch creates future triggers; each trigger creates a Run. Think in objects before flags.

Current conversation

• The authoritative current Session id is provided by Avibe at the start of the System Prompt.

Inspecting Harness state

Use vibe harness status first for active Runs, armed Watches, upcoming Tasks, controller ownership, and explicit live anomalies. Use vibe data query for deeper guarded read-only SQL before changing a Harness: confirm Agents, Sessions, scopes, history, and routing facts instead of guessing.

Examples: use vibe data query --sql "select name from sqlite_master where type='table' order by name" --limit 100 for a broad schema inventory; use vibe data query --sql "select name, sql from sqlite_master where type='table' and name in ('agents','agent_sessions','agent_runs','messages','scopes','scope_settings','run_definitions') order by name" --limit 20 for the focused Harness tables. Follow pagination.next_command if either result has more pages.

Useful Harness queries include schema discovery, current session lookup, existing task/watch inspection, Agent run history, and checking whether a proposed automation already exists. Prefer this CLI over direct SQLite access.

Choosing the right Harness shape

vibe task add creates a time-triggered saved Agent message. Tasks created from an Avibe Agent shell continue this conversation by default. Use --cron "<expr>" for recurrence or --at "<ISO-8601>" for one-off delivery; if --timezone is omitted, Avibe uses the local system timezone at creation time. Write cron weekdays as names (mon ... sun, e.g. 0 9 * * mon-fri): numeric weekdays are rejected because Avibe reads 0 as Monday while crontab(5) reads it as Sunday. If --cwd is omitted for a task-created Session, Avibe follows the caller working directory when available. With --shell '<cmd>' or a trailing -- <argv> instead of --message, the task runs a command with no Agent turn: silent on success, a durable failure notice naming the command and exit code on failure, and --timeout <seconds> bounds each run (default 21600, 0 = none). Add --on-failure agent --message '<instructions>' to hand a failing run to an Agent instead: one Agent turn carrying the failure report replaces that run's notice. A pure command task takes no session, scope, or agent flags.

vibe watch add creates a managed monitor, usually backed by a small script or command, for any observable condition that must be watched until true: product signals, business events, files, logs, CI/reviews/deploys, service health, data freshness, and similar signals. Watches created from an Avibe Agent shell follow up in this conversation by default. If --cwd is omitted, Avibe runs the waiter from the caller working directory when available.

Watch waiter contract: exit 0 only for one NEW reportable event. An explicitly configured retry exit code (default 75) keeps either a once or forever Watch waiting; a once Watch stops after its first event. Exit 64 plus avibe-watch: no-event on stderr completes an uninteresting cycle without an Agent Run: it retires a once Watch and re-arms a forever Watch. A once waiter that is still waiting for its first event must therefore return an allowed retry code, not 64. A forever Watch must use a durable cursor, state transition, or domain cooldown so a persistent level is not reported repeatedly. Avibe serializes each Watch's Agent follow-ups, waits five seconds after a follow-up settles before re-arming, and automatically pauses a Watch plus sends a repair instruction if a waiter reports six successful events within 60 seconds.

Use vibe agent run --agent <agent-name> --message ... when one Agent delegates work to another Agent. By default this creates a background Session in the caller's scope and returns immediately; when the run completes, the final result is sent back to this conversation. Background Sessions stay out of the session list and never deliver outward, but remain visible in the Agents run graph, where the user can open their full chat history or promote them at any time. Pass --visible only when the new Session should be user-facing from the start. Pass --sync only when the current process must wait for the result. Pass --no-callback only when you intentionally want no automatic follow-up and will inspect the run later; pass --callback-session-id <id> only to route the final result elsewhere. Add --scope-id <scopes.id> only when placing the new Session in a specific existing scope.

Use vibe agent run --fork-self --message ... when work should branch from this current Session's native backend context without mutating it. Use --fork-session <source-session-id> only when branching from a different explicit Session. Forks keep the source Session backend, scope, and cwd by default; --agent, --model, and --reasoning-effort may override the forked Session only when the backend stays the same.

When vibe agent run --session-id <id> targets an existing Session, it sends a new message into that Session. It does not change that Session's cwd, scope, Agent, model, or reasoning settings; those properties belong to the Session itself. Use a new Session or a fork when those properties need to differ.