# Vinci Code CLI
The canonical public source and release lineage for Vinci Code, a terminal coding agent distributed from the MIT-licensed Pi harness.
Sign in with your Vinci account to start. Bring-your-own-provider use is available through `/other` and does not require a Vinci account. Managed inference is a separate service dependency. The private vinci-code repository contains operations and historical reference, not a second product publisher.
## Start here
[Installation](#installation) · [Quick start](#quick-start) · [Privacy](vinci/PRIVACY.md) · [Security reports](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Releases](#releases)
Preserve Pi provenance, the MIT grants and third-party notices. Code licensing does not grant the Vinci/SimpleDirect trademarks or separately governed artwork rights.
## Product and developer reference
A terminal coding agent with **Vinci account sign-in** and optional bring-your-own-provider
keys through `/other`.
Same guard rails either way.
[](https://nodejs.org)
[](LICENSE)
[](https://github.com/badlogic/pi-mono)
[](vinci/PRIVACY.md)
**Vinci Code is a distribution of [Pi](https://pi.dev)** — a thin fork of the
[Pi agent harness](https://github.com/badlogic/pi-mono) (MIT) by
[Mario Zechner](https://github.com/badlogic), maintained under
[SimpleDirect®](https://www.getsimpledirect.com) by Alpine Pacific Trading Inc. Pi's
package structure is retained; Vinci adds extensions and integration patches. Provenance, including the
exact upstream commit this forked from, is in [`UPSTREAM.md`](UPSTREAM.md).
That is one unedited turn on a **user's own key** — the header reads `Anthropic: Claude Haiku 4.5`
and `/login to connect`, because no Vinci account is involved. The capture ends with its final report of what was verified and what was not.
## How it fits together
```mermaid
flowchart LR
You["your terminal"] --> Guard
subgraph Local["on your machine — identical in both modes"]
direction LR
Guard[guard] --> Mask[secret redaction] --> Agent[agent loop]
Agent -.-> Receipts[("receipts checkpoints review")]
end
Agent -->|BYOK| Provider["your provider Anthropic · OpenAI · Google · Groq"]
Agent -->|Managed| Gateway["Vinci gateway"] --> Managed["a model Vinci selects"]
style Provider fill:#0A84FF,color:#fff
style Gateway fill:#6C3483,color:#fff
```
In **BYOK** your inference key and prompts go straight to your provider. Opening `/model`
can fetch Vinci's public model details without credentials or conversation content; see
[`PRIVACY.md`](vinci/PRIVACY.md). Everything in the grey box runs locally in either mode.
## Two ways to run it
| | **Direct / BYOK** | **Managed** |
|---|---|---|
| Vinci account | **not required** | required |
| Provider | you choose | Vinci selects |
| Your API key | stored locally; sent **only to your provider**, never to Vinci | you have none |
| Vinci sees your prompts | **no** | yes, in transit |
| Guard · receipts · checkpoints · review | ✅ | ✅ |
## What the Vinci layer adds
The table describes the current source. Check the installed version and its release notes
for the behavior of a distributed build; source checks alone do not qualify a release.
| Capability | Status | What it does |
|---|:---:|---|
| Command guard | In source | Classifies destructive operations and confirms before running them |
| Secret redaction | In source | Masks credentials before the terminal, diffs, previews, and `/feedback` + `/issue` egress |
| Honest terminal states | In source | A run blocked awaiting permission says so, instead of reporting a read-only success |
| Checkpoints | In source | Durable recovery points you can roll back to |
| Review / accept | In source | A workflow for inspecting and accepting agent output |
| Sandbox | In source | Bounded execution for agent-run commands |
| BYOK | In source | Any Pi-supported provider, with every guard above still active |
The first row is the one worth seeing rather than taking on trust. Asked to delete a directory
with `rm -rf`, it names the classification, prints the exact command it would run, and waits —
with **no** selected. The directory in this capture still had all four files in it afterwards.
Layout, the branch model, and the patch inventory: [`vinci/README.md`](vinci/README.md).
## Project structure
```
vinci-code-cli/
├── packages/ # Pi packages and Vinci integration patches
│ ├── ai/ # unified multi-provider LLM API
│ ├── agent/ # agent runtime: tool calling and state
│ ├── coding-agent/ # the coding agent CLI
│ ├── tui/ # terminal UI with differential rendering
│ └── orchestrator/ # multi-agent orchestration
├── vinci/ # the Vinci layer — almost everything Vinci is here
│ ├── extensions/ # guard, receipts, checkpoints, review, crew, …
│ ├── updater/ # signed update client and pinned public key
│ ├── themes/ # vinci-dark, vinci-light
│ ├── assets/ # logomark, lockup, demo captures
│ ├── docs/ # architecture, persistence, verification, environment
│ ├── test/ # integration harness for the Vinci layer
│ └── release-notes/ # mirrored to the public releases repository
├── scripts/ # repo tooling: checks, release, shrinkwrap
└── .github/workflows/ # CI, tests, benchmarks, signed release
```
`packages/` contains the Pi harness and Vinci integration patches, including changes to
existing upstream files. Most Vinci-specific code lives in `vinci/`, with additional
`vinci-*` modules and marked integration patches inside `packages/`. See
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the layer and patch conventions before contributing.
Extension-by-extension detail, the patch inventory and the branch model → **[`vinci/README.md`](vinci/README.md)**
## System requirements
| Requirement | Minimum |
|-------------|---------|
| Node | 22.19+ |
| OS | macOS or Linux |
| Sandbox | `sandbox-exec` (built into macOS) · `bubblewrap` (Linux) |
| Provider key | Any Pi-supported provider, for BYOK mode |
## Installation
```sh
# From source — the path this repository supports (Node 22.19+)
git clone https://github.com/getsimpledirect/vinci-code-cli
cd vinci-code-cli
npm ci --ignore-scripts && bash vinci/build.sh
./vinci/bin/vinci
```
```sh
# Or the signed release (installs the built binary and self-updates)
curl -fsSL https://vinci.getsimpledirect.com/install | sh
```
> There is no `vinci` npm package. The npm packages in this repo are **upstream Pi's**
> (`@earendil-works/*`, binary `pi`) — installing those gives you Pi, not Vinci Code.
## Quick start
Install it, run it, and sign in with your Vinci account:
```sh
./vinci/bin/vinci
/login # sign in to Vinci in your browser
/model # choose Vinci Auto, Vinci Mezzo, or Vinci Forte
```
By default, `/login` opens Vinci browser sign-in directly, and the model surfaces offer Vinci
models. Auto remains the initial model and uses your plan's default. The picker shows live
underlying model details for Mezzo and Forte when available, or a note when details are unavailable offline.
To bring your own provider key, run `/other` and confirm enabling other providers, then
use `/login` to choose an authentication method and provider. This opt-in persists globally.
You can also set `showOtherProviders: true` in settings or `VINCI_SHOW_OTHER_PROVIDERS=1`.
Vinci entries stay first, followed by a separate group of other providers in `/model`.
Run `/other` again to hide them; the environment switch overrides the setting in either direction.
`--list-models` works before sign-in. Its `auth` column marks local credential presence as
`configured` or `unconfigured`, without validating credentials or contacting providers.
Use `--list-models ` to filter it. Other providers appear after opt-in; the interactive
picker lists models with configured authentication.
**BYOK needs no Vinci account.** Credentials are stored by Pi in `~/.pi/agent/auth.json`.
Vinci Code adds no second credential store, and your provider key is sent only to the provider
you picked, never to Vinci. The coding demo above uses this optional mode.
## CLI reference
These are the commands `/help` lists in a session:
```
/login Connect to Vinci
/other Add or hide other providers
/logout Disconnect from Vinci
/model Choose which Vinci model to use
/new Start a fresh conversation
/resume Pick up an earlier conversation
/undo Undo the last changes Vinci made to your files
/usage See this task's model calls, tokens, and cost
/security Show Vinci's active confidentiality and sandbox controls
/support Get help and support
/feedback Send private feedback without uploading your transcript
/issue Report a bug or request a feature on the public tracker
/hotkeys Keyboard shortcuts
```
The Vinci layer adds more on top of these — `/review`, `/checkpoint`, `/plan`, `/todo`,
`/crew` and others come from the extensions in `vinci/extensions/`.
### Task state, recovery and display
The final receipt distinguishes `DONE`, `DONE-UNVERIFIED`, `WAITING` and `BLOCKED`.
Read the verification and stopping reason before treating a task as complete. The usage
meter is a local estimate, and the account/provider billing surface remains authoritative.
- `/agents` opens helper status and reviewed changes; `/task-info` gives the task ID.
- Press Escape to abort active work. Reopen a saved task with `vinci resume `.
- `vinci report-wrong "optional note"` records a false completion locally.
- `vinci doctor` inspects the installed environment; `vinci update` and `vinci rollback`
use the signed update flow.
Regular terminal mode is the default. Opt into fullscreen with `vinci --tui-mode fullscreen`
or the `tuiMode` setting. See [terminal controls and recovery](vinci/README.md#fullscreen-opt-in)
for selection, scrolling and the terminal-specific checks still outstanding. Plain and
reduced-motion presentation options are documented in
[the environment reference](vinci/docs/environment.md#terminal-presentation).
### Local Work task client
`vinci runtime --help` lists an optional local Work client. It requires an explicitly
configured, owned, private (no group or world access) `VINCI_RUNTIME_CONFIG` profile with a
numeric loopback origin and exactly one Work cookie or token. The client itself reads no other credential or profile; like every `vinci` command, the launcher first loads `~/.vinci-code.env` if it exists.
The client can create an admitted saved task, inspect state/events, answer a current
question, approve or correct an exact action, read receipts/artifacts and request
cancellation. Creation does not launch a worker; cancellation does not prove it stopped.
After an uncertain mutation, reconcile the original outcome before retrying.
Task listing, worker launch/resume, hosted schedules, merging and deployment are outside
this interface. See [configuration and limits](vinci/docs/environment.md#local-work-task-client).
### Environment variables
| Variable | Effect |
|---|---|
| `VINCI_SHOW_OTHER_PROVIDERS` | Other providers are off by default. `1` enables them, `0` hides them; either overrides the saved `/other` preference. |
| `VINCI_RUNTIME_CONFIG` | Explicit private profile for the optional local Work task client; unrelated to provider authentication. |
| `VINCI_PROVIDER` | `vinci` (default) or `openrouter` |
| `VINCI_MODEL` | With `VINCI_PROVIDER=vinci`: `auto` (default), `mezzo`, `forte`, or `fortissimo` (alias of Forte). `auto` resolves server-side to your account's class. With `openrouter`: a full `vendor/model` id. |
| `VINCI_NO_SANDBOX=1` | Disable the sandbox. A development escape hatch — it removes a real safety boundary. |
| `VINCI_ISSUE_REPO_URL` | Override where `/issue` files reports |
Full extension list and behaviour → **[`vinci/README.md`](vinci/README.md)**
## Documentation
| Document | What it covers |
|---|---|
| [`vinci/README.md`](vinci/README.md) | The Vinci layer in detail — extensions, layout, branch model |
| [`vinci/PRIVACY.md`](vinci/PRIVACY.md) | Exactly what leaves your machine, in each mode |
| [`SECURITY.md`](SECURITY.md) | Reporting a vulnerability; known limits |
| [`UPSTREAM.md`](UPSTREAM.md) | Fork provenance and how to sync with Pi |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute |
| [`SUPPORT.md`](SUPPORT.md) | Where to take a bug, a question, or a billing issue |
| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Expected conduct, and how to report a concern |
## Development checks
Build with `bash vinci/build.sh` after the source installation above; it uses the committed
model catalogs. Run `npm run check` for the repository checks and
`VINCI_SKIP_SMOKE=1 bash vinci/test/run.sh` for the offline Vinci harness. The full
harness can make live gateway calls when authenticated, so choose that lane explicitly.
Use [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for contribution and
dependency-install rules.
## Releases
This public repository's reviewed `main` is the canonical product source and its protected
[`vinci-v*` release workflow](.github/workflows/vinci-release.yml) is the sole product
publisher. The product version comes from [`vinci/identity.json`](vinci/identity.json),
independently of the Pi package versions.
Release preparation and activation are separate runs:
1. A protected tag push, or a manual `candidate` run on that tag, builds/tests the unsigned
archive and carries those exact bytes into protected signing and immutable staging.
This phase retains a signed candidate for owner QA and ends **without activation**.
2. A separate manual `activate` run needs the exact candidate/artifact and QA-receipt
identities plus a fresh protected approval. It validates the retained signed bytes,
policy/expiry and unchanged live baseline, then conditionally updates the manifest.
It does not rebuild or re-sign. Public GitHub Release assets and release notes are
published after the activated manifest's live bytes are verified.
A successful candidate run does not establish that a version is available to users.
Clients verify the signed manifest and archive hash. See
[activation risks and recovery](vinci/RELEASE-ACTIVATION-RISK.md) before release operations.
Private operations and signing-key custody remain private and do not create a second publisher.
| What you want | Where it is |
|---|---|
| What version am I running | `vinci --version` — nothing is pinned in these docs, so it cannot go stale |
| What changed | the [releases page](https://github.com/getsimpledirect/vinci-code-cli/releases), and [`vinci/release-notes/`](vinci/release-notes/) |
| The build itself | the installer above, which verifies a signed manifest and its sha256 |
| Bug reports and questions | [`SUPPORT.md`](SUPPORT.md) |
Product changes land through the public review lineage. The retained private repository's legacy
mirror/rebase workflow is a separate maintenance model; it is unsupported on public product
`main` until adapted. See [`vinci/UPSTREAM.md`](vinci/UPSTREAM.md).
## Project status
**Actively maintained** by a small team. Security fixes go to the latest release only — there
is no LTS branch. APIs and settings may change before 1.0. Issues and pull requests are
welcome.
Security reports: [`SECURITY.md`](SECURITY.md). Report the *format* of a missed
credential, never a live key.
## Contributing
Read **[`CONTRIBUTING.md`](CONTRIBUTING.md)** before opening a PR. Most of `packages/` is
upstream Pi, so the first question is whether a change belongs here or upstream — sending an
engine fix only to us means Pi's users never get it, and we carry the patch forever.
[`AGENTS.md`](AGENTS.md) carries the engineering rules for this codebase and applies to humans
as well as agents.
## License
The source code is **MIT** — see [`LICENSE`](LICENSE).
- Upstream Pi is © 2025 Mario Zechner, MIT. That notice is preserved verbatim.
- Vinci's modifications are © 2026 Alpine Pacific Trading Inc., under the same MIT grant.
- Third-party notices: [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
- "Vinci" and "SimpleDirect" are trademarks of Alpine Pacific Trading Inc.; the code grant
conveys **no** trademark rights. See [`TRADEMARKS.md`](TRADEMARKS.md) — if you fork and
ship this, rename it.
Original brand artwork retains its recorded provenance; the code license and this README do not
grant additional artwork or trademark rights. See [`vinci/BRAND.md`](vinci/BRAND.md) and
[`vinci/NOTICE`](vinci/NOTICE).