guv docs
Setup

Docs

Install, configure, troubleshoot, and extend Guv on macOS or Linux.

Pick your setup to hide the parts that do not apply.

install agent

Coding agents

Guv runs a coding agent that you already installed and signed in to. Each Job goes to that agent. The agent keeps its own login, model, and permissions. Interactive setup detects available agents and asks which one Guv must use.

Pi default

Guv’s default Handler invokes your separately installed and authenticated pi. Pi runs a new process for each Job and exits when Job is done. Job input and output files live in a private temporary directory.

Claude Code supported

Claude Code keeps one session in a working directory that you choose, so context carries between Jobs.

Setup can add only the Guv result-tool permissions after approval. Guv does not select a model, built-in tools, or a general permission policy.

Install and set up

Run setup in your terminal. It explains pairing state and shows a QR only when Familiar App needs pairing. Guv supports macOS and Linux.

Homebrew or Linuxbrew

brew install familiar-ai/tap/guv
guv setup

Already installed? Run brew update and brew upgrade guv before guv setup. Setup shows the restart command and requests approval before it runs the command.

Direct archive

Take the asset matching your system from the tap releases. A direct archive does not install a service. 

mkdir -p "$HOME/.local/bin" "$HOME/.local/share/guv"
tar -xzf guv_Darwin_arm64.tar.gz -C "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
guv setup
guv run

Keep guv run open or use your process supervisor.

Setup requests a hidden token only when Guv needs pairing. It configures the selected Handler, explains the optional Guv support skill, and runs checks after an approved service restart.

State lives in ~/.config/guv. Set $XDG_CONFIG_HOME to move the whole config directory, or $GUV_HOME to move only this one. Your coding agent keeps its own login and settings where it always does.

Handlers

A Handler receives one Job and returns one validated Outcome. Guv currently ships with Handlers for Pi and Claude Code. Each packaged Handler declares the Guv configuration that it needs. Setup renders those questions and writes the selected Handler command. It also includes the TypeScript SDK. The daemon reads Handler configuration at startup. Restart the daemon after each configuration change. Use the Custom Handler guide to write your own Handler.

caution — not a sandbox

Install only Handlers, hooks, and plugins that you trust. They run on your machine with all your credentials. 

guv handler default
brew services restart guv
guv status
guv handler default
guv run

Switch to Claude Code

Claude Code must already be available to your account. Setup offers the current directory or a different path. Guv uses Claude Code Channels, and Claude needs Guv result-tool permissions to return replies, notes, and App Effects. Setup shows the exact Claude settings file and additions before it requests approval. Return to Pi with guv handler default. 

cd /path/to/working-directory
CLAUDE_HANDLER="$(brew --prefix)/bin/guv-handler-claude"
guv handler set-command --cwd "$PWD" -- "$CLAUDE_HANDLER"
brew services restart guv
guv status
cd /path/to/working-directory
CLAUDE_HANDLER="$HOME/.local/bin/guv-handler-claude"
guv handler set-command --cwd "$PWD" -- "$CLAUDE_HANDLER"
guv run

Write your own

Use the Custom Handler guide to install the SDK, write a Handler, and configure it.

Prove the first Job

Send Reply with exactly: Guv works from the app. Working means that the Job status is running. A notification does not automatically indicate a successful Job completion. Onboarding is complete only when the app shows Done and displays Guv works.

If the app reports Handler failed while guv status shows handler ok, the Handler is ready. Use the agent troubleshooting guide to diagnose the selected coding agent and find safe actions.

Troubleshooting

guv status prints one line per check. Find your line below. A line reading skipped until … means an earlier check failed, so fix that line first.

config MISSING Guv is installed but never paired. Run guv setup, then approve its QR or fallback code in Familiar App.
config INVALID guv.json exists but does not parse. Every later check reads skipped until config is valid. Stop Guv and contact Guv support. Setup does not overwrite malformed configuration.
api UNREACHABLE Guv could not get a healthy answer from Familiar API. The number in brackets is the HTTP status, or 0 when the request never completed. Check your connection, then Familiar API health.
api INVALID api_url The api_url in guv.json is not a usable URL. Run guv setup and approve the computer again.
api MISSING guv.json has no api_url. Run guv setup and approve the computer again.
auth FAILED Familiar API did not accept the Guv token, or the request never completed. Check your connection first. If the token is no longer accepted, run guv setup and approve the new Device Authorization in Familiar App.
auth INVALID guv_token The token in guv.json is malformed. Run guv setup and approve the computer again.
auth MISSING guv.json has no guv_token. Run guv setup and approve the computer again.
handler NOT RUNNING The daemon is up but the Handler process is not answering. Confirm the runtime is installed and logged in. For Homebrew, run brew services restart guv. For a direct archive, restart guv run.
handler INVALID The Handler configuration does not parse. Run guv setup to select and configure a Handler again.
daemon not running Run brew services start guv, or guv run in the foreground. Then guv logs.
401 during setup A Guv device authorization expires after ten minutes. Run guv setup again and approve the newly displayed code.

See the complete troubleshooting guide. A coding agent can start from the public llms.txt map or use the Guv support skill.

Familiar App messages

These come from Familiar App, not from guv status. Find the message the App showed you.

Too many incorrect computer codes Familiar accepts five wrong computer codes in ten minutes. Wait ten minutes, then enter the code again. Entering the same code again is not a wrong try.
Familiar needs re-pairing The App credential is no longer accepted, because a newer setup code replaced it. Get a new setup email, then paste that code in Settings under Reconnect Familiar. Guv keeps its own pairing, so do not run guv setup again.
Paste your setup code A new or restored phone shows this welcome screen. Familiar keeps the App credential on one device, so it is not in your iCloud backup and it does not transfer. Ask for a new setup email, then paste that code here. A restored phone returns to the same setup, and your Jobs stay.

Upgrade or remove

brew update && brew upgrade guv
brew services restart guv

To remove Guv, stop the Guv service. Then run brew uninstall guv. Guv never deletes your workspace.