heavy-coder
Adaptive multi-agent coding-team profile for GitHub issue-to-PR work. It routes hard tasks into candidate builders, critics, synthesizers, verifiers, state machines, and fail-closed merge policy.
repocodegraphtheory/heavy-coderdocshttps://graphtheory.xyz/heavy-coder/statusoriginal GraphTheory workaudiencedevelopers and maintainersoverview
Adaptive multi-agent coding-team profile for GitHub issue-to-PR work. It routes hard tasks into candidate builders, critics, synthesizers, verifiers, state machines, and fail-closed merge policy.
interactive codingRun heavy-coder chat from a repository. Non-trivial tasks are routed through team mode before implementation.issue to PRUse the heavy-issue-to-merge skill chain for claim, discovery, candidate worktrees, critique, synthesis, verification, and PR publication.council modeWidth policies determine whether the task stays single-agent or fans out to a parallel council.ship gateMerge is blocked unless evidence, tests, branch state, and policy gates satisfy the fail-closed rules.quickstart
Use these commands first. They are intentionally copyable and match the public repository workflow.
install or run
hermes profile install github.com/codegraphtheory/heavy-coder --name heavy-coder --alias --force --yeshermes -p heavy-coder chatlocal developer setup
git clone https://github.com/codegraphtheory/heavy-coder.gitcd heavy-coderpython3.11 -m venv .venvsource .venv/bin/activatepython -m pip install -e ".[dev]"python scripts/validate_distribution.py .python -m pytestdeveloper workflows
The project is useful when the workflow is explicit. These are the paths to test before treating the project as production-ready.
interactive codingRun heavy-coder chat from a repository. Non-trivial tasks are routed through team mode before implementation.issue to PRUse the heavy-issue-to-merge skill chain for claim, discovery, candidate worktrees, critique, synthesis, verification, and PR publication.council modeWidth policies determine whether the task stays single-agent or fans out to a parallel council.ship gateMerge is blocked unless evidence, tests, branch state, and policy gates satisfy the fail-closed rules.repo map
Start with these files when debugging, extending, or reviewing the project.
src/heavy_coder/team_plan.pyBuilds and validates team plans for multi-agent execution.src/heavy_coder/width_policy.pyControls adaptive council width and routing decisions.src/heavy_coder/policy.pyFail-closed policy checks for unattended workflow boundaries.agent-hooks/pre_llm_heavy_team.pyHook that detects tasks needing heavy-team behavior.skills/heavy-issue-to-merge/Issue-to-PR skill with claim, discovery, candidate, critic, synth, verifier, and merge scripts.schemas/*.schema.jsonMachine-checkable schemas for candidates, evaluations, and run state.scripts/heavy_coding_flow.pyLocal scripted entry point for the heavy coding flow.docs/state-machine.mdState model for issue-to-merge execution.validation
Do not trust the docs. Run the checks and inspect the output.
python scripts/validate_distribution.py .python -m pytestpython -m ruff check .python -m mypy src testspython scripts/validate_github_repo_metadata.pypython scripts/validate_release_guard.pyconfiguration
Configuration surface and credential expectations.
GITHUB_TOKENNeeded for issue, PR, and merge automation when gh auth is unavailable.XAI OAuth or configured model providerRecommended Composer or Grok-backed model path for wide council work.HERMES_HOMEUse a temp profile home for install smoke tests.Never commit .env files, OAuth tokens, API keys, cookies, private documents, or Hermes runtime state.
troubleshooting
Common failure modes and where to look first.
team mode does not triggerCheck agent-hooks sync, profile config, and the heavy scope router decision.PR automation stallsRun skills/heavy-issue-to-merge/scripts/doctor.py and verify gh auth, branch state, and issue permissions.too much fan-outAdjust heavycoder.councilwidth and inspect width_policy behavior with tests.contribute
Open a focused issue or pull request with commands run, expected behavior, actual behavior, and relevant logs. Keep changes scoped. For GraphTheory public repos, maintainer commits use the GraphTheory identity and avoid private personal data.