VinaX Code

VinaX CLI by SIRIMILLA VINAY

An agentic coding CLI with Claude Code's feature set. It works with free and paid model providers:

| Provider | id (aliases) | Free | Default model | Get a key | |---|---|---|---|---| | Groq | groq | ✅ | openai/gpt-oss-120b | https://console.groq.com/keys | | NVIDIA NIM | nvidia (nim) | ✅ | nvidia/nemotron-3-ultra-550b-a55b | https://build.nvidia.com | | OpenRouter | openrouter (or) | ✅ :free models | nvidia/nemotron-3-ultra-550b-a55b:free | https://openrouter.ai/keys | | Gemini | gemini (google) | ✅ free tier, paid once billing is on | gemini-3.6-flash | https://aistudio.google.com/apikey | | Claude | anthropic (claude) | | claude-opus-5-5 | https://console.anthropic.com | | ChatGPT | openai (chatgpt) | | gpt-5 | https://platform.openai.com/api-keys | | VinaX proxy | proxy (render) | depends on the proxy | groq/openai/gpt-oss-120b | your proxy's URL and token |

It has no npm dependencies and needs Node.js 20 or newer.

npm install -g vinax-code   # installs the `vinax` (and `vinax-code`) command
vinax                       # the first run opens your provider's site to get a key, then checks it

Works on macOS, Windows (PowerShell, Windows Terminal, cmd; uses Git Bash when installed), WSL, Linux, Kali, Termux and editor terminals such as VS Code — see the install & platforms guide. Run vinax doctor to check your setup.

From source: git clone https://github.com/Vinay1812007/VinaX-CLI-2.0 && cd VinaX-CLI-2.0 && npm link

Documentation: https://vinax-proxy.onrender.com

Features

| | | |---|---| | Agent loop | Streaming output, parallel tool calls, automatic retries for free-tier rate limits, and a token counter | | Tools | The same tools as Claude Code, with the same names, parameters and descriptions: Read (also images and notebooks), Write, Edit, MultiEdit, NotebookEdit, LS, Glob, Grep (uses ripgrep when installed), Bash (with background shells via BashOutput/KillShell), WebFetch, WebSearch, TodoWrite, Task (subagents), Skill, AskUserQuestion, ExitPlanMode, and MCP tools. The pre-1.11 names (read_file, bash…) still work in agent definitions and saved sessions | | Permission modes | default → acceptEdits → plan → auto (→ bypassPermissions). Shift+Tab cycles through them. Auto mode runs everything except risky actions (sudo, deletes outside the project, git push, curl \| sh, publishing…) | | Permission rules | Same syntax as Claude Code: Bash(npm test:*), Edit(src/**), WebFetch(domain:docs.rs), mcp__github. Supports allow, ask, and deny lists, and chained commands are checked part by part | | Plan mode | Read-only research, then a plan you approve before any edits happen | | Hooks | PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, Notification, PreCompact. Uses Claude Code's JSON and exit-code-2 protocol | | MCP | stdio and streamable-HTTP servers. Configure them in .mcp.json or settings, or with vinax mcp add. Servers from a project's .mcp.json need your approval | | Subagents | VinaX delegates on its own. Built-in general-purpose, Explore, Plan, smoke-tester (/smoke) and code-reviewer agents, plus your own in .vinax/agents/*.md (with an optional color:). Each shows its live tool uses and tokens; parallel agents appear as a "Running N agents…" tree | | Custom commands | .vinax/commands/*.md with $ARGUMENTS/$1, !`shell` substitution, @file, and model / allowed-tools frontmatter | | Skills | .vinax/skills/<name>/SKILL.md, loaded when the task matches | | Memory | VINAX.md (or CLAUDE.md/AGENTS.md) from the project, its parent folders, and ~/.vinax/, with @path imports. Start a message with #note to save a note | | Checkpoints | Every file edit is snapshotted. /rewind (or Esc Esc) restores code, conversation, or both | | Sessions | Saved automatically. Use vinax -c, vinax -r <id>, or /resume. /export writes a markdown transcript | | Context | Windows are per model, not per provider — /model shows each model's window and /context says where the figure came from. Auto-compact runs at 80%, /compact [focus] compacts on demand | | Claude extras | Adaptive thinking (shown live), /effort levels, prompt caching, signed thinking blocks sent back unchanged, eager tool-input streaming, and server-side refusal fallbacks (fallbacks: "default") on Opus 5.5, Sonnet 5.5, and Fable 5.1 | | Terminal UI | Claude Code-style input box with a / command menu, @ fuzzy file search, ! bash mode, # memory mode and ? shortcuts. Permission prompts with diffs, multiple-choice questions, and pickers for /model, /provider, /resume, /config and more | | Visibility | Live thinking preview under the spinner, a live box for running commands (Ctrl+B sends it to the background), compact "Read 3 files, ran 2 shell commands" summaries, "Allowed by auto mode" marks, tips, and /btw for side questions | | Input | Big pastes become [Pasted text #1] chips (Ctrl+E or double-click to expand), Claude-style next-prompt suggestions (→ to accept), @file or @dir mentions, images (@shot.png or a dragged-in path), multi-line paste, messages queued while the agent is busy, Esc to interrupt | | Attachments | Drag images, videos, audio and PDFs into the terminal ([Image #1] chips) or press Ctrl+V to paste a screenshot. Videos are read as frames plus a transcript (ffmpeg), audio is transcribed with Whisper (Groq or OpenAI), PDFs are read natively or as extracted text | | Model fallback | When a model hits a rate or usage limit, VinaX switches to another configured free model and keeps working (autoFallback, fallbackModels). Pick Auto in /model to leave the choice to VinaX from the start. Models that cannot see images, or cap how many a request may carry (NVIDIA: 8), get the newest images and a note in place of the rest instead of an error | | Effort | /effort slider (low → max) with an Ultracode toggle for parallel sub-agent work | | Full screen | Like Claude Code: runs on the terminal's alternate screen, so exiting leaves your terminal as it was. Mouse-wheel and PageUp/PageDown scrolling, and drag to select and copy. VINAX_FULLSCREEN=0 or /config switches to inline output | | Terminal | The window title shows the current task (✳ Fix login validation) and animates while VinaX works; iTerm2, Ghostty, WezTerm and Windows Terminal also show a progress indicator in the tab | | Settings & themes | /settings grouped panel (appearance, model, permissions, updates, conversation) and /theme with Dark, Light, colorblind-friendly and ANSI-only styles | | Updates | vinax update, vinax install <version> to pin or roll back, vinax versions, a startup notice when a new version is out, and /release-notes | | Snake | /snake plays a real Snake game inline in the chat: walls or wrap-around edges, three speeds, a speed ramp, timed bonus fruit and a high score per mode. It opens even while VinaX is working, and pauses itself if VinaX needs you | | Headless | -p with --output-format text\|json\|stream-json, --allowedTools, --disallowedTools, --permission-mode, --max-turns, --append-system-prompt, --mcp-config, --add-dir |

Some Claude Code features are not implemented: IDE integrations, vim mode, and Claude's hosted server tools. WebSearch uses DuckDuckGo, or Brave/Tavily if you set BRAVE_API_KEY or TAVILY_API_KEY.

Usage

vinax                                     # interactive
vinax "fix the failing test"              # interactive, with a first prompt
vinax -p "explain this error" < err.log   # headless; prints only the final answer
vinax -p "run the tests and fix failures" --allowedTools "Bash(npm test:*) Edit" --output-format json
vinax --provider nvidia -m nvidia/nemotron-3.5-lightning-30b-a3b
vinax --permission-mode plan              # start in plan mode
vinax -c                                  # continue the last session in this folder
vinax doctor                              # check tools, keys, provider reachability and MCP
vinax update                              # update to the latest version

Slash commands

Type / to open the command menu. Commands without arguments open a picker.

/help /clear /compact [focus] /context /copy /cost /status /provider [id] /model [id] /effort [level] /login /logout /proxy [url] [token] /plan /auto /yolo /permissions /add-dir /memory /init /review [PR#] /security-review /rewind /resume [all] /export [file] /todos /bashes /agents /skills /mcp /hooks /config /doctor /snake /update /release-notes /exit, plus your custom commands and skills.

Shortcuts

| Key | | |---|---| | ? | show all shortcuts | | Shift+Tab | cycle default → accept edits → plan → auto mode (the footer shows ⏵⏵ auto mode on · 1 shell with the running background shells) | | Esc | interrupt the agent, close a menu, or reject a permission prompt | | Esc Esc | clear the input; with an empty input, open /rewind | | Ctrl+C | interrupt or clear input; press twice to exit | | Ctrl+O / Ctrl+T | verbose tool output / show todos | | Ctrl+G | edit the prompt in $EDITOR | | Option+Enter, \ Enter | newline | | ultrathink | maximum reasoning effort for that prompt |

When VinaX asks for permission, choose 1. Yes, 2. Yes, and don't ask again (saves a rule such as Bash(npm test:*) to .vinax/settings.local.json, or auto-accepts edits for the session), or 3. No (Esc) and tell VinaX what to do differently.

Configuration

Settings are merged from the following files, with later ones taking priority. .claude/settings*.json is also read, so existing Claude Code hooks and permission rules work.

1. ~/.vinax/settings.json (user)
2. .vinax/settings.json (project, committed)
3. .vinax/settings.local.json (project, personal; git-ignored)
4. --settings <file>

{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(git diff:*)", "Edit(src/**)"],
    "deny": ["Bash(rm -rf:*)", "Read(.env)"],
    "ask": ["Bash(git push:*)"],
    "defaultMode": "default",
    "additionalDirectories": ["../shared-lib"]
  },
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write|MultiEdit", "hooks": [{ "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.path)\"" }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "grep -q 'rm -rf /' && { echo 'blocked' >&2; exit 2; } || exit 0" }] }
    ]
  },
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } }
  },
  "statusLine": { "type": "command", "command": "echo \"$(git branch --show-current) · $(jq -r .model.id)\"" },
  "env": { "NODE_ENV": "development" }
}

Hook commands receive JSON on stdin: tool_name, tool_input (with Claude Code's parameter names, e.g. file_path, command, pattern), tool_response, prompt, session_id, cwd, and so on. Exit code 2 blocks the action and sends stderr back to the model. A hook can also print {"decision":"block","reason":"…"} or hookSpecificOutput.permissionDecision. Tool names follow Claude Code's: Bash, Read, Edit, Write, MultiEdit, Glob, Grep, LS, WebFetch, WebSearch, Task, mcp__server__tool.

Commits and pull requests VinaX writes end with an attribution trailer, as in Claude Code: Co-Authored-By: VinaX Code <[email protected]> and 🤖 Generated with [VinaX Code](…). Set "includeCoAuthoredBy": false in settings to drop them, or "attribution": { "commit": "…", "pr": "…" } to replace them.

App settings live in ~/.vinax/config.json. Change them in the /config panel or with /config set <key> <value>. The keys are effort, maxTokens, maxTurns, autoCompact, autoCompactRatio, contextWindow, showThinking, fallbacks, updateCheck, autoUpdates, and terminalTitle.

Context windows

A context window belongs to the model, not to the provider serving it, so VinaX resolves it per model and shows it next to every name in the /model picker (a ~ marks a figure the provider didn't report). /context prints the window it is measuring against and where that number came from.

The order of truth is:

1. contextWindow in your config — either a plain number for every model, or a map of model pattern to tokens:

   { "contextWindow": { "glm-5.3": 200000, "groq:allam-2-7b": 2048 } }

   Keys match the model id (as a substring or regex), or provider:model for one host only.
2. What the provider reported for that exact model id. Groq and OpenRouter publish a window per model in /models; VinaX records it when it lists models and remembers it in modelWindows once you select the model.
3. The built-in table of known models (MODEL_WINDOWS in src/providers.js).
4. The provider's default, as a last resort for a model nothing else recognises.

A host may serve a model with a narrower window than the model supports, or a wider one on a free route, which is why a reported figure always wins over the table.

MCP

vinax mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
vinax mcp add -s project -t http linear https://mcp.linear.app/mcp -H "Authorization: Bearer $LINEAR_KEY"
vinax mcp add-json db '{"command":"uvx","args":["mcp-server-sqlite","--db-path","app.db"]}'
vinax mcp list
vinax mcp remove filesystem

The scopes are local (the default, in .vinax/settings.local.json), project (.mcp.json), and user (~/.vinax/settings.json).

Subagents, commands, and skills

<!-- .vinax/agents/test-runner.md -->
---
name: test-runner
description: Runs the test suite and fixes failing tests. Use after code changes.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---
You are a test specialist. Run the tests, diagnose failures, fix them, and report what changed.

<!-- .vinax/commands/fix-issue.md  →  /fix-issue 123 -->
---
description: Fix a GitHub issue
argument-hint: <issue-number>
allowed-tools: Bash(gh issue view:*)
---
Fix issue #$1. Details: !`gh issue view $1`

<!-- .vinax/skills/release/SKILL.md -->
---
name: release
description: Cut a new release (version bump, changelog, tag)
---
1. Run ./scripts/bump.sh ...

VinaX also reads the same folders under ~/.vinax/, .claude/, and ~/.claude/.

Updating

vinax update               # install the latest version
vinax install 1.0.0        # install a specific version, e.g. to roll back
vinax versions             # list published versions
vinax --version

Inside a session, /update does the same, and /release-notes shows what changed.

Auto-updates. Like Claude Code, VinaX keeps itself up to date: when installed with npm install -g, it checks npm at startup (and every 30 minutes) and installs new versions in the background. You'll see ✓ Update installed · Restart to apply under the input box. Turn auto-install off in /config (Auto-updates) or with DISABLE_AUTOUPDATER=1; turn update checks off entirely with VINAX_DISABLE_UPDATE_CHECK=1. From a git checkout (npm link), VinaX only notifies you, and vinax update runs git pull.

VinaX proxy

A VinaX proxy is an OpenAI-compatible gateway that holds the provider keys, so your machine only needs one token. Pick the upstream provider with a model prefix: groq/…, nvidia/…, openrouter/…, gemini/…, anthropic/… or openai/….

/proxy https://<proxy-url> <token>
/provider proxy
/model

Keeping a free Render service awake

Render spins a free web service down after 15 minutes with no inbound traffic, and the next request then waits ~30-60s for the cold start. Two layers keep it up 24/7:

1. The server pings itself every 14 minutes (startKeepAlive in server/index.js). Render sets RENDER_EXTERNAL_URL, so this needs no configuration. GET /health reports it:

   { "ok": true, "uptime": 86400, "keepAlive": { "every": "14m", "pings": 102, "last": "…", "error": null } }

   Knobs: KEEPALIVE=0 turns it off (use this on a paid plan, which never sleeps), KEEPALIVE_INTERVAL_MS changes the gap (floor: 60s), KEEPALIVE_URL overrides the target.

2. GitHub Actions pings from outside every 14 minutes (.github/workflows/keepalive.yml). This is the part that matters after a crash or redeploy: a sleeping instance cannot ping itself awake. Set the repository variable PROXY_URL to your service URL (Settings → Secrets and variables → Actions → Variables).

Worth knowing: GitHub's cron is best-effort and can run minutes late, so the in-process ping is the precise one and the workflow is the safety net; GitHub also disables scheduled workflows after 60 days of repository inactivity. Render's free tier allows 750 instance-hours a month and 24/7 is about 730, so this fits one free service — a second would exhaust the quota and suspend both.

Tips

• /model shows models from all connected providers. For Groq, NVIDIA and OpenRouter it lists free, tool-capable chat models only. Free models differ in how reliably they call tools; good picks are Groq openai/gpt-oss-120b, NVIDIA nvidia/nemotron-3-ultra-550b-a55b, and OpenRouter nvidia/nemotron-3-ultra-550b-a55b:free.
• Gemini works on both tiers of the Gemini API with one key from https://aistudio.google.com/apikey (GEMINI_API_KEY, or GOOGLE_API_KEY): the free tier until you enable billing on the Google Cloud project, paid rates after. /model lists every Gemini chat model and marks each one free tier or paid (Gemini 4 Argon and the Pro models are paid only, and on a free key they fail at once with a message saying so). Models that did not answer when checked, such as the Gemini 2.5 family (closed to new keys) and gemini-3.8-flash, are left out; you can still enter one by ID. /cost estimates Gemini usage at paid-tier rates; on the free tier it costs nothing. Gemini is not used as an automatic fallback, since that could spend money on a paid key: add "gemini:gemini-3.6-flash" to fallbackModels to opt in.
• VINAX_<PROVIDER>_BASE_URL overrides an endpoint, for example a self-hosted NIM: VINAX_NVIDIA_BASE_URL=http://localhost:8000/v1. An overridden endpoint needs no API key.
• NVIDIA's model API still advertises models it no longer hosts, so for NVIDIA /model offers a fixed list of the free-endpoint models on https://build.nvidia.com that can drive a coding agent, rather than whatever the API returns. It is in NVIDIA_MODELS in src/providers.js.
• A NVIDIA-hosted model that has gone cold can take ~90s to start answering the first request. VinaX waits up to 3 minutes (esc interrupts) and then switches models; set VINAX_RESPONSE_TIMEOUT_MS to wait longer or VINAX_STALL_TIMEOUT_MS to change the mid-stream limit.
• VINAX_HOME moves the config, session, and history directory (default ~/.vinax).

Development

npm test        # unit + end-to-end tests (also run in CI on Linux, macOS and Windows)

Releasing

npm run release                 # patch, with the changelog drafted from commits since the last release
npm run release -- minor
npm run release -- 2.0.0 "headline for the release commit"
npm run release -- patch --notes "Fixed the picker" --notes "Faster startup"
npm run release -- patch --dry-run   # show what would happen, change nothing
npm run release -- patch --yes       # skip the confirmation prompt

It bumps package.json, writes the CHANGELOG.md section, commits as Release x.y.z: … and pushes. Pushing that version change to main is what triggers .github/workflows/publish.yml, which runs the tests, publishes to npm, tags vx.y.z and creates the GitHub release. The one-time setup is an npm automation token in the repository secret NPM_TOKEN.

The script refuses to run off main, with uncommitted changes, behind origin, with no commits since the last release, or if the tests fail — an npm version cannot be unpublished after 72 hours, so there is no taking a bad release back.

Not every commit needs one. A release per user-visible change is the useful rhythm; README and comment-only commits can ride along with the next one.

Layout

bin/vinax.js        entry point
src/cli.js          REPL, slash commands, headless mode, `mcp` / `doctor` / `update` subcommands
src/tui.js          terminal UI: input box, menus, dialogs
src/ui.js           rendering: markdown, tool calls, diffs, welcome screen
src/theme.js        colors and ANSI-aware text helpers
src/snake.js        the /snake game
src/agent.js        agent loop, system prompt, permissions, plan mode, subagents, checkpoints, compaction
src/providers.js    provider registry and streaming (OpenAI-compatible and native Anthropic)
src/tools.js        built-in tools
src/update.js       version checks and self-update
src/settings.js     settings merge and permission-rule matching
src/hooks.js        hook runner
src/mcp.js          MCP client (stdio and streamable HTTP)
src/extensions.js   subagents, custom commands, skills