$ Terminal AI coding agent that lives in your project directory

ViCode — install and fix bugs from your terminal

A Terminal AI coding agent for Terminal-first Developers. Copy the install command, bring your OpenRouter key, and start in your project directory.

$ npm install -g vicode-ai

★ Star

  • Node 22+ required
  • OpenRouter API key required
  • bash on PATH required on Windows (Git Bash or WSL)

vicode — Faked Terminal

vicode [build] › fix the login crash on empty password

Simulated session · scripted demo

Modes govern each turn

Build, discuss, and plan scope which tools the model can even see. The active Mode is marked by a colored Mode tag, in the CLI and here.

vicode [Build] ›

Get the work done. The model reads, edits, and runs shell commands to work through the spec or tickets.

All six tools visible — no mode confinement.

  • read_file
  • list_files
  • search
  • write_file
  • edit_file
  • bash

Tab through the modes — in the ViCode CLI, the Tab key cycles build → discuss → plan.

Everything the README promises, nothing it doesn't

Six cards, each traced to a README fact. The rest lives in the docs it came from.

  • Two-panel TUI

    A scrolling Chat Panel plus a Usage Panel with model, token totals (in/out), context usage, cost, and turn count.

    token-by-token streaming · Esc cancels

  • Six core tools

    Reads, lists, searches, writes, edits, and runs shell commands — every step visible as it happens.

    read_file · list_files · search · write_file · edit_file · bash

  • Approval + Bash Allowlist

    Ordinary in-project file operations run silently; Sensitive Paths and out-of-root targets pause for approval.

    Allowlist re-checked on every call — no turn-memory for bash

  • Context budgeting + auto-compaction

    History is projected to fit 70% of the context window; at 60% load older messages fold into a running summary.

    largest results dropped first · /compact on demand

  • Skills + layered config

    Markdown skill files inject extra System Prompt layers; project config overrides global config.

    .vicode.json · ~/.vicode/config.json

  • Session persistence

    Conversations auto-save as JSON inside the project and resume automatically on the next start.

    .vicode/sessions/<id>.json

Full details live in the README.

Edits you can trust

Blast Radius

What the model is allowed to touch without approval — in-project by default. Sensitive Paths and anything outside the Project Root pause for approval instead of running silently.

  • Turn-scoped approval memory — approve a path once and later calls to that path run without re-asking for the rest of the turn. This memory resets at the start of every turn, on session switch, and on a new session.
  • Bash Allowlist re-check — the allowlist is re-checked on every single call, and there is no turn-memory for bash approvals. An empty allowlist means every bash call asks.

How approval works, in the README.

Daily use, predictable

Nine slash commands and five keys. That is the whole surface.

  • /helpList available commands
  • /sessionSwitch to a saved session
  • /newSave the current session and start a new one
  • /exitStop any response in progress, save the session and quit
  • /modelSwitch the LLM model mid-session
  • /skillLoad a skill Markdown file as a System Prompt layer
  • /homeReturn to the Welcome Screen
  • /keySet, change, or remove your OpenRouter API key
  • /compactFold older messages into a summary and keep the context window lean

Only the first word of an input is treated as a command — `/help me` runs `/help`.

  • TabCycle the Mode (build → discuss → plan)
  • y / nApprove / reject a pending tool call
  • EscCancel the in-progress response
  • EnterSubmit the message
  • ↑ / ↓Recall Input History

Honest answers only

Sourced from README limitations and requirements — nothing invented.

Why does the cost display show $0.00?

Cost display only covers eight hardcoded models. Any other model — including the default — shows $0.00 even though tokens are still counted correctly.

Why is the Context row missing?

The Context row needs a warm model cache: it appears once the active model's context length is known from ~/.vicode/models-cache.json. Open /model once to populate it; until then budgeting falls back to a 200k window.

How do I delete old sessions?

Sessions cannot be deleted from the UI. /session lists and switches; prune old <project>/.vicode/sessions/*.json files manually.

Does ViCode work in Windows cmd?

ViCode shells out to bash -c, so it needs a bash binary on PATH. On Windows that means Git Bash or WSL — on stock cmd or PowerShell, bash calls fail until you install one.