# PaneVibe documentation An IDE for coding agents with real terminal sessions, an editor, worktrees, and a built in browser. ## [Getting started](https://panevibe.com/docs/getting-started/) Clone PaneVibe, run one setup command, and open your first real agent CLI in a PTY. Markdown: https://panevibe.com/docs/getting-started.md ## [Terminal-first architecture](https://panevibe.com/docs/terminal-first/) The PTY is the source of truth. Chat is a readable projection with the raw terminal always available. Markdown: https://panevibe.com/docs/terminal-first.md ## [Agents and models](https://panevibe.com/docs/agents-and-models/) Use native agent CLIs when they exist, or connect any OpenAI-compatible endpoint for direct model access. Markdown: https://panevibe.com/docs/agents-and-models.md ## [Browser and MCP](https://panevibe.com/docs/browser-and-mcp/) Six built-in MCP servers and two deliberately different browser surfaces ship inside the binary. Markdown: https://panevibe.com/docs/browser-and-mcp.md ## [Security and privacy](https://panevibe.com/docs/security-and-privacy/) Localhost transport, no telemetry, OS-encrypted credentials, and explicit workspace permissions. Markdown: https://panevibe.com/docs/security-and-privacy.md ## [Configuration](https://panevibe.com/docs/configuration/) Everything has a working default; environment variables are escape hatches rather than a required setup surface. Markdown: https://panevibe.com/docs/configuration.md ## [Contributing](https://panevibe.com/docs/contributing/) Keep changes inside one concern, preserve the PTY execution model, and run the focused release gates. Markdown: https://panevibe.com/docs/contributing.md # Getting started Clone PaneVibe, run one setup command, and open your first real agent CLI in a PTY. Canonical: https://panevibe.com/docs/getting-started/ Source: https://github.com/brandonmlicea/panevibe ## Requirements Install Node.js 20.10 or newer before you begin. Node 22 is recommended. The setup script detects your operating system and handles the remaining toolchain, including Rust when it is missing. The packaged desktop app uses Tauri 2 on Windows, macOS, and Linux. ## Build from source The setup script installs workspace dependencies, builds the shared packages, frontend, and Rust binary, prepares the browser engine, then performs a real MCP handshake before reporting success. `Terminal` ```bash git clone https://github.com/brandonmlicea/panevibe.git cd panevibe node scripts/setup.mjs ``` ## Useful setup modes - --no-install checks the machine without changing it. - --debug produces a faster development build. - --skip-browser leaves the browser engine untouched. - The setup command is idempotent and safe to run again. `Terminal` ```bash node scripts/setup.mjs --no-install node scripts/setup.mjs --debug node scripts/setup.mjs --skip-browser ``` ## Open your first pane PaneVibe bundles no model vendor. Install the agent CLI you already use, open a workspace, and choose a pane type. A Codex pane launches the native Codex TUI; a default chat pane launches PANEVIBE_IDE_CLI, Claude Code, or your platform shell in that order. `Agent CLIs` ```bash npm i -g @anthropic-ai/claude-code npm i -g @openai/codex ``` --- # Terminal-first architecture The PTY is the source of truth. Chat is a readable projection with the raw terminal always available. Canonical: https://panevibe.com/docs/terminal-first/ Source: https://github.com/brandonmlicea/panevibe ## The one decision A coding CLI is a terminal program: ANSI escapes, cursor movement, raw-mode input, resize signals, and process signals are part of its behavior. PaneVibe runs the real binary in a real pseudo-terminal instead of rebuilding the agent loop behind a request API. The byte stream is parsed into semantic chat events for readability, while the raw stream remains one keystroke away. A parser gap can be cosmetic, but it cannot remove the underlying capability. ## System shape - IDE surface: Next.js and React render chat, terminal, editor, browser, files, diffs, and worktrees. - Agent harness: local transport connects PTYs, parsing, policy, indexing, and browser control. - Real CLI: Claude, Codex, a shell, or another executable runs as its own process in its own working directory. `Architecture` ```text IDE surface → agent harness → real CLI in a PTY code + browser context + actions source of truth ``` ## Fault boundaries Every pane is an independent process with its own working directory, history, and lifecycle. Closing one pane tree-kills only that process tree. Panics unwind rather than abort so one command failure does not take down every window. --- # Agents and models Use native agent CLIs when they exist, or connect any OpenAI-compatible endpoint for direct model access. Canonical: https://panevibe.com/docs/agents-and-models/ Source: https://github.com/brandonmlicea/panevibe ## CLI providers CLI panes are the primary path. Authentication remains inside the CLI. PaneVibe does not proxy or reinterpret the agent's own session, tools, resume behavior, or credentials. - Claude Code powers the default chat pane when it is on PATH. - Codex gets a dedicated pane so its live TUI redraws and caret remain native. - Any shell remains a first-class pane rather than a degraded fallback. ## API and local providers Settings → Providers accepts OpenAI, Gemini, Grok, Mistral, and custom OpenAI-compatible chat-completions endpoints. Custom endpoints cover Ollama, vLLM, LM Studio, llama.cpp, Together, DeepInfra, Groq, and private gateways. Tool calling is negotiated per provider. Set it to off for endpoints that reject a tools field; the pane falls back to plain completion instead of failing. ## Bounded delegation The built-in assist server lets a primary agent delegate self-contained work to a cheaper secondary model. The helper receives no tools of its own, keeping the subtask bounded while preserving the main agent's context for harder decisions. --- # Browser and MCP Six built-in MCP servers and two deliberately different browser surfaces ship inside the binary. Canonical: https://panevibe.com/docs/browser-and-mcp/ Source: https://github.com/brandonmlicea/panevibe ## Built-in MCP servers PaneVibe ships terminal, browser, notepad, library, assist, and a Playwright-backed Thorium engine as dependency-free JavaScript embedded in the Rust binary. They are materialized on demand, with no npx or network install step. User MCP servers merge alongside the built-ins. Pane configuration must not replace the user's own MCP config. ## Browser inside the IDE The agent harness docks a browser beside the workspace. The agent can navigate, inspect, and act through the browser MCP while you watch in the same window. --- # Security and privacy Localhost transport, no telemetry, OS-encrypted credentials, and explicit workspace permissions. Canonical: https://panevibe.com/docs/security-and-privacy/ Source: https://github.com/brandonmlicea/panevibe ## Local by default - The bridge binds to 127.0.0.1 on a random free port. - No analytics, crash reporting, license checks, account, or phone-home path ships in the desktop app. - Provider calls go directly from your machine to the endpoint you configured. - Credentials are encrypted at rest with operating-system-native storage. ## Workspace permissions Project workspaces default to write access; business document workspaces default to read. Read-only sessions reject known write commands before the CLI sees them and can be reinforced by CLI policy and a read-only filesystem mount in runner mode. There is no in-session unlock. Reopen the workspace with a changed permission to make escalation explicit. ## Report vulnerabilities privately Do not open a public issue for a vulnerability. Follow SECURITY.md in the source repository for the current private reporting channel. --- # Configuration Everything has a working default; environment variables are escape hatches rather than a required setup surface. Canonical: https://panevibe.com/docs/configuration/ Source: https://github.com/brandonmlicea/panevibe ## Core variables - PANEVIBE_IDE_CLI overrides the binary launched by a default chat pane. - PANEVIBE_IDE_HOME_OVERRIDE moves worktrees and harness state. - PANEVIBE_IDE_POLICY_DIR points to custom tool-permission policies. - PANEVIBE_MCP_CONFIG merges additional MCP servers into every pane. - PANEVIBE_NO_MEM_GUARD disables the low-memory load shedder. - PANEVIBE_NO_FREEZE_WATCHDOG disables compositor self-healing. ## Browser variables - PANEVIBE_PW_EXECUTABLE selects a Chromium binary. - PANEVIBE_PW_HEADLESS enables headless mode. - PANEVIBE_PW_USER_DATA_DIR selects the persistent profile directory. - PANEVIBE_PW_MAX_PAGES, PANEVIBE_PW_RENDERER_LIMIT, and PANEVIBE_PW_JS_MAX_MB tune safety bounds. - PANEVIBE_PW_2CAPTCHA_KEY is empty by default; no CAPTCHA key ships with the source. ## Where state lives Application data follows the native platform location. Worktrees and engineering-harness state live under ~/.panevibe unless PANEVIBE_IDE_HOME_OVERRIDE changes the root. Transient MCP configuration is written under the operating system temp directory. --- # Contributing Keep changes inside one concern, preserve the PTY execution model, and run the focused release gates. Canonical: https://panevibe.com/docs/contributing/ Source: https://github.com/brandonmlicea/panevibe ## Development loop `Terminal` ```bash npm install npm run desktop:fast -- --launch npm run typecheck npm run scan:secrets ``` ## Boundaries worth preserving - The PTY remains the source of truth; do not create a parallel agent execution path. - A new capability gets its own Rust module or React component. - Unbounded filesystem, process, and network work stays off the async runtime and behind timeouts. - Panics unwind instead of aborting the whole desktop process. - Do not add analytics, crash beacons, license checks, or an unrequested network path. ## Before opening a change `Release checks` ```bash npm run typecheck npm test node scripts/scan-secrets.mjs cd desktop/src-tauri && cargo check --locked --all-targets ```