vincent documentation
vincent is a local-first control plane for AI coding-agent workloads. A
background daemon owns the state and the execution — SQLite, git worktrees,
agent CLI subprocesses — and every client (the TUI, the vincent subcommands,
curl) is a thin consumer of its localhost API.
It gives locally installed agents durable scheduling, reusable workflows, isolated branches, deterministic checks, human gates, crash recovery, and one place to see the work. Start with the feature tour, or run a real task with the Quickstart.
Explore vincent
| I want to… | Start here |
|---|---|
| Understand what vincent can do | Features |
| Run my first managed agent task | Quickstart |
| Learn the daemon, workflow, task, and worktree model | Concepts |
| Build reliable, cost-aware workflows | Writing workflows |
| Operate active workloads from the terminal | Using the TUI |
| Integrate vincent with scripts or CI | Scripting vincent |
What makes it different
- Work survives the client. Close the TUI or terminal and the daemon keeps scheduling, running, and recording tasks.
- Workflows are more than prompts. Mix agents with commands, approval gates, parallel groups, fan-out, conditions, loops, and reusable includes.
- Every task is isolated. A dedicated git worktree and branch protect your checkout and let multiple changes run at once.
- Success is verified. Checks, retries, timeouts, blocked-step recovery, and durable transcripts make outcomes inspectable instead of aspirational.
- People retain control. Review diffs, approve gates, answer supported agents, edit and retry failed steps, and choose exactly when delivery happens.
- The interface is yours to choose. Use the full TUI, JSON-capable CLI, or localhost REST + SSE API on Windows, macOS, and Linux.
Getting started
| Page | What it covers |
|---|---|
| Installation | Download, verify, and put vincent on your PATH; installing an agent CLI; upgrading and uninstalling |
| Quickstart | Register a repository, run your first task, approve it, ship the branch |
| Concepts | Daemon, project, workflow, task, step, worktree — and how they fit together |
Guides
| Page | What it covers |
|---|---|
| Writing workflows | The authoring guide, in 14 sections: the nine step types, control flow, templates, checks, retries, agents, portability |
| Agent CLIs | Claude Code, Codex and Cursor: installing, authenticating, and what each one can and cannot do |
| Using the TUI | The board, task detail, the four takeover screens, every key |
| Scripting vincent | --json, exit codes, and driving the API directly from a script or CI |
| Running at login | vincent service install on launchd, systemd and Task Scheduler |
| Troubleshooting | The failures people actually hit, and what each one means |
Platforms
vincent runs the same feature set on all three platforms, and the places where that is not true are stated rather than smoothed over.
| Page | What it covers |
|---|---|
| Windows | SmartScreen, %APPDATA%/%LOCALAPPDATA%, PowerShell command steps, the Scheduled Task, the one restricted-mode gap |
| macOS | Gatekeeper, the Developer ID signature and the stapled .pkg, ~/Library/Application Support, the LaunchAgent, PATH capture |
| Linux | XDG directories, the systemd user unit, loginctl enable-linger |
Reference
| Page | What it covers |
|---|---|
| CLI | Every command, flag, and exit code |
| Configuration | config.yaml key by key, plus per-project settings |
| Files and directories | Where vincent puts everything, on every platform |
| Workflow schema | The complete YAML field reference |
| Task lifecycle | States, human actions, step outcomes, block reasons |
| HTTP API | REST endpoints, the SSE streams, the error envelope |
Also here
- Security model — what full-auto means, what the worktree does and does not isolate, and how to tighten it.
- FAQ — the short answers.
- Example workflows — five ready-to-copy files.
- Changelog — user-visible changes in every release.
Contributing
Want to improve vincent itself? The Contributing guide covers development setup, architecture pointers, documentation expectations, tests, cross-platform checks, commit conventions, and pull requests.
The repository also retains maintainer specifications, engineering work records, acceptance walkthroughs, and historical decision records. They support implementation work and stable code citations, but they are not prerequisites for installing or using vincent; the contributing guide points to the relevant record when a change needs one.
Conventions in these docs
{config_dir}and{data_dir}are the platform-native directories resolved in Files and directories.- Shell samples are POSIX unless a PowerShell equivalent is shown beside them.