How to Contribute to LoopX: A Complete Guide for Open-Source Contributors

To contribute to LoopX, select a task from the CONTRIBUTOR_TASKS.md board, respect public-private code boundaries, set up your environment with scripts/install-local.sh, make focused changes on a codex/ branch, and submit a PR that passes loopx check and the maintainer checklist.

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. Learning how to contribute to LoopX requires understanding its unique architecture—particularly the strict separation between public code and private runtime state. This guide walks you through the complete contribution workflow as implemented in huangruiteng/loopx.

Finding a Task to Work On

The recommended entry point is the contributor task board located at CONTRIBUTOR_TASKS.md in the repository root. This curated list contains public, claimable work items matched to various skill levels.

If no suitable task exists, open a new GitHub issue using the contributor task template referenced in CONTRIBUTING.md. Your issue must include:

• Problem description and intended scope
• Files you will modify
• Command you will use to validate the change

Wait for maintainer feedback before starting large or behavior-changing work.

Respecting Public-Private Boundaries

LoopX enforces strict boundaries to prevent accidental exposure of sensitive runtime data. Files in .loopx/, .codex/goals/, and ACTIVE_GOAL_STATE.md must never be committed.

According to CONTRIBUTING.md, you must not publish:

• Private benchmark traces
• Verifier output
• Raw session logs
• Credentials
• Internal document links
• Absolute local paths

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:

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 scripts/install-local.sh to automate environment setup:

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
export PATH="$HOME/.local/bin:$PATH"

Verify your installation:

loopx doctor      # sanity-check the environment

loopx demo        # run a quick demonstration

For comprehensive validation, 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 a Focused Change

Follow this workflow when contributing to LoopX:

1. Comment on the issue to announce you are beginning work
2. Create a clean worktree on a dedicated codex/<task-id> branch as required by AGENTS.md
3. Implement in small increments

Key source locations for core contributions:

File	Purpose
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 or update tests using existing smoke tests as templates. Never embed raw prompts, credentials, or private session data in fixtures.

Submitting a Pull Request

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

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

Maintainers may request a smaller PR if concerns are mixed.

Complete Contribution Example

# 1️⃣ Clone and install

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

# 2️⃣ Pick a task from CONTRIBUTOR_TASKS.md, then comment on the issue

# 3️⃣ Create a clean worktree for the change

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

# 4️⃣ Make a small edit (e.g., improve a docstring)

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

# 5️⃣ Run local checks

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

# 6️⃣ 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

# 7️⃣ Open a PR on GitHub linking the issue

Summary

• Find work in CONTRIBUTOR_TASKS.md or propose via issue template
• Respect boundaries—never commit .loopx/, credentials, or session logs; use loopx check for verification
• Set up locally with scripts/install-local.sh and validate with loopx doctor
• Work cleanly on codex/ branches with focused, test-backed changes
• Submit properly with linked issues, clear summaries, and passing checks

Frequently Asked Questions

What files are considered private and cannot be committed?

Private files include everything under .loopx/, .codex/goals/, and ACTIVE_GOAL_STATE.md, plus any benchmark traces, verifier output, raw session logs, credentials, internal document links, or absolute local paths. The loopx check command scans for these automatically.

How do I validate my changes before submitting a PR?

Run loopx doctor for environment health, loopx check to detect private artifacts, ruff check for linting, mypy for type checking, and pytest -q for tests. The loopx canary premerge --from-git-diff command provides final pre-submission validation.

Can I contribute if no tasks match my skills on the public board?

Yes. Open a new issue using the contributor task template from CONTRIBUTING.md, describing your proposed change, target files, and validation approach. Wait for maintainer approval before starting substantial work.

What branch naming convention does LoopX require?

LoopX requires codex/<task-id> branches created via git worktree add as documented in AGENTS.md. This maintains PR hygiene and separates active worktrees from your main checkout.

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