How to Contribute to the LoopX Open-Source Project

To contribute to LoopX, select a task from the public CONTRIBUTOR_TASKS.md board, set up your environment using scripts/install-local.sh, create a clean worktree on a codex/<task-id> branch, and submit a focused pull request that excludes private runtime state.

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. The project welcomes contributions but enforces strict boundaries between public code and private runtime state to protect sensitive operational data. Understanding the repository structure and workflow defined in CONTRIBUTING.md ensures your changes are accepted quickly.

Finding Contribution Opportunities

Start your contribution journey by reviewing the contributor task board. The repository maintains a curated list of public, claimable work items at CONTRIBUTOR_TASKS.md【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTOR_TASKS.md】.

If no existing task matches your skills, open a new GitHub issue using the contributor task template referenced in CONTRIBUTING.md. Your issue must describe:

• The specific problem or enhancement
• The intended scope of changes
• The files you plan to modify (e.g., loopx/worker_bridge.py, loopx/visible_multi_agent_launcher.py)
• The validation command you will use to test the change

Wait for maintainer feedback before beginning any large or behavior-changing work to ensure alignment with project goals.

Respecting Public-Private Boundaries

LoopX stores live agent state in directories that must never be committed. According to the source code in CONTRIBUTING.md, you must never publish:

• Private benchmark traces or verifier output
• Raw session logs or credentials
• Internal document links or absolute local paths

Forbidden paths include .loopx/, .codex/goals/, and ACTIVE_GOAL_STATE.md【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md】.

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

Before submitting, run the built-in scan tool to verify 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 these commands to initialize your local 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, install test dependencies and run the full 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

Once you have selected a task, follow the repository's PR hygiene policy from AGENTS.md to ensure clean history.

1. Claim the Issue

Comment on the GitHub issue announcing you are beginning the task.

2. Create a Clean Worktree

Create a dedicated branch named codex/<task-id> using Git worktrees:

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

3. Implement in Small Increments

Typical source locations 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 templates (safe to extend)

Each file is accessible directly via the GitHub UI. For example, loopx/worker_bridge.py is available at https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py.

4. Add Tests

Extend existing smoke tests or create new ones. Use examples/worker-bridge-install-contract-smoke.py as a template for proper test structure. Never embed raw prompts, credentials, or private session data in test fixtures.

Submitting Your Pull Request

Before opening a PR, verify the CONTRIBUTING.md checklist:

1. Link the related issue or task ID in the description
2. Summarize the behavior change and validation steps
3. Keep the PR focused – avoid unrelated formatting or refactors
4. Verify exclusion of private files using git diff --check and loopx check

Maintainers may request a smaller PR if the change mixes unrelated concerns. A complete workflow from clone to submission looks like:

# Clone and install

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh

# Pick a task from CONTRIBUTOR_TASKS.md, then create worktree

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

# Make focused edits (example: improving worker bridge documentation)

sed -i 's/old text/new text/' loopx/worker_bridge.py

# Validate changes

loopx check --scan-path loopx/
ruff check loopx/
pytest -q

# Commit and push

git add loopx/worker_bridge.py
git commit -m "docs: clarify worker bridge contract (ref #12345)"
git push -u origin codex/12345

# Open PR on GitHub linking the original issue

Summary

• Find work in CONTRIBUTOR_TASKS.md or propose new issues using the contributor task template.
• Protect private data by never committing .loopx/, .codex/goals/, or ACTIVE_GOAL_STATE.md; always run loopx check before submitting.
• Set up locally using scripts/install-local.sh and verify with loopx doctor and loopx demo.
• Use clean worktrees on branches named codex/<task-id> as required by AGENTS.md.
• Focus your PRs on single concerns, link related issues, and run ruff, mypy, and pytest before requesting review.

Frequently Asked Questions

How do I know if a task is available for contribution?

Check the CONTRIBUTOR_TASKS.md file in the repository root for a curated list of public, claimable work items. If you want to work on something not listed there, open a new issue using the contributor task template and wait for maintainer approval before starting large changes.

What files should I never modify or commit when contributing to LoopX?

Never commit files containing private runtime state, including the .loopx/ directory, .codex/goals/ folder, or ACTIVE_GOAL_STATE.md. Also avoid including benchmark traces, verifier output, session logs, credentials, or absolute local paths in your commits.

What branch naming convention does LoopX require?

The project requires branches named codex/<task-id> for all contributions. Create these using Git worktrees (git worktree add -b codex/<task-id>) to maintain a clean development environment as specified in AGENTS.md.

How do I validate my changes before submitting a pull request?

Run the comprehensive validation pipeline: ruff check for linting, mypy for type checking, pytest -q for tests, and loopx canary premerge --from-git-diff for pre-merge checks. Always run loopx check --scan-path on your modified files to ensure no private data is included.

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