*vigent-docs* vigent user manualv0.9.7

GETTING STARTED*vigent-start*

Install globally, then run it inside a git repository.
npm i -g @vigent/cli
vigent .                  # or: vigent ~/code/app
vigent --version
vigent opens on a dashboard: i new agent, E engine, m model, t theme, s settings, ? every key. Press <Space> and pause for a which-key panel.

YOUR FIRST AGENT*vigent-first*

Press i, type what you want done, Enter. The agent starts in its own worktree on a branch named from the task (fix/…, feat/…). Press i again to follow up, Esc to go back to NORMAL. Start more with |:new|. Links in a reply are clickable (Cmd-click in most terminals), even when they wrap.

ENGINES*vigent-engines*

An engine is what runs an agent. CLIs run as installed, in the agent's worktree, with their own login. The sidebar shows ● ready, ◐ not signed in, ○ not installed.
:engine                   " menu: auto, pi, claude, codex, opencode
:engine claude            " new agents run on Claude Code
:new docs pass --engine codex
:checkhealth              " what's installed and signed in
Agents keep the engine they started on. auto picks the first signed-in CLI, otherwise pi when it has a key.

WORKTREES*vigent-worktrees*

Every agent gets its own worktree and branch, so agents never touch your checkout or each other's files.
:new fix flaky checkout test  " branch fix/flaky-checkout-test
:worktrees                     " list them
:kill                          " stop the agent, keep its work
:kill!                         " also remove the worktree, safely
:attach <branch>               " reopen an agent in a kept worktree
Agents and their conversations come back after a restart. Their records live in git's own worktree metadata, not in your files.

RIFTRI*vigent-riftri*

riftri installs with vigent. It makes each worktree a real git linked worktree whose unchanged files share copy-on-write storage: APFS clones on macOS, Btrfs, reflink XFS or OverlayFS on Linux, ReFS on Windows.
:newsays · riftri apfs-clone (or reflink, overlay-fs…)
:checkhealthshows why riftri fell back to git, and the fix
riftri gcfrees storage no worktree uses any more
vigent falls back to plain git only when riftri declines and says nothing changed. [worktree] backend = "riftri" requires it, "git" turns it off.

REVIEW & LAND*vigent-review*

:diff                  " the agent's changes; ]c / [c between hunks
:diff split            " side by side
:merge                 " squash into your branch: one commit
:merge --no-squash     " a regular merge commit
:pr                    " push and open a pull request
:dash                  " every agent at a glance
:tree                  " go back to any point in the conversation
A merge only touches your checkout when it's clean and on the agent's base branch. A conflict is rolled back, so nothing changes.

KEYS*vigent-keys*

i a otype a prompt for the focused agent
j k gg Gscroll the transcript
{ }jump between messages
]s [s <Space>1–9switch agents
<Space>efocus the sessions sidebar, like neo-tree: j/k pick, a new, dd kill, Esc back
<C-w>h <C-w>lsidebar / transcript, like neovim windows (also <C-h> <C-l>)
za zR zMfold tool output
V vselect lines, y to copy
yy yibcopy the last reply / a code block
ddkill the focused agent (asks first)
<Space>…n d m p q t D u s r T E M R (pause to see them)
Copies go through the terminal (OSC 52), so they work over SSH.

COMMANDS*vigent-commands*

:new <task>     :queue <prompt>   :pause :resume   :w [file]
:engine         :model           :effort          :settings
:colorscheme    :hi Group …       :set transparent  :help
:nmap :imap :unmap :let mapleader      :q :q!

MODEL & EFFORT*vigent-model*

|:model| (<Space>M) lists every model by name and version (Claude Fable 5.1, GPT-5.5 Codex…) in one plain list, from every engine that's signed in. |:effort| (<Space>R) sets reasoning effort. Both apply from the next prompt and survive a restart. In every menu: j/k move, Enter picks, q closes, / searches.

PERMISSIONS*vigent-permissions*

Agents run headless, so one can't stop to ask before a command it isn't allowed. It refuses it, and vigent shows what was refused and the :permissions allow line that would permit it.
|:permissions| is a panel of what each agent may do without asking: Claude Code's mode, asking when it's refused a tool, and its allow rules; Codex's sandbox and network; Gemini CLI's approval mode; Cursor CLI's --force.
:permissions                        " the panel
:permissions allow Bash(cargo:*)   " one more Claude Code rule
:permissions remove Bash(cargo:*)  " and away again
Every change is saved to config.toml as you make it, so it stays set after a restart, and every agent uses it from its next prompt. With several vigents open, each change starts from what's saved, so one never undoes another's.

CONFIG.TOML*vigent-config*

~/.config/vigent/config.toml. vigent config init writes a starter file.
theme = "nvim"
engine = "claude"
leader = "<Space>"

[ui]
icons = "nerd"

[keys.normal]
"<leader>n" = ":new "
"<Tab>" = "session.next"

[keys.insert]
"jk" = "<Esc>"
vigent config check validates it. |:settings| edits it live; w saves.

THEMES & ICONS*vigent-themes*

vigent theme import             # the colorscheme your nvim/vim uses
vigent theme import kanagawa    # any colorscheme your editor can load
vigent theme new mine --from nord
vigent --theme nvim             # follow Neovim
|:colorscheme| previews live. icons = "nerd" uses Nerd Font icons; set a Nerd Font in your terminal for them.
vim:tw=78:ts=8:ft=help:norl: