Add a repo

The daemon won't pay attention to a directory until you tell it to. There are two reasons for that: it limits the scope of what gets observed, and it keeps the daemon's resource manifest deterministic for each repo.

Add a directory

vpd add ~/code/api

This persists the path into ~/.viewport/config.json under directories[] and POSTs the daemon's local API so the running daemon picks it up immediately. The daemon resolves the path, watches the repo's .viewport/ if present, and is ready to announce sessions started inside it.

List what's registered:

vpd list

Remove one:

vpd remove ~/code/api

What gets watched

The daemon watches for session hook events that agents fire when they start, emit tool calls, or end. It does not poll your filesystem. It does not index your code. It does not read files unless an agent's hook event references them.

Specifically:

• It watches for the local socket the agent's adapter posts to.
• It reads .viewport/config.yaml and .viewport/workflows/*.yaml at session start to resolve the resource manifest. Which contexts attach, which workflows apply, which plan templates are available.
• It does not stream file contents anywhere. Frames are metadata.

The resource manifest

At session start, the daemon resolves a deterministic manifest for the working directory. The manifest names:

• contexts to attach (read from the org's vault).
• workflows applicable in this scope.
• plans templates available.
• agentProfiles that apply.

Inspect the resolution:

vpd config resolve
vpd session manifest --session SID

If two configs collide (e.g., a worktree above two repos), the merged manifest surfaces the conflict explicitly. Nothing is silently chosen.

.viewport/ in your repo

The committed .viewport/ directory is optional but it's where you declare what makes this repo specific:

.viewport/
├── config.yaml          # context attachments, workflow visibility
├── workspace.yaml       # opt-in org hint (gitignored if private)
├── local.yaml           # gitignored: authoritative local binding
└── workflows/
    └── deploy.yaml      # workflow definitions

The workspace.yaml is a hint. It tells a teammate cloning the repo which org this is intended for. It cannot grant streaming. Streaming is granted only via the gitignored local.yaml written by vpd bind.

See Concepts: Workflows for the schema and Reference: Workflow YAML for every field.

Recursive trees

A common pattern: you keep all work repos under ~/code/. Bind the whole tree once.

vpd add ~/code --recursive

This watches every direct child of ~/code as its own directory. New repos you git clone under it are picked up the next time the daemon scans.

Common gotchas

• Adding a directory before pairing: works fine. The daemon stores the directory list. It just won't stream anything until you pair.
• Adding /: refused. The daemon enforces a minimum depth (default: 1 level under your home) to avoid scanning irrelevant trees.
• Permission errors: if the daemon can't read .viewport/config.yaml, it logs a clear warning to vpd logs and treats the directory as having no manifest. Sessions still announce; they just have no workflows/contexts attached.

Where to go next

• Decide from anywhere. The inbox flow.
• Concepts: Sessions. What a session is on the wire.
• Concepts: Workflows. The YAML contract.
• CLI: directories. Every flag for vpd add / vpd list / vpd remove.