OpenFox

Local-LLM-first agentic coding assistant

Autonomous coding agent for local LLMs with contract-driven execution.

_Session — Criteria tracking, tool calls, and streaming responses_ !Session

_Providers — Local LLM backend configuration_ !Providers

_Workflows — Contract-driven execution pipeline_ !Workflows

Quick Start

npm i -g openfox
openfox

On first run, OpenFox automatically detects your local LLM backend (vLLM, sglang, ollama, llamacpp) and configures itself.

What's New in 2.0

• Multi-Turn Agent Engine — Completely rewritten agent loop with EventStore as single source of truth. All modes (builder, planner, verifier, sub-agents, compaction) run through the same unified loop.
• Provider Dialog — Comprehensive provider configuration UI with thinking mode (reasoningEffort), editable kwargs, profile defaults, and preset management.
• Auto-Retry Patterns — Replace the old XML protection toggle with configurable pattern matching. Define your own retry triggers in settings.
• Unified Image Handling — Automatic vision model fallback for non-vision models. Images are described before each turn so any model can "see" them.
• Session Metadata — Unified session_metadata tool replaces separate criterion/todo tools. Interactive criteria editor with CRUD and agent badges.
• Workflow Sub-Groups — Run individual workflow steps in isolation. New code review phase in the build-verify pipeline.
• Parallel edit_file Safety — Per-file mutex prevents race conditions when editing multiple files simultaneously.
• Firefox Support — Custom thin scrollbars with hover behavior, cross-browser compatible.

CLI Commands

# Start server for current project
openfox
Start on custom port
openfox --port 8080
Start without opening browser
openfox --no-browser
Show current configuration
openfox config
Manage LLM providers
openfox provider add      # Add new provider
openfox provider list     # List configured providers
openfox provider use      # Switch active provider
openfox provider remove   # Remove provider

CLI Options

| Option | Description | Default | | --------------------- | --------------------------- | ------------- | | -p, --port | Specify server port | 10369 | | --no-browser | Don't open browser on start | Opens browser | | -h, --help | Show help message | - | | -v, --version | Show version number | - |

Requirements

• Node.js >= 24.0.0
• Local LLM backend with OpenAI-compatible API:

Features

• Plan → Builder Workflow: Interactive task breakdown followed by autonomous implementation
• Contract-Driven Execution: Acceptance criteria serve as immutable contract
• Workflows: Declarative multi-step pipelines (agent turns, sub-agents, shell commands, user gates) with conditional transitions. File format and authoring reference: docs/WORKFLOWS.md
• Iterative Verification: Agent loops until all criteria pass
• LSP Integration: Immediate feedback on code validity
• Real-Time Metrics: Prefill time, generation speed, context usage

Plugins

OpenFox supports plugins loaded from the plugins directory inside its configuration folder. A plugin can contribute LLM providers (auth, transport, presets), model metadata, tools, slash commands, skills, workflow transitions, schema-driven settings, notifications, and declarative UI (header/message/composer actions, session badges, panels).

You can install a plugin from the UI by curated registry entry, GitHub URL, npm package name, or local path — then enable, disable, configure, or remove it without restarting OpenFox.

Default plugin directories:

• macOS: ~/Library/Application Support/openfox/plugins
• Linux: ${XDG_CONFIG_HOME:-~/.config}/openfox/plugins
• Windows: %APPDATA%\openfox\plugins

• To authenticate with a ChatGPT Plus or Pro account, you can install the openfox-chatgpt plugin.
• To authenticate with a Github copilot account, you can install the openfox-github-copilot plugin.
• To authenticate with a Google Antigravity account, you can install the openfox-google-antigravity plugin.
• To authenticate with an X (xAI) SuperGrok subscription, you can install the openfox-xai-supergrok plugin.
• To use free OpenRouter models, you can install the openfox-openrouter-free plugin.
• To use free OpenCode models, you can install the openfox-opencode-free plugin.

Screenshots

_Homepage — Project overview and session history_ !Homepage

_Project Selected — Active session with context stats_ !Project Selected

_Stats — Prefill time, generation speed, token usage_ !Stats

_Terminal — Integrated terminal for running commands_ !Terminal

_Notifications — Event log and system messages_ !Notifications

_Agents — Sub-agent management and execution_ !Agents

_General Instructions — Global custom instructions_ !General Instructions

_Vision Fallback — Image processing configuration_ !Vision Fallback

Environment Variables

| Variable | Default | Description | | ------------------------------------ | -------------------------- | --------------------------------------------------------------- | | OPENFOX_LLM_URL | http://localhost:8000/v1 | LLM API base URL | | OPENFOX_VLLM_URL | — | Deprecated alias for OPENFOX_LLM_URL | | OPENFOX_BACKEND | unknown | Backend type: vllm, sglang, ollama, llamacpp, unknown | | OPENFOX_BASE_PATH | / | Web app base path for subpath deployments (e.g. /openfox/) | | OPENFOX_MODEL_NAME | '' | Override default model name | | OPENFOX_MAX_CONTEXT | 200000 | Max context window in tokens | | OPENFOX_LLM_TIMEOUT | 300000 | LLM request timeout in ms | | OPENFOX_LLM_IDLE_TIMEOUT | 300000 | LLM stream idle timeout in ms | | OPENFOX_PORT | 10369 | Server listen port | | OPENFOX_HOST | 127.0.0.1 | Server bind host | | OPENFOX_PUBLIC_URL | — | Public origin used to build the MCP OAuth redirect URI | | OPENFOX_WORKDIR | cwd | Working directory | | OPENFOX_DB_PATH | ./openfox.db | SQLite database path | | OPENFOX_LOG_LEVEL | info | Log level: debug, info, warn, error | | OPENFOX_REASONING_EFFORT | — | Reasoning effort (e.g. none, low, medium, high) | | OPENFOX_DEV | false | Enable dev mode | | OPENFOX_MODE | production | Force mode: production, development, test | | OPENFOX_SERVICE | false | Run as systemd service (suppresses browser open) | | OPENFOX_GIT_POLL_INTERVAL | 10000 | Git status poll interval in ms | | OPENFOX_DISABLE_AUTO_SESSION_TITLE | false | Disable automatic session title generation |

License

MIT