background-agents: An Open-Source System for Background Coding Agents

Introduction

background-agents is an open-source background agents coding system inspired by Ramp's Inspect. It provides a hosted background coding agent capable of working on tasks in the background, accessing full development environments (Node.js, Python, git, browser automation, VS Code), and connecting from various platforms like web UI, Slack, GitHub PRs, and Linear issues. The system supports multiplayer sessions for real-time collaboration, creates PRs with proper commit attribution, and can run on a schedule or be triggered by webhooks. It also offers flexibility with your choice of AI model, including Anthropic Claude, OpenAI Codex, xAI Grok, and OpenCode Zen.

It is important to note that this system is designed for single-tenant deployment only, where all users are trusted members of the same organization with access to the same repositories.

Installation

To get started with background-agents, you should refer to the official documentation for detailed setup instructions.

For a practical setup guide covering local, contributor, and deployment paths, begin with the SETUP_GUIDE.md.
For specific deployment instructions, consult GETTING_STARTED.md.
To understand the architecture and core concepts, read HOW_IT_WORKS.md.

Examples

background-agents offers a rich set of features that demonstrate its capabilities:

Fast Startup: Sessions start almost instantly thanks to filesystem snapshots, pre-built images, and proactive warming.
Multi-Repository Sessions & Environments: Work across several repositories in a single sandbox, creating ad-hoc sets or saving named environments with their own secrets and prebuilt images.
Multiplayer Sessions: Multiple users can collaborate in the same session, with presence indicators and prompt attribution in git commits.
Commit Attribution: Commits are attributed to the user who sent the prompt, ensuring proper authorship.
Multi-Provider Model Support: Choose from various AI models, including Anthropic, OpenAI, xAI, and OpenCode Zen, with per-session reasoning effort controls.
Client Integrations: Interact with agents from your team's existing workflows via a Web UI, Slack Bot, GitHub Bot, Linear Bot, or custom Webhooks.
Automations: Schedule recurring tasks with cron, react to Sentry alerts, or trigger sessions from inbound webhooks, supporting multi-repo fan-out.
Sandbox Environment: Every session runs in an isolated sandbox with a full development environment, including Node.js, Python, git, browser automation, VS Code (optional), web terminal, and port tunneling.
Child Sessions: Agents can decompose work into parallel child sessions, allowing for concurrent execution on separate branches.
Repository Lifecycle Scripts: Define optional .openinspect/setup.sh for provisioning and .openinspect/start.sh for runtime startup, enabling custom environment setup.

Why Use background-agents?

background-agents empowers development teams to significantly enhance productivity and collaboration. By automating repetitive coding tasks and integrating seamlessly with existing tools like GitHub, Slack, and Linear, it frees up developers to focus on more complex challenges. Its support for multiple AI models provides flexibility, while features like fast startup, multiplayer sessions, and full development environments ensure an efficient and robust workflow. The system's single-tenant design, coupled with deployment recommendations, offers a secure environment for trusted organizational use. Whether you need to run scheduled tasks, automate code reviews, or enable real-time coding collaboration, background-agents provides a powerful and adaptable solution.