# ViziProof

**Review what your coding agent delivered — with the brief, evidence, and exact commit in one place.**

[Try the browser demo](https://caiohenriqu123-art.github.io/viziproof/) · [Português](README.pt-BR.md) · [Connect an agent](docs/MCP.md) · [Contribute](CONTRIBUTING.md)

![ViziProof delivery board](docs/assets/board-light.png)

An agent saying “done” is the start of a review. ViziProof is a small, local-first kanban that gives that review a home. Define acceptance criteria, collect reported evidence, fetch GitHub checks for a commit, and record your decision.

## A reviewable handoff

1. **Brief:** write the outcome and acceptance criteria.
2. **Delivery:** your agent submits a summary, remaining work, evidence, and an optional commit SHA through MCP.
3. **Review:** inspect the results and approve or request changes in the local interface.

Attach a GitHub commit to tie a decision to the exact code reviewed. On an explicit sync, ViziProof fetches checks and commit statuses directly from GitHub. If a tracked branch has advanced, or a check has started failing, an existing approval returns to review. Earlier decisions and delivery snapshots remain in the history.

**Reported is not verified.** Manually attached evidence stays labeled as reported. GitHub results show their source and fetch time; they are a snapshot of what GitHub reported, not an independent execution of the tests. No continuous monitoring is implied.

## Try it

The [browser demo](https://caiohenriqu123-art.github.io/viziproof/) runs without an account or server. Edits stay in browser storage. It uses fictional tasks and illustrative evidence, and does not connect to an agent or fetch GitHub results. Click **Try a review** for a guided walkthrough.

[Watch the recorded review walkthrough](docs/assets/walkthrough.webm).

## Run locally

Requires **Node.js 22.16+** and npm. Node.js 24 LTS is recommended.

```sh
git clone https://github.com/caiohenriqu123-art/viziproof.git
cd viziproof
npm ci
npm run build
npm start
```

Open **http://127.0.0.1:4173**. Your workspace starts empty and is stored in `.data/board.sqlite`.

To explore sample tasks instead:

```sh
npm run demo
```

The sample workspace uses a separate `.data/demo.sqlite` database. Stop one server before starting another on the same port. Re-running the demo preserves your edits.

To choose a database:

```sh
npm start -- --data /absolute/path/my-board.sqlite
```

No external database, cloud account, or AI API key is required. See [operation and backups](docs/OPERATIONS.md).

## Connect your agent

The local MCP server uses stdio and shares the SQLite file with the app. Configure the agent to run:

```sh
node /absolute/path/viziproof/dist-server/server/cli.js --mcp --data /absolute/path/viziproof/.data/board.sqlite
```

It exposes `list_tasks`, `get_task`, `create_task`, `move_task`, `add_evidence`, `submit_delivery`, and `sync_github`. There is no MCP approval tool. See the [configuration example, workflow, and conflict handling](docs/MCP.md).

## Why this exists

ViziProof focuses on the handoff between coding and review. It does not launch agents, create worktrees, or replace a code-review tool. The useful unit is a delivery with a clear brief, supporting evidence, and a decision linked to the reviewed code.

- Local SQLite storage shared by the UI and MCP processes.
- Version checks prevent stale writes from silently replacing newer work.
- Superseded evidence and delivery snapshots remain inspectable.
- Optional GitHub snapshots for an exact commit and tracked branch.
- Markdown export of the brief, evidence, decisions, and history.
- Responsive interface, keyboard-accessible controls, light and dark themes.

![Review a delivery](docs/assets/review.png)

## Scope and trust

This is an early **single-user local app**, not a hosted multi-user service. It binds to loopback and has no account system. “Human review” describes the intended workflow, not verified identity or a security boundary against another process on your computer. Anyone with local database/API access is trusted. Do not expose the server to the public internet.

GitHub sync is explicit. It sends the attached repository, SHA and optional branch to `api.github.com`; task descriptions and reported evidence are not sent. Public repositories work without a token, subject to GitHub limits. An optional `VIZIPROOF_GITHUB_TOKEN` is read only by the local server/MCP process. It is never stored in a task or sent to the browser. Private repository results, if fetched, become part of your local ledger and its exports.

See [security and privacy](SECURITY.md), [architecture](docs/ARCHITECTURE.md), and [roadmap](docs/ROADMAP.md).

## Development

```sh
npm ci
npm run dev
```

The development command starts the API on 4173 and Vite on 4174. Open **http://127.0.0.1:4174**. It uses the regular local database; use a dedicated `VIZIPROOF_DB` path for disposable development data.

```sh
npm run check
npx playwright install chromium
npm run test:e2e
```

`check` includes strict TypeScript, ESLint, formatting, domain/API/MCP tests, and builds. Browser tests cover the review workflow, persistence, export, keyboard focus, automated accessibility checks, mobile layout, and themes. CI runs installation and core checks on Linux and Windows, with browser checks on Linux.

## Contributing

Small, focused contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), describe the problem before proposing a large feature, and include the relevant validation. Useful next areas include localization, evidence attachments, and more MCP-client setup examples.

## License

[MIT](LICENSE). Bundled dependencies and fonts retain their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).