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

Providers — Local LLM backend configuration

Workflows — Contract-driven execution pipeline

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 <number>	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:
  • vLLM
  • sglang
  • ollama
  • llamacpp

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

Authoring guide: docs/PLUGINS.md — working reference plugin in examples/hello-plugin.

• 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

Project Selected — Active session with context stats

Stats — Prefill time, generation speed, token usage

Terminal — Integrated terminal for running commands

Notifications — Event log and system messages

Agents — Sub-agent management and execution

General Instructions — Global custom instructions

Vision Fallback — Image processing configuration

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