How to Contribute to LoopX: From Setup to Your First Pull Request

To contribute to LoopX, select a task from the public contributor board in CONTRIBUTOR_TASKS.md, configure your environment using scripts/install-local.sh, and submit changes from a dedicated worktree branch following the strict public-private boundary rules enforced by the loopx check tool.

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. Contributing to this repository requires understanding its unique architecture that separates public code from private runtime state. This guide walks you through the entire contribution workflow according to the standards defined in CONTRIBUTING.md.

Finding Contribution Tasks

The recommended entry point for new contributors is the contributor task board located at CONTRIBUTOR_TASKS.md in the repository root. This curated list contains public, claimable work items organized by complexity and domain.

If the existing board does not match your skills, open a new GitHub issue using the contributor task template referenced in CONTRIBUTING.md. Your issue must describe the problem, intended scope, specific files you plan to modify (such as loopx/worker_bridge.py or loopx/visible_multi_agent_launcher.py), and the validation command you will use to verify the change. Wait for maintainer approval before beginning substantial work.

Respecting Public-Private Boundaries

LoopX maintains strict boundaries between public source code and private runtime state. The contribution guidelines explicitly forbid committing:

• Private benchmark traces
• Verifier output and raw session logs
• Credentials and internal document links
• Absolute local paths
• Runtime state files in .loopx/, .codex/goals/, or ACTIVE_GOAL_STATE.md

Safe contribution surfaces include documentation, examples, smoke tests, CLI diagnostics, schema files, UI code, and sanitized fixtures.

Always run the built-in scan tool before committing to ensure no private artifacts are included:

loopx check \
  --scan-path README.md \
  --scan-path CONTRIBUTING.md \
  --scan-path CONTRIBUTOR_TASKS.md \
  --scan-path docs/ \
  --scan-path examples/

Setting Up Your Development Environment

The repository includes an automation script that installs the package in editable mode and verifies your checkout. Run the following commands to bootstrap your environment:

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
export PATH="$HOME/.local/bin:$PATH"
loopx doctor          # sanity-check the environment

loopx demo            # run a quick demonstration

For comprehensive validation before submitting changes, install test dependencies and run the full quality suite:

python -m pip install -e ".[test]"
python -m ruff check tests loopx/...
python -m mypy
python -m pytest -q
loopx canary premerge --from-git-diff

Making Focused Changes

When you begin work on a task, follow this precise workflow:

1. Comment on the issue to announce you are claiming the task.
2. Create a clean worktree on a dedicated branch named codex/<task-id>, as required by the PR hygiene policy in AGENTS.md.
3. Implement in small increments. Key files for core contributions include:
   • loopx/worker_bridge.py – Core bridge between LoopX runtime and external workers
   • loopx/visible_multi_agent_launcher.py – Launcher for multi-agent simulations
   • loopx/upgrade.py – Upgrade-path logic for runtime versions
   • loopx/status.py – Status-server implementation
   • examples/*.py – Smoke-test and usage examples (safe to extend)
4. Add tests using existing smoke tests like examples/worker-bridge-install-contract-smoke.py as templates. Avoid embedding raw prompts or credentials in test fixtures.

Example workflow for creating a worktree:

git worktree add -b codex/12345 /tmp/codex-12345 main
cd /tmp/codex-12345

# Make your changes here

Submitting Your Pull Request

Before opening a PR, ensure you satisfy the checklist from CONTRIBUTING.md:

• Link the related issue or task ID in the description.
• Summarize the behavior change and validation steps.
• Keep the PR focused—avoid unrelated formatting or refactors.
• Verify no private/runtime files are included by running git diff --check and loopx check.

Maintainers may request that you split large PRs if changes mix unrelated concerns. The repository requires worktrees for isolation, ensuring your codex/<task-id> branch contains only the intended modifications.

Summary

• Find work in CONTRIBUTOR_TASKS.md or propose new tasks via GitHub issues with detailed scope descriptions.
• Respect boundaries by never committing .loopx/, .codex/goals/, or ACTIVE_GOAL_STATE.md; always run loopx check before submitting.
• Configure locally using scripts/install-local.sh and validate with loopx doctor, ruff check, mypy, and pytest.
• Isolate changes in dedicated worktrees on codex/<task-id> branches as mandated by AGENTS.md.
• Target safe surfaces like loopx/worker_bridge.py, examples, and documentation while avoiding private runtime data.

Frequently Asked Questions

How do I choose my first task to contribute to LoopX?

Start by reading CONTRIBUTOR_TASKS.md in the repository root, which contains a curated list of public tasks categorized by complexity. Select an item that matches your familiarity with the codebase—documentation fixes and example updates in examples/ are ideal starting points. If no suitable task exists, create a new issue using the contributor task template and wait for maintainer feedback before coding.

What files should I never commit when contributing to LoopX?

Never commit runtime state directories including .loopx/, .codex/goals/, or the ACTIVE_GOAL_STATE.md file. Additionally, avoid including private benchmark traces, verifier output, raw session logs, credentials, internal document links, or absolute local paths. Use the loopx check command to scan your changes before submission to ensure compliance.

Which source files are safe for first-time contributors to modify?

Safe targets include documentation, the examples/ directory (particularly smoke tests like worker-bridge-install-contract-smoke.py), CLI diagnostics, and UI code. Core implementation files such as loopx/worker_bridge.py, loopx/visible_multi_agent_launcher.py, loopx/upgrade.py, and loopx/status.py are also open for contributions, provided you follow the worktree branching strategy and include appropriate tests.

What is the required branch naming convention for LoopX contributions?

LoopX requires contributors to use the worktree-based workflow specified in AGENTS.md. Create your branch using the format codex/<task-id> (for example, codex/12345) when running git worktree add -b codex/12345. This isolation ensures clean PRs that contain only the specific changes related to your claimed task.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}