Better Agent

Run every coding agent. Keep every session.

Claude, Codex, and Gemini in one local workspace—persistent, inspectable, and available from every trusted screen.

Quick start · Why Better Agent · How it works · Install guide · Extensions

Note

Better Agent is source-available for non-commercial use. See the license.

Quick start

git clone https://github.com/ofekron/better-agent
cd better-agent
./run.sh

The first run initializes dependencies, builds the UI, and guides you through local authentication and network access. See Getting started for prerequisites and platform notes.

Why Better Agent

Stop juggling terminal tabs, provider UIs, hidden logs, and throwaway sessions.

• Every provider, one workspace. Run Claude, Codex, and Gemini side by side. Choose the provider and model per session without changing how you organize or revisit work.
• Work that survives the tab. Detached agents outlive browser disconnects and backend restarts. Return to the complete run and its full trace.
• A team, not a chatbot. Fork sessions, delegate bounded work, run agents in parallel, and orchestrate them headlessly through the SDK and CLI.
• Local and inspectable. Sessions, settings, credentials, project data, live output, tool calls, and file context stay on your machine and remain visible in one history.
• One backend, every trusted screen. Use the same workspace from the browser, desktop app, or mobile app on devices you trust.

Built for real agent work

• Persistent sessions — recover in-flight provider work after restarts and reconcile it into one deduplicated history.
• Offline-first capture — create sessions and queue prompts while the backend is unreachable; sync them after reconnect.
• Project organization — folder trees, tags, session tabs, quick filters, and advanced search across your work.
• Provider-native setup — connect the Claude, Codex, and Gemini accounts and CLIs you already use.
• Multi-agent orchestration — fork, delegate, supervise, and coordinate work across providers.
• Extension platform — add permission-scoped workflows, tools, settings, and UI through signed marketplace or private extensions.

How it works

flowchart LR
    UI[Browser · Desktop · Mobile] <-- REST + WebSocket --> CORE[Better Agent backend]
    CORE --> C[Claude runner]
    CORE --> O[Codex runner]
    CORE --> G[Gemini runner]
    CORE <--> STATE[(Local persistent state)]

Loading

The FastAPI backend is the source of truth for sessions, projects, settings, provider state, and agent output. The React frontend reflects backend snapshots and live WebSocket events. Per-session runners stay detached so work can continue independently of the UI.

Layer	What it owns
Backend	Orchestration, event ingestion, provider runners, authentication, persistence, and recovery
Frontend	Responsive browser, desktop, and mobile interfaces over one reconnecting session stream
Local state	Sessions, traces, settings, credentials, projects, and extension data on your machine

SDK and extensions

The public Integration SDK lives in sdk/better_agent_sdk/. Extensions and external orchestrators run out of process and call authenticated loopback APIs instead of importing backend internals.

Two included extensions demonstrate the model:

• extensions/ask finds the best existing session for a task and continues the work there.
• extensions/session-bridge exposes cross-session search, recall, proposals, and delegation through MCP.

See EXTENSIONS.md to build private or marketplace extensions.

Getting started

Supported hosts: macOS, Linux, and Windows. Authentication uses the native OS credential store. The macOS desktop build is verified; a Windows installer is provided but has not yet been validated on a real Windows host.

On a fresh machine, start with the platform bootstrap:

# macOS
./scripts/bootstrap-macos.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File scripts\bootstrap-windows.ps1

Then run ./run.sh. The backend defaults to port 18765; set BETTER_AGENT_BACKEND_PORT to override it. On first launch, choose local-only or trusted-LAN access and create credentials stored by your OS.

The complete clean-clone, LAN, desktop, mobile, and reset-auth flows are in INSTALL.md.

Developer commands

# Backend with hot reload
cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000

# Frontend
cd frontend
npm run dev

# Headless CLI
cd backend
source .venv/bin/activate
python cli.py -p "do the thing"

# Reset stored credentials
./run.sh --reset-auth

Security

Warning

Better Agent can execute commands, read and write files, invoke provider CLIs, and persist local data. Run it only in trusted environments, keep backups, review tool calls, and never expose the backend to untrusted networks.

Normal API access is credential-gated. Browser clients use a signed session cookie; mobile clients use signed bearer tokens; internal extension and runner routes require a separate loopback token. Public unauthenticated routes are limited to setup, authentication, and served app artifacts.

Read SECURITY.md and DISCLAIMER.md before public or shared use.

Contributing

Read CONTRIBUTING.md before opening a pull request. Integration tests run real provider CLI subprocesses rather than mocks.

Public planning and release policies live in ROADMAP.md and RELEASE.md.

License

Better Agent is source-available for non-commercial use. Commercial use, commercial distribution, hosted offerings, and Better Agent marketplaces require prior written permission from Ofek Ron. It is not OSI-approved open-source software because commercial rights are reserved. See LICENSE.

Additional legal and trust material: DISCLAIMER.md · SECURITY.md · TRADEMARKS · NOTICE

---

One agent in a terminal was never going to be enough.