vcode — Agentic Dev Shell

vcode is a terminal-based AI coding assistant powered by OpenRouter or NVIDIA NIM. It runs in your shell with file editing, code search, and bash execution capabilities.

Quick Start

Prerequisites

• Node.js 18+ or Bun (for development)
• An API key from OpenRouter or NVIDIA NIM

Install

npm install -g vcode-tui

Usage

vcode

On first launch, you'll be prompted to trust the current working directory. vcode will also ask you to select a model if multiple are available.

Configuration

API Keys

Create a ~/.vcode/.env file or a .env file in your project root:

# OpenRouter (recommended — includes free tier models)
OPENROUTER_API_KEY=sk-or-...

# Or NVIDIA NIM
NVIDIA_API_KEY=nvapi-...

Note: OpenRouter is the default provider. If both keys are set, the provider is auto-detected. Set VCODE_PROVIDER=nvidia to force NVIDIA.

Environment Variables

| Variable | Description | Default | |---------------------|--------------------------------------------------------------------|-------------------------------| | OPENROUTER_API_KEY | OpenRouter API key | — | | NVIDIA_API_KEY | NVIDIA NIM API key | — | | VCODE_PROVIDER | Force provider: auto, nvidia, or openrouter | auto | | VCODE_MODEL | Override the default model ID | Provider-specific default | | VCODE_AUTO_TRUST | Set to 1 to skip the folder trust prompt | — |

Commands

Slash Commands

| Command | Description | |-----------------|--------------------------------------------| | /help | Show help panel | | /model | List and switch models | | /models | Show only free-tier models (OpenRouter) | | /provider | Switch between OpenRouter and NVIDIA | | /theme | Change the color theme | | /clear | Clear the conversation history | | /tree | Show project file tree | | /tools | List available agent tools | | /root | Show current workspace root | | /cd | Mock directory change (ROOT stays same) | | /exit | Exit vcode |

Tool Commands

| Command | Description | |-----------------|--------------------------------------------| | /read_file | Read a file's contents | | /write_file | Write content to a file | | /edit_file | Replace text in a file | | /list_files | List files in the workspace | | /grep | Search for a pattern across files | | /bash | Run a shell command |

Shell Escape

Any line starting with ! is executed as a shell command:

!npm run build

Troubleshooting

vcode: command not found

The npm global binaries directory isn't in your PATH.

Step 1 — Find the global bin directory:

npm bin -g

Typical locations:

• ~/.npm-packages/bin
• ~/.npm-global/bin
• /usr/local/bin
• /opt/homebrew/lib/node_modules/.bin (Apple Silicon Mac)

Step 2 — Add to your shell config:

Add this line to ~/.zshrc (or ~/.bashrc / ~/.bash_profile):

export PATH="$(npm bin -g):$PATH"

Step 3 — Reload and verify:

source ~/.zshrc
which vcode

No API key configured

Create a .env file or set the environment variable:

export OPENROUTER_API_KEY="sk-or-..."
vcode

vcode loads .env from, in order:

1. Current working directory (.env)
2. The package directory
3. ~/.vcode/.env

403 Forbidden when publishing

If you get a 403 when running npm publish:

1. Go to npm tokens page
2. Create a Granular Access Token with Read and Write permissions and Bypass 2FA enabled
3. Configure locally:

   export NPM_TOKEN="npm_..."
   echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc

Version conflicts when publishing

You can't publish the same version twice. Bump the version:

# In package.json, increment the version field
npm version patch  # or minor, or major
npm publish

Autocomplete not working

Tab completion works for:

• Slash commands (type / then Tab)
• File paths (type @ or start typing a path then Tab)

If it's not working, ensure you're in an interactive terminal session (not piping input).

Development

# Clone
git clone https://github.com/H4mzaX/vcode-tui.git
cd vcode-tui

# Install dependencies
bun install

# Build
npm run build

# Run locally
node dist/index.js

Publishing

# Build
npm run build

# Publish to npm
npm publish

License

Proprietary — see package.json.