Simple "Background Agent" Guide

How To
1

Hello, this is made by ChatGPT, and I have read it.
I have not tried Background Agent myself, YET, so I can not answer questions, but I thought that it could be a starting point for learning more and sharing experiences.

:white_check_mark: 1. Prerequisites

  • :link: GitHub repo (public or private).

  • :white_check_mark: GitHub account connected to Cursor with appropriate permissions.

  • :penguin: Project should be able to run in Ubuntu-based container.

  • :file_folder: Optionally include:

    • .cursor/environment.json → installs dependencies.

    • Dockerfile → for full custom environments.

  • :page_facing_up: Project should be in good structure (agent scans and analyzes it).

:rocket: 2. Starting a Background Agent

  • :brain: From Cursor App:

    • Press Ctrl+E (or Cmd+E on Mac).

    • Type your task as a prompt.

    • Select “Background Agent”.

  • :globe_showing_europe_africa: From Web Interface:

  • :speech_balloon: From Slack (optional):

    • If integrated, send prompts to agent bot.

:puzzle_piece: 3. What the Agent Does

  • :hammer_and_wrench: Spawns a remote container in Cursor’s cloud (not GitHub or your machine).

  • :counterclockwise_arrows_button: Clones your GitHub repo into the container.

  • :open_book: Reads the codebase, understands structure and logic.

  • :writing_hand: Executes the prompt:

    • Writes code, refactors, adds tests, edits docs, etc.

  • :repeat_button: Commits to a new branch and pushes to GitHub.

  • :chart_increasing: Updates progress.md (if prompted to).

:brain: 4. Prompting Style

  • :light_bulb: Use clear, intent-based prompts, e.g.:

    • “Implement feature in docs/feature_x.md and update progress.md”

    • “Refactor legacy code in utils/logger.py to follow SOLID principles”

  • :stop_sign: Avoid overly procedural prompts like:

    • “First open X file, then insert Y function…” (Agent figures this out itself).

:scroll: 5. Will the Agent Use My Rules?

  • :check_mark: Yes, if rules are present in:

    • .cursor/rules.json

    • .cursor/config.json

    • .cursor/settings.json

  • :white_check_mark: Agent respects your rules (e.g., DRY, SOLID, SRP) if defined.

  • :cross_mark: Agent does not read your “intentions” unless they’re formalized in those files or reiterated in the prompt.

:test_tube: Pro Tip: Minimal Setup Example

📁 docs/features/login.md:
- Add login page with username & password fields.
- POST to /api/auth/login.
- Display error messages.

📁 .cursor/environment.json:
{
  "packages": ["requests", "flask", "pytest"]
}

📁 .cursor/rules.json:
["Follow DRY", "Use SOLID principles", "Prefer async for I/O-bound ops"]

🔁 Prompt:
Analyze docs/features/login.md, write an implementation plan in the same folder, then implement it and track in progress.md.