Vibe Codr

vibe-codr

[](https://github.com/robzilla1738/vibe-codr/actions/workflows/ci.yml) [](https://www.npmjs.com/package/vibe-codr) [](LICENSE) [](https://buymeacoffee.com/robcourson)

A model-agnostic CLI coding agent for the terminal — in the class of Claude Code / Codex / opencode, but able to drive coding and agentic tasks on any model: local models via Ollama and LM Studio, aggregators (OpenRouter, Fireworks, Together, Baseten, Hugging Face), and first-party providers (OpenAI, Anthropic, Google Gemini, Meta Muse Spark, Z.ai/GLM, Moonshot/Kimi, Alibaba/Qwen, DeepSeek, xAI/Grok, Groq, Mistral, Cerebras, Perplexity, MiniMax) — plus OpenAI Codex via your codex login session and a generic custom provider for any OpenAI-compatible endpoint (your own base URL + key). Model context windows, pricing, and capabilities come live from models.dev (24h cache; /models refresh to force the latest), with a small published fallback for brand-new APIs not yet in the catalog (e.g. Meta Muse Spark 1.1).

> Status: feature-complete. Multi-provider agent loop, live model catalog, > plan / execute / yolo modes (Shift+Tab to cycle) with a permission layer, a > live task list, an observable prompt queue, an interactive > slash-command menu, skills / plugins, /goal + /loop, checkpoints/undo, > self-verify, cache-aware cost tracking, and session persistence with > context-aware compaction. On top of that: > > - Long-term memory — hybrid recall (BM25 + optional on-device semantic > embeddings, fused with reciprocal-rank fusion) over saved facts and past > sessions, a deduplicating save_memory write-path with a user scope that > grows the always-injected global USER.md, and default-on > proactive recall + cross-session digests (digests only for interactive > sessions — headless -p runs never pay an extra call). Fully offline; degrades to lexical > when no embedder is present. > - Engine-owned build intelligence — deterministic repo recon (your > real build/typecheck/test/lint commands, injected into every agent — no > guessing), a parsed run_check (PASS 142/142, not log spew), an > automatic green-gate after mutating turns with bounded fix rounds, > green checkpoints (commit-on-green that never touches your branch), > an adversarial diff review + deterministic stub scan, optional > browser verification (screenshot + click every control, flag dead > ones), and multi-language diagnostics in the loop on every edit — > in-process TypeScript plus an LSP client that lazy-spawns whatever server > is on your PATH (pyright, gopls, rust-analyzer, clangd, jdtls, ruby-lsp, …), > deadline-bounded so a slow server never wedges an edit and advisory-only so a > crash degrades to nothing, never a false "clean". > - Multi-agent orchestration — parallel subagents with exclusive per-file > write ownership, a typed coordination blackboard, a tree-global > adaptive concurrency limiter, and a default-ON deterministic task-DAG > scheduler (spawn_tasks) with structured handoffs, a read_report > tool, model tiers (cheap/strong), executable verify→retry against the > real checks, git-worktree isolation for parallel writers (opt-in > best-of-N ensembles), a journaled resume, and live per-child activity — > plus subagent continuation (continue_subagent resumes a finished child's > full context), schema-validated structured output (an outputSchema the > child's answer must satisfy, or it returns the errors — never a fabricated > object), and detached background spawns (detach:true + check_task). > - Research — keyless web search that fans out across DuckDuckGo + Bing > and quality-ranks the deduped merge (TinyFish optional), with deep-mode > passage enrichment (fetches the top pages and quotes dated passages), > zero-result query reformulation, a bounded crawl_docs site > crawler, a per-session source ledger with [n] citations (/sources), > a ranked import-graph repo_map, and hardened webfetch (SSRF-guarded > with DNS-rebinding-safe IP pinning, per-redirect revalidation, > charset-aware markdown extraction, paywall-shell detection, Wayback > recovery, PDF extraction with a deflate-bomb guard, cache-through > with request coalescing). > - Safety — a glob-based allow/deny/ask permission layer (deny is an > absolute kill-switch; rules match every equivalent path spelling) with, > underneath it, opt-in OS sandboxing — a macOS Seatbelt / Linux > bubblewrap backstop that confines writes to your workspace and can cut > network, with a fail-closed dangerouslyUnsandboxed escape hatch. > - MCP — stdio + Streamable-HTTP/SSE transports, tools, resources, > prompts, OAuth 2.1, and auto-reconnect + tools/list_changed. > - Planning — an interactive plan-approval modal (accept & execute, > revise, or keep planning) that seeds the task list from the plan. > - Extensibility — declarative shell/HTTP hooks, project + global > skills/commands, and per-agent tool allowlists. > - Ships as a product — prebuilt standalone binaries (darwin/linux × > arm64/x64, checksummed) and an npm/bun package, a tag-driven release > pipeline, vibe upgrade + a quiet opt-out update check, and crash > visibility (redacted crash log + terminal restore, no telemetry). > > A full slash-command surface (/status /cost /config /diff /recall > /mcp /review /doctor /export …) makes every setting and bit of session > state reachable. All covered by 900+ tests (including mock-model integration > tests of the agent loop with zero network) plus a TUI render smoke test and a > compiled-binary check. > > The terminal command is vibecodr (vibe works as an alias).

Screenshots

An opencode-inspired terminal UI on vibe-codr's own engine, with a deliberate color language: a near-black graphite background with filled panel cards and a thin left rail on every block (no box-drawing borders — they gap into dashes on terminals with line spacing). The chrome is white-first (opencode's neutral scale): the VIBE CODR wordmark, panel titles, the user-message rail, the active task/step, and the input caret all read in the body white, while a royal violet (#8b5cf6) is saved for the few emphasis moments — the selected menu row's solid band (dark text on it), menu section headers, and markdown headings. The input's mode label, rail + caret (AGENT ❯ in the accent · PLAN ❯ green · YOLO ❯ red) make switching mode unmistakable without repainting the screen. Swap the accent in one word — /accent blue, or purple, orange, ember, amber, green, teal, violet, rose, white, or any /accent — the swatch submenu previews each hue live, and the wordmark fade, markers, and input rail all follow it (/theme opencode keeps the classic peach look). The other colors are purely functional — green/red on diffs, amber on warnings, and one calm muted tone for the tool-step / subagent rails. The layout is a single, centered chat column (ChatGPT-style): it fills a narrow terminal and centers on a wide one, with no sidebar and no top header. A fresh screen shows a centered VIBE CODR wordmark; once you start, the column is the scrolling transcript, the live status — the plan's task list and live subagents (one tidy line each, tap to expand) — in panels above the input, and the input itself: a raised filled block with the mode-hued rail. All the details sit under the input — cwd · git, then model · changed-files · context · cost, plus key hints and the goal. Each user turn sits in a filled card on the accent rail (tap your message to fold the whole exchange under it), with the calm step rails and the input aligned on one left edge; assistant replies render as real Markdown — prose as Markdown, with headings in the signature violet, blockquotes with a rail bar, and code blocks + tables as clean native primitives (aligned columns, accent header row); tool calls read as a distinct icon + action ($ bash, → read, ← edit, ✱ glob/grep, ◈ websearch, ± git…) and condense to one line you click to expand, while edits fold into a single diff row with the hunk shown beneath it and search steps expand to clean source cards; a rainbow braille spinner (hue-cycling — the "model is thinking" signature) shows live work; the slash menu docks flush to the input as one connected control and drills into rich submenus (a searchable model picker, clickable toggles).

| Chat + tool calls | Live diff | |---|---| | | |

| Plan mode | Task list + subagents panels | |---|---| | | |

| Permission card | Slash-command menu | |---|---| | | |

| /accent orange — one word recolors the chrome | The /accent swatch submenu | |---|---| | | |

| Wide terminal — a session card (the block wordmark over dir · model · git · usage), Tasks, Subagents, and reasoning-only Thinking move to a right sidebar (tool work stays in the chat) | |---| | |

| Ported classic themes (/theme tokyonight, catppuccin, gruvbox, …) | |---| | |

Regenerate with bun packages/tui/scripts/screenshot.ts docs/screenshots (renders the real OpenTUI app and rasterizes its actual cell grid — bundled Playwright Chromium; pixel-for-pixel what the live UI paints).

Stack

• Runtime: TypeScript + Bun (workspaces + Turbo).
• Models: Vercel AI SDK v5 (streamText + tool() +

stopWhen: stepCountIs) as a unified, always-current provider abstraction.

• Catalog: live provider /v1/models merged with the

models.dev capability/pricing catalog — never hardcoded.

• TUI: OpenTUI (Solid) for the

interactive UI, with a guaranteed readline + headless fallback.

Architecture

A hard core/TUI boundary: the engine emits a typed UIEvent stream and accepts EngineCommands; no UI type leaks into core, so the UI is swappable and the engine is fully testable headless.

| Package | Owns | |---|---| | @vibe/shared | Contracts: UIEvent, Message/Part, ToolDefinition, EngineClient, errors, logger | | @vibe/config | Zod config schema, file discovery + deep-merge, auth resolution | | @vibe/providers | ProviderRegistry, resolveModel, CatalogService (models.dev + /v1/models) | | @vibe/tools | Built-in tools with readOnly flags + the AI-SDK tool() adapter / Toolset | | @vibe/core | Agent loop (Session.run), mode gating, subagent fork, event bus, Engine | | @vibe/plugins | HookBus, PluginApi, slash-command + skill runtimes; config hooks accept stdout logs only before a final-line JSON directive | | @vibe/tui | OpenTUI app + headless/REPL renderers | | @vibe/cli | bin/vibe entrypoint (argv, config, headless -p vs TUI) |

Install

Two channels — pick one:

Standalone binary (no runtime to install). Grab the build for your platform from the latest release, verify it against SHA256SUMS, then drop it on your PATH:

# macOS arm64 shown; swap in darwin-x64 / linux-x64 / linux-arm64
curl -sSL -o vibecodr https://github.com/robzilla1738/vibe-codr/releases/latest/download/vibecodr-darwin-arm64
curl -sSL -o SHA256SUMS https://github.com/robzilla1738/vibe-codr/releases/latest/download/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing   # verify before trusting the binary
chmod +x vibecodr && sudo mv vibecodr /usr/local/bin/

npm / bun (requires Bun ≥ 1.2 on your PATH — vibe-codr runs on the Bun runtime):

bun add -g vibe-codr        # or: npm install -g vibe-codr
vibecodr                    # `vibe` is an alias

Provider SDKs, the rich TUI (OpenTUI), MCP, and on-device embeddings are declared as optional dependencies, so the install pulls what it can and the CLI degrades gracefully when one is missing.

Windows — native Windows support is experimental and currently untested (no maintainer runs Windows yet; the CI Windows job is advisory, not a merge gate). A native vibecodr-windows-x64.exe is published on the releases page, but the recommended path is WSL2: inside your WSL distro use the linux-x64 binary or bun add -g vibe-codr and run it as an ordinary Linux install. One caveat to know before running the native .exe: the OS sandbox is unavailable on native Windows. There is no Seatbelt/bubblewrap backstop there — resolveSandboxPolicy reports available:false and commands run unsandboxed, so the glob-based permission layer is the only enforcement layer on native Windows. WSL2 restores the Linux bubblewrap sandbox (when bwrap is installed and unprivileged user namespaces are enabled).

Upgrade — vibe upgrade prints the right steps for how you installed (a bun add -g line for the package channel, the Releases URL for the binary):

vibe upgrade

Update check — the interactive CLI does a quiet, cached (24h) check for a newer release at startup and prints a one-line hint when one exists. It sends no user data. Turn it off with update.check: false in config, or VIBE_NO_UPDATE_CHECK=1.

Quick start

bun install
# Install the providers you'll use + the rich TUI (optional peer deps):
bun add -D @ai-sdk/anthropic @ai-sdk/openai @opentui/core @opentui/solid solid-js
bun link                      # makes `vibecodr`/`vibe` available on your PATH

# interactive — on first run, a guided setup lets you pick a provider
# (Anthropic, OpenAI, Ollama Cloud, …), keys you already have in your env are
# auto-detected, and it fetches the live model list so you just pick one.
# Saved to ~/.config/vibe-codr/config.json. Re-run it anytime with `vibe setup`.
vibecodr

# one-shot (headless / pipeable)
vibecodr -p "list the TS files and read package.json" \
  --model anthropic/claude-opus-4-8

# machine-readable output (for scripting) and prompt-from-stdin
vibecodr -p "summarize this" --output-format json
cat task.md | vibecodr -p -            # read the prompt from stdin
cat task.md | vibecodr -p ""           # empty -p also reads stdin (no onboarding)
# Headless exits non-zero on engine error, so `vibecodr -p … && next` is safe in CI.

# other entry points
vibecodr setup                # (re)run the guided provider/model setup (alias: login)
vibecodr models               # list models for configured providers
vibecodr --continue           # resume the most recent session
vibecodr --resume         # resume a specific session

# (without linking, run from source: `bun packages/cli/bin/vibecodr.ts ...`)

Ollama Cloud (subscription)

Run big open models on ollama.com with your subscription — no local GPU:

export OLLAMA_API_KEY=...      # from https://ollama.com/settings/keys
vibecodr setup                 # pick "Ollama Cloud" (it's preselected when the key is set)
# or skip setup and go straight in:
vibecodr --model ollama/gpt-oss:120b

With a key set, vibecodr automatically targets https://ollama.com/v1. Run vibecodr models to list the exact ids your subscription exposes (e.g. ollama/glm-5.2, ollama/kimi-k2.7-code, ollama/deepseek-v4-pro, ollama/gpt-oss:120b).

OpenAI Codex (reuse your ChatGPT login)

If you've logged in with the official Codex CLI (codex login), vibecodr reuses its credentials — no API key to paste:

codex login                    # once, with the official OpenAI Codex CLI
vibecodr setup                 # pick "OpenAI · Codex (ChatGPT login)" — it's auto-detected
vibecodr --model codex/gpt-5.3-

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [robzilla1738](https://github.com/robzilla1738)
- **Source:** [robzilla1738/vibe-codr](https://github.com/robzilla1738/vibe-codr)
- **License:** MIT
- **Homepage:** https://github.com/robzilla1738/vibe-codr

Install and usage instructions live in the source repository linked above.