Claude Code

Claude Code is the primary agent Viewport ships with. The adapter is built into the daemon. No separate install.

How it's wired

1. The daemon ships with a Claude Code hook installer.
2. vpd install writes the hook into ~/.claude/hooks/ so every claude invocation announces itself to your local daemon.
3. The hook posts session events (start, tool calls, transcript chunks, end) over a local Unix socket to vpd.
4. The daemon translates those events into the Viewport wire protocol and ships them to the relay.

Install the hook

If you ran vpd setup in the quickstart, it ran vpd install for you. If not:

vpd install

You should see:

[+] claude-code found at /usr/local/bin/claude
[+] Installing Claude Code hook... installed at ~/.claude/hooks/viewport.json

Verify the hook is firing:

cd ~/code/some-repo
claude --message "what's in this repo"

In another terminal:

vpd logs --follow

You should see session-started, then session-update frames as Claude works, then session-ended.

Plan template

When you have a workflow node that requires a plan review, the agent runs a plan-then-execute loop:

1. The agent reads your prompt.
2. Instead of acting, it generates a structured plan and posts it to the platform.
3. You review.
4. On approve, the agent executes the plan.
5. On deny or revisions requested, the agent stops or re-plans.

Viewport ships a default plan template for Claude Code that produces:

• A one-paragraph goal.
• 3-6 numbered steps.
• File list (predicted touch set).
• Risk callouts.
• Test/verification plan.

Override the template per-workflow in .viewport/workflows/your-workflow.yaml:

plan_template: ./prompts/migration-plan.md

See Reference: Workflow YAML.

Permission gates

Claude Code already supports per-tool permission prompts. Viewport intercepts the permission-request event and surfaces it as an inbox approval gate. The agent stays paused at the original prompt until the inbox decision resolves; then the agent receives the resolution and continues or stops.

The flow:

claude  ─►  hooks/viewport.json  ─►  vpd
                                       │
                                       ▼
                                  ws-frame: permission-request
                                       │
                                       ▼
                                  relay  ─►  platform  ─►  inbox item
                                                              │
       ┌──────────────────── you approve ──────────────────┘
       ▼
   inbox: resolved
       │
       ▼
   vpd  ─►  hooks/viewport.json  ─►  claude  → continues

Cost and token usage

Token usage frames come from Claude Code's usage events. The daemon aggregates them per session and reports rolling totals over the WebSocket. In the web app, each session row shows live token spend.

You can cap session cost in the workflow:

execution:
  cost_cap_usd: 5

When the cap is hit, the agent pauses and surfaces an inbox approval gate to extend or stop.

What's not yet implemented

• Sub-agent visibility. Claude Code's sub-agents emit nested sessions today but are flattened in Viewport's UI. A nested-session view is on the roadmap.
• Custom tool registration UI. Custom tools work via Claude Code's normal config; Viewport doesn't yet expose a UI to register them.

Where to go next

• Quickstart. Install + pair if you haven't.
• Concepts: Sessions. What's on the wire.
• Concepts: Plans. The plan artifact.
• Reference: Workflow YAML. Every field.