Show HN: Python-based background agents for software dev

• What is Cairn?
  • Model Support
• Quick Start
  • Installation
• Architecture Overview
• Development
  • Project Structure
  • Contributing
• License
• Roadmap

Cairn is a simple open-source background-agent system. Think Codex, Jules, or Cursor Background Agents, but open sourced! You can run Cairn locally, connect it to your repos, use your favorite LLM and execute fullstack tasks, 100% in the background. Save time for the things you want to do, not the boring stuff!

1. Clone or fork the repository

   git clone [email protected]:cairn-dev/cairn.git cd cairn

2. Install dependencies

   Using venv (recommended, but can use conda or system-wide installation as well)

   python -m venv cairn-env source cairn-env/bin/activate # On Windows: cairn-env\Scripts\activate pip install -r requirements.txt

3. Set up github access

   Cairn uses a self-hosted GitHub app (you own and control it) with read/write permissions to edit your repositories.

   Step 1: Create your GitHub App

   For Personal Account:

   1. Navigate to GitHub Apps Settings
   2. Click "New GitHub App"

   For Organization:

   1. Navigate to https://github.com/organizations/YOUR-ORG-NAME/settings/apps
   2. Replace YOUR-ORG-NAME with your actual organization name
   3. Click "New GitHub App"

   App Configuration:

   • App Name: "Cairn Agent for [Your-Username]" (must be globally unique) • Description: "Cairn automated development agent" • Homepage URL: https://try-cairn.com (or leave blank) • Webhook URL: Leave blank • Webhook Secret: Leave blank • ✅ Disable "Active" checkbox under Webhooks Repository Permissions: • Contents: Read & write ✅ • Pull requests: Read & write ✅ • Metadata: Read ✅ (auto-selected) Where can this GitHub App be installed? • Select "Only on this account" ✅
   4. Click "Create GitHub App" to finish
   Step 2: Gather your credentials and install the app (3 required values)
   • App ID: Copy from app settings page (displayed at top) • Private Key: Generate and download .pem file → save to cairn project root • Installation ID: Click "Install App" → Select repositories → Install Then check browser URL: https://github.com/settings/installations/[INSTALLATION_ID]
   Step 3: Note your credentials for .env configuration

   You'll need these three values for your .env file in the next step:

   • App ID: Your GitHub App ID
   • Installation ID: From the installation URL (see step 2)
   • Private Key Path: Path to your downloaded .pem file
   ⚠️ Security: Keep your .pem file secure and never commit it to version control 📖 Reference: https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app

4. Configure environment variables

   # Copy the example environment file cp .env.example .env

   Edit your .env file with the following configuration:

   # GitHub App credentials (from Step 3 above) GITHUB_APP_ID=your_app_id_here GITHUB_INSTALLATION_ID=your_installation_id_here GITHUB_PRIVATE_KEY_PATH=your_private_key_file.pem # LLM API keys. Each is optional, add the ones you want to use. ANTHROPIC_API_KEY=your_anthropic_api_key_here OPENAI_API_KEY=your_openai_api_key_here GEMINI_API_KEY=your_gemini_api_key_here # Connected repositories - Format: "owner/repo-name,owner/repo-name" (comma-separated, no spaces) # Examples: CONNECTED_REPOS="john-doe/my-frontend,john-doe/my-backend" # Or for a single repository: # CONNECTED_REPOS="mycompany/main-project"

Then, navigate to http://0.0.0.0:8000 in your browser.

1. Access the interface (via http://0.0.0.0:8000)
2. Select an agent type (Fullstack Planner, PM, or SWE)

• SWE: recommended for simple self-contained subtasks. Output is a branch with the changes.
• PM: recommended for slightly more complex subtasks. Delegates software changes to SWE. Output is a PR detailing the changes.
• Fullstack Planner: recommended for fullstack or multi-step tasks. Output is a list of subtasks that can be ran in parallel, and who will communicate if necessary on cross-subtask code.

3. Choose target repositories from your connected repos
4. Describe your task in natural language
5. Monitor progress through real-time logs and status updates

Cairn maintains local configuration and memory through a .cairn/ directory that gets automatically created in your project root when you run tasks locally.

.cairn/settings.json allows you to define custom rules that agents must follow:

.cairn/memory/<repo-name>.json stores persistent memory for each repository. This is generated by the agents. In practice, this saves money/time by skipping certain tool calls the agents use to figure out the structure of your repo.

Cairn uses three simple (and hierarchical) agents to accomplish tasks. We call them SWE, PM and FULLSTACK PLANNER. The SWE is specialized at making code changes. The PM is specialized at delegating specific instructions to the SWE, checking the SWE changes, tracking dependencies, and creating a pull request. The FULLSTACK PLANNER is specialized at breaking down a large task into multiple subtasks that can run in parallel, and for orchestrating communication between any related parallel tasks.

For example, if you assign a task like "retrieve user metrics from our supabase backend, and display this in a chart in the frontend" to the FULLSTACK PLANNER, a single agent could implement both parts itself, but this is slower (and contextually worse) than having one agent implement the backend and another implement the frontend. We parallelize this process and allow the agents working on the frontend and backend to communicate with each other to ensure consistent API routes and data formats!

We use subprocess to spawn multiple parallel processes, SQLite as a persistent database, and FastAPI to provide a simple frontend.

We welcome contributions from the community! Please check our Contributing Guide for more information on how to get started.

We provide several issue templates to help you report bugs, request features, or suggest documentation improvements:

• 🐛 Bug Report
• 💡 Feature Request
• 📖 Documentation

When submitting a pull request, please use our Pull Request Template to ensure your contribution includes all the necessary information.

This project is licensed under the MIT License - see the LICENSE file for details.

• ✅ Multi-agent task execution
• ✅ GitHub integration
• ✅ Simple web interface
• ✅ OpenAI, Anthropic, & Gemini Support

• Agent-runnable code environments
• Pausable, playable, restartable tasks
• Custom diff-application models
• Embedding search support (auto-updating with github webhooks)
• and more...