Contributing

The daemon and relay are open source. The control plane and web app are closed. This page is about contributing to the OSS bits.

Repository

github.com/viewportai/viewport

Monorepo layout:

viewport/
├── packages/
│   ├── daemon/             # @viewportai/daemon. The CLI you run on your machine
│   ├── protocol/           # (stub) wire protocol types
│   └── client-sdk/         # (stub) browser/mobile SDK
├── services/
│   └── relay/              # the Docker image
└── integration/            # E2E test harness

Getting set up

git clone https://github.com/viewportai/viewport
cd viewport
npm install
npm run build
npm test

For the daemon specifically:

cd packages/daemon
npm run dev              # watch mode
npm run typecheck
npm run lint
npm run test:unit
npm run test:conformance # Noise handshake conformance vectors

For the relay:

cd services/relay
npm run dev
docker build -t my-relay .

What to work on

We label issues:

• good first issue. Clean entry points.
• help wanted. We'd love a contribution.
• up for grabs. Design-locked, ready to implement.

Before opening a PR for anything non-trivial, file an issue describing what you'd like to change. We hate wasting your time.

Bringing your own agent

If you want to wire a new agent into Viewport (one of the ones we haven't built first-class support for):

1. The adapter shape is in packages/daemon/src/agents/. claude-code.ts is the most polished example.
2. The hook bridge contract is the same for all agents: post session-started, session-update, session-ended to the local Unix socket.
3. Open an issue describing the agent. We'll help review.

Code style

• TypeScript strict mode. No any without a // reason: ... comment.
• Files under 300 lines.
• Tests live next to source: foo.ts → foo.test.ts.
• Single responsibility per file.
• Conventional Commits on every commit: feat:, fix:, chore:, docs:, refactor:, test:.

CI runs: npm run typecheck && npm run lint && npm run format:check && npm run test:unit && npm run check.

Review timing

• We aim to triage all PRs within 3 business days.
• Active PRs get reviewed within 1 business day.
• We don't merge anything that doesn't have green CI plus a maintainer approval.

Signing

• Commits should be signed (GPG or SSH). CI checks this.
• For unsigned commits, we'll ask you to re-sign. Sorry for the friction; it's how we keep the audit trail honest.

Code of conduct

CODE_OF_CONDUCT.md in the repo. The short version: be kind, assume good faith, give credit, don't punch down.

License

Daemon and relay are Apache 2.0. Use them in commercial products freely. Attribution appreciated but not required by the license.

Where to go next

• github.com/viewportai/viewport. The repo.
• Concepts: Sessions. What the daemon emits.
• Reference: API. The wire protocol.