Vibe

BEAM-native coding agent for Elixir/OTP projects.

Vibe is a terminal/web coding agent that runs as a local OTP application. It includes a TUI, a LiveView web console, persistent sessions, plugins, skills, subagents, and project-aware Elixir eval.

[!WARNING] Vibe is experimental and not production-ready. It can take actions on your machine and talk to external model providers. Use it at your own risk, review changes before applying them, and avoid repositories or machines where unintended agent actions would be costly.

Why Vibe?

Vibe is an experiment in making an agent feel native to the BEAM, rather than wrapping a chat loop around shell commands.

A few things this gives you:

• Elixir eval as the control plane. The agent can use stateful Elixir APIs for commands, storage, search, telemetry, goals, web fetches, Markdown rendering, and custom helpers. The model sees a small tool surface, but the agent still gets a composable interface.
• Stateful work, closer to Livebook. Eval sessions can keep intermediate values around, so the agent can compute something once, inspect it, transform it, and refer back to it later.
• OTP supervision for agent work. Sessions, command jobs, plugin workers, subagents, telemetry, UI state, and storage are supervised processes that can be monitored, cancelled, resumed, and inspected.
• Agents can launch other agents. Subagents get their own sessions and lifecycle, which makes parallel research, background work, and longer workflows easier to model.
• Remote workflows are part of the design. Vibe can use SSH and Erlang distribution so agents can attach to remote nodes and coordinate across machines.
• The system is meant to be customized. Plugins, skills, gateways, semantic events, and eval helpers are extension points. During development, Vibe can run checks, patch code, and hot-reload modules; tools like Reach help keep boundaries clear.

Quick start

Requirements: Elixir 1.19+, Erlang/OTP 27+, and credentials for the model provider you select. Vibe stores local runtime state under ~/.vibe by default.

Package docs are on HexDocs.

Install the released executable from Hex:

mix escript.install hex vibe
export PATH="$HOME/.mix/escripts:$PATH"

Sign in with ChatGPT/Codex OAuth if you use the Codex/OpenAI provider:

vibe --login codex

Start the TUI. If no background server is running, Vibe starts one and attaches to a server-owned session:

vibe

Open the web console for the same background server:

vibe --web
# or type /web in the TUI

Run one non-interactive prompt:

vibe -p "Inspect this project and suggest next steps"

Useful first slash commands:

/help        Show built-in docs
/model       Pick a model and reasoning effort
/sessions    Browse sessions
/new         Start another session
/goal TASK   Set a persistent goal for long-running work
/web         Open the web console

Useful commands

The README only shows the common paths. For the full command reference, run vibe --help or see Mix.Tasks.Vibe.

Attach files with Pi-style @file arguments. Text files become context blocks. Image files are supported by direct prompts and by inline @image references in the TUI/web prompt.

vibe --direct @path/to/image.png "describe this"
vibe --direct "summarize @README.md"
vibe
# then type: compare @lib/foo.ex and @test/foo_test.exs

Server, TUI, and web console

Normal vibe invocations are clients. They connect to a singleton background Vibe server, creating it when needed. This gives a tmux-like workflow:

# terminal 1
vibe

# terminal 2
vibe

# terminal 3
vibe a <session-id>

The Phoenix LiveView web console uses the same session processes as the TUI. vibe --web prints an authenticated URL and opens the browser.

Foreground server commands are available for debugging:

vibe server start --foreground
vibe server restart --foreground

Eval APIs

Most project-aware power is exposed through Elixir APIs available from eval.

Common aliases:

• Cmd — Vibe.Command, supervised shell commands with persisted output
• MD — Vibe.MD, Markdown rendering helpers
• Web — provider-neutral web search/fetch API
• Goal — active session goal controls

Examples:

Cmd.run(["mix", "test"], timeout: 120_000) |> MD.doc()
Vibe.Telemetry.summary()
Vibe.Session.list()
Vibe.Storage.status()
Vibe.Context.recall("sqlite migration", cwd: File.cwd!(), limit: 3)
Web.search!("ecto sqlite fts", num_results: 5, highlights: true) |> MD.doc()

Prefer these APIs over raw System.cmd/3, ad-hoc string formatting, and provider-specific web clients when working inside Vibe.

Storage and search

Runtime state lives under ~/.vibe by default and is stored in local SQLite. Sessions, eval snapshots, memory, telemetry, subagent jobs, and imported history can be searched from the CLI or eval.

vibe storage status
vibe search "sqlite migration" --cwd vibe
vibe storage import pi path/to/pi-session.jsonl --rebuild-fts

See vibe help storage, Vibe.Storage, and Vibe.Storage.Search for migration, FTS, and isolation options.

Subagents, plugins, and skills

Vibe.Subagents creates child Vibe sessions that can be attached like any other session.

{:ok, job} = Vibe.Subagents.start("Review the storage search code")
Vibe.Subagents.await(job.id)
Vibe.Subagents.result(job.id)

From the CLI:

vibe subagents jobs
vibe subagents status <job-id>
vibe subagents result <job-id>

Built-in plugins currently include:

• Rules — loads ~/.vibe/rules/*.md into the system prompt with optional model-glob filtering
• Safety — asks for confirmation before risky commands
• Notify — terminal notifications when tasks complete or fail
• Question — model-facing question tool with selectable options
• WebSearch — provider-neutral web search/fetch through the Web eval alias

Disable plugins in ~/.vibe/agent-profiles.toml:

disabled_plugins = ["notify", "safety"]

Executable skills are trusted local Elixir files discovered from priv/skills, ./skills, ./.vibe/skills, and ~/.vibe/skills.

vibe skill list
vibe skill show <name>
vibe skill apis
vibe skill from-session <session-id> <name>

Providers and models

Vibe passes provider:model strings through ReqLLM. Most providers authenticate with environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, or provider-specific keys. Codex/OpenAI OAuth is available through:

vibe --login codex

Model switching supports fuzzy names and reasoning-effort shorthand:

vibe --model openai_codex:gpt-5.5
/model openai_codex:gpt-5.5:high
/effort medium

Built-in help

API docs are available on HexDocs. Task-focused docs are available from the CLI:

vibe help
vibe help eval
vibe help subagents
vibe help storage

The TUI exposes the same docs through /help.

Install from checkout

Use a checkout when developing Vibe itself or testing unreleased changes:

git clone https://github.com/elixir-vibe/vibe.git
cd vibe
mix deps.get
mix ci

Run from the checkout:

mix vibe
mix vibe --help

Install a local vibe executable:

mix vibe.install

Development

Run the full gate:

mix ci

mix ci runs compile, format check, tests, Credo, Dialyzer, ExDNA, and Reach checks.

Useful checks from Elixir:

report = Vibe.Code.Checks.analyze()
report.ok?
report.failures
Vibe.SelfPatch.deployment_gate()

First principles

1. Few model-facing tools outside; many BEAM powers inside.
2. Prefer eval over shelling out to mix run.
3. Prefer AST-aware search/replace for Elixir syntax.
4. Use LSP for diagnostics/navigation and runtime eval for OTP state.
5. Subagents, plugins, sessions, terminal panes, and background work are OTP processes.
6. UI state is semantic; terminal and web rendering are adapters.
7. Persist durable state with Ecto schemas/migrations and typed semantic events.
8. Self-improvement changes skills/helpers first; runtime core changes need tests and validation.