Imported from scaryrawr/vivi (AGENTS.md). Install upstream with npx skills add scaryrawr/vivi. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Vivi targets Windows, Linux, and macOS with one authoritative Zig backend and platform-native UX:

• backend/src/root.zig owns domain behavior and is the only production module allowed to import copilot_sdk.
• backend/src/c_api.zig adapts domain values to the stable C ABI in backend/include/vivi_backend.h; keep SDK, JSON-RPC, subprocess, and Zig-owned memory types out of this boundary.
• cli/src/main.zig imports vivi_backend directly.
• macos/ owns the SwiftUI/AppKit app and XCTest integration.
• windows/ documents the future WinUI 3 / Windows App SDK host.
• linux/ documents the future GNOME GTK 4 / libadwaita host.
• build.zig.zon is the sole SDK dependency pin. Build products belong in ignored .zig-cache/, zig-pkg/, zig-out/, or Xcode Derived Data.
• Vendored or derived third-party code must retain the applicable upstream license notice and document its exact source revision under third_party/.

Native hosts share domain semantics through the C ABI, not widgets or view models. Do not add speculative sessions, generic JSON bridges, daemons, shared UI abstractions, or empty executable targets.

Build, Test, and Development Commands

Use Zig 0.16.x and Xcode 26.6.

zig build                         # CLI, static library, C header/module map
zig build run -- --help           # narrow CLI smoke path
zig build test                    # Zig unit tests plus C ABI smoke test
zigdoc copilot_sdk.Client         # inspect the pinned SDK

The Xcode BuildViviBackend target invokes scripts/build-zig-for-xcode.sh. Future MSBuild and Meson projects should call zig build install-c-api rather than creating another Zig dependency graph.

xcodebuild -project macos/Vivi.xcodeproj -scheme Vivi \
  -configuration Debug -destination 'platform=macOS' \
  CODE_SIGNING_ALLOWED=NO test
./scripts/check.sh                 # full format, Zig, CLI, and Xcode checks

Concurrent worktrees build macOS apps with the same bundle identifier. Before live Dock or URL-handler verification, confirm the running Vivi executable comes from the current worktree; otherwise macOS can route activation to another agent's build.

Coding Style & Naming Conventions

Run zig fmt build.zig backend cli for Zig. Run xcrun swift-format format --in-place --recursive macos/Vivi macos/ViviTests for Swift. Preserve lowercase vivi for the CLI and capitalized Vivi for app/product names.

Testing Guidelines

Keep backend and SDK adaptation tests in Zig, ABI agreement in the C smoke test, and native binding/UX behavior in each platform's test framework. Default tests must not require Copilot credentials or a running Copilot CLI. Any C ABI change must update the header, Zig adapter, smoke test, and every implemented native binding together.

zig build test does not compile test blocks in every imported backend module. When changing backend/src/settings.zig or backend/src/session_store.zig, also run zig test directly on the changed module.

Version every persisted settings or session-shard schema change. Parse each supported older version explicitly, migrate it in memory, and test the next write/compaction. Do not rely on ignore_unknown_fields for forward compatibility because an older writer can discard new fields while compacting sibling shards.

C API cross-builds do not compile the CLI. For platform-specific clipboard or terminal-input changes, also cross-build the executable:

zig build -Dtarget=x86_64-linux-gnu --prefix zig-out/cli-linux
zig build -Dtarget=x86_64-windows-gnu --prefix zig-out/cli-windows

Use the Windows GNU target when cross-building from macOS without MSVC headers. These checks establish compilation, not live desktop behavior.

Release CLIs target glibc 2.17 on Linux and macOS 14.0 on Apple silicon. An explicit macOS target must pass both --sysroot and -Dmacos-sdk from xcrun --sdk macosx --show-sdk-path so Zig can find AppKit and SDK headers.

Commit & Pull Request Guidelines

No commit convention exists yet. Keep changes narrowly scoped and include the relevant command output in PR descriptions.

Every PR that changes user-visible CLI, TUI, or native app behavior must include a reviewer-facing demo in its description. Use a short GIF or video when the behavior changes over time. Use before-and-after screenshots when a static comparison is clearer. Exercise the built application through the same surface the user sees. Unit tests, terminal transcripts, and written claims do not replace the visual demo. If the host cannot capture or upload media, state the specific blocker in the PR description and do not present the PR as visually verified.

Never commit generated archives, caches, Derived Data, credentials, or a Copilot CLI binary.