{"id":14677355,"url":"https://github.com/FSoft-AI4Code/HyperAgent","last_synced_at":"2025-09-09T03:31:22.768Z","repository":{"id":217113732,"uuid":"722523710","full_name":"FSoft-AI4Code/HyperAgent","owner":"FSoft-AI4Code","description":"Generalist Software Agents to Solve Soware Engineering Tasks","archived":false,"fork":false,"pushed_at":"2024-12-10T19:52:28.000Z","size":44361,"stargazers_count":217,"open_issues_count":10,"forks_count":19,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-08-21T12:34:55.791Z","etag":null,"topics":["code-generation","code-understanding","codellm","codellms","coding-assistant","multi-agent","repo-level","repository"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FSoft-AI4Code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-23T10:34:19.000Z","updated_at":"2025-08-10T08:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"9bae543d-b11f-4533-9a26-53e6a1a1b495","html_url":"https://github.com/FSoft-AI4Code/HyperAgent","commit_stats":null,"previous_names":["fsoft-ai4code/repopilot","fsoft-ai4code/hyperagent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FSoft-AI4Code/HyperAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FSoft-AI4Code%2FHyperAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FSoft-AI4Code%2FHyperAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FSoft-AI4Code%2FHyperAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FSoft-AI4Code%2FHyperAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FSoft-AI4Code","download_url":"https://codeload.github.com/FSoft-AI4Code/HyperAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FSoft-AI4Code%2FHyperAgent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274238703,"owners_count":25247110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-09T02:00:10.223Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","code-understanding","codellm","codellms","coding-assistant","multi-agent","repo-level","repository"],"created_at":"2024-09-12T09:01:18.314Z","updated_at":"2025-09-09T03:31:22.753Z","avatar_url":"https://github.com/FSoft-AI4Code.png","language":"Python","funding_links":[],"categories":["HarmonyOS","Python","Multi-Agent \u0026 Orchestration","Open Source Agents"],"sub_categories":["Windows Manager","Other IDEs"],"readme":"    \n\u003cp align=\"center\"\u003e\n    \u003cbr\u003e\n    \u003cimg src=\"assets/hyperagent-logo-zip-file/svg/logo-no-background.svg\" width=\"600\"/\u003e\n    \u003cbr\u003e\n\u003cp\u003e\n\u003cdiv align=\"center\"\u003e\n \n\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Python 3.10](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-380/) [![arXiv](https://img.shields.io/badge/📝-Paper-red)](paper/main.pdf)\n\n    \n# Generalist Software Engineering Agents to Solve Coding Tasks at Scale\n\n\u003c!-- \n[![Code License](https://img.shields.io/badge/Code%20License-Apache_2.0-green.svg)](https://github.com/bdqnghi/CodeTF_personal/blob/main/LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) --\u003e\n \u003c/div\u003e   \n    \n## Overview\n\nHyperAgent is a generalist multi-agent system designed to tackle a wide spectrum of software engineering (SE) tasks across various programming languages. Unlike existing LLM-based software agents that typically specialize in specific tasks, HyperAgent mimics human developers' workflows to address diverse SE challenges. Comprising four specialized agents (Planner, Navigator, Code Editor, and Executor), it manages the full lifecycle of SE tasks from conception to verification. \n\nHyperAgent demonstrates state-of-the-art performance in:\n\n- GitHub issue resolution ([SWE-Bench-Python](https://www.swebench.com/)): 31.4% on Resolved Rate on SWE-Bench Verified and 25% on SWE-Bench Lite. The results has currently been verifing on swe-bench (https://github.com/swe-bench/experiments/pull/80)\n- Repository-level code generation ([RepoExec-Python](https://github.com/FSoft-AI4Code/RepoExec)): 53.3% on Pass@5.\n- Fault localization and program repair ([Defects4J-Java](https://github.com/rjust/defects4j)): 249 bugs fixed.\n\nNotably, HyperAgent is designed to handle a codebase written in a wide range of programming languages. We currently support Python and Java and plan to expand to other languages on other tasks/benchmarks in the future. We believe we are the first software engineering agent designed to handle a variety of software engineering tasks across multiple programming languages.\n\n### Key Features\n- Generalizability: Easily adapts to various tasks with minimal configuration changes.\n- Efficiency: Optimized agents manage processes of varying complexity using appropriate LLM capabilities.\n- Scalability: Built to handle large-scale, real-world software engineering scenarios effectively.\n- Multi-task Proficiency: Excels in GitHub issue resolution, code generation, fault localization, and program repair. existing development workflow with its Python API, allowing for flexible and powerful code interactions.\n\n## Architecture\n\u003cp align=\"center\"\u003e\n    \u003cbr\u003e\n    \u003cimg src=\"assets/method_overview.png\" width=\"950\"/\u003e\n    \u003cbr\u003e\n\u003cp\u003e\n\n## Installation and Usage\nHyperAgent uses Zoekt for code search. Please install Zoekt before installing HyperAgent. Zoekt requires latest Go installation, please follow the instructions [here](https://www.linuxedo.com/2021/10/install-latest-golang-on-linux.html) to install Go.\n\n```bash\ngo get github.com/sourcegraph/zoekt/\n\n# Install Zoekt Index\ngo install github.com/sourcegraph/zoekt/cmd/zoekt-index\n# Install Zoekt Web Server\ngo install github.com/sourcegraph/zoekt/cmd/zoekt-webserver\n```\nWe also need to install universal-ctags for semantic code search. Please follow the instructions [here](https://github.com/sourcegraph/sourcegraph/blob/main/doc/dev/how-to/zoekt_local_dev.md#install-ctags). Remember to set the environment variable of CTAGS `CTAGS_COMMAND=universal-ctags`. \n\nAfter installing Zoekt and universal-ctags, we can install HyperAgent by running the following commands, notes that it's a must to create a new conda environment before installing HyperAgent named hyperagent, since the Executor uses jupyter kernel named hyperagent to execute the code:\n```bash\nconda create -n hyperagent python=3.10\npip3 install -e .\n```\n\n### Quick Test\nTo test the hyperagent with general prompt, you can run the following command:\n```bash\npython3 main.py --repo \"your/path/to/repo\" --commit \"commit_hash\" --language \"python\" --clone_dir \"data/repos\" --prompt \"I want to create an FastAPI app to handle GET request from OpenAI API\"\n```\n### General usage\n```python\nfrom hyperagent import HyperAgent\npilot = HyperAgent(repo, commit=commit, language=language, clone_dir=\"data/repos\")\n```\nwith `repo` is the repository URL, `commit` is the commit hash, `language` is the programming language of the repository, and `clone_dir` is the directory to store the cloned repository. You also can configure the agents by setting the `config` parameter. \n\nHyperagent supports 2 modes: patch and predict. In the patch mode, the agent will generate a patch for the given task. In the predict mode, the agent will predict the next token for the given task (for example, repoQA or fault location).\n\n```python\nconfig = {\n        \"name\": \"claude\",\n        \"nav\": [{\n            \"model\": \"claude-3-haiku-20240307\",\n            \"api_key\": os.environ.get(\"ANTHROPIC_API_KEY\"),\n            \"stop_sequences\": [\"\\nObservation:\"],\n            \"base_url\": \"https://api.anthropic.com\",\n            \"api_type\": \"anthropic\",\n        }],\n        \"edit\": [{\n            \"model\": \"claude-3-5-sonnet-20240620\",\n            \"api_key\": os.environ.get(\"ANTHROPIC_API_KEY\"),\n            \"stop_sequences\": [\"\\nObservation:\"],\n            \"price\": [0.003, 0.015],\n            \"base_url\": \"https://api.anthropic.com\",\n            \"api_type\": \"anthropic\",\n        }],\n        \"exec\": [{\n            \"model\": \"claude-3-5-sonnet-20240620\",\n            \"api_type\": os.environ.get(\"ANTHROPIC_API_KEY\"),\n            \"stop_sequences\": [\"\\nObservation:\"],\n            \"price\": [0.003, 0.015],\n            \"base_url\": \"https://api.anthropic.com\",\n            \"api_type\": \"anthropic\",\n        }],\n        \"plan\": [{\n            \"model\": \"claude-3-5-sonnet-20240620\",\n            \"api_type\": os.environ.get(\"ANTHROPIC_API_KEY\"),\n            \"price\": [0.003, 0.015],\n            \"base_url\": \"https://api.anthropic.com\",\n            \"api_type\": \"anthropic\",\n        }],\n        \"type\": \"patch\"\n    }\n```\n\nHyperAgent is a software generalist agent, therefore it can be used to solve various software engineering tasks. We provide a few examples of how to use HyperAgent to solve different tasks in the `scripts` folder. This is easily configured via an input template prompt for each task.\n\nFor example, in `src/hyperagent/tasks/github_issue_resolution.py`, we provide a script to resolve GitHub issues using HyperAgent. The script will prompt the user to input the issue title and description, and then HyperAgent will generate a patch to resolve the issue. \n```python\ndef run(self, system, idx) -\u003e Result:\n      prompt = self.construct_prompt(idx)\n      system.query_codebase(prompt)\n      prediction_patch = extract_patch(system.repo_dir)\n      return prediction_patch\n```\n\nIf you want to use HyperAgent to solve other tasks and systematically evaluate the results, you can create a new task class and implement the `run` method. The `run` method should return the result of the task. \n\n## Reproduce Evaluation Results\nTo reproduce the results, please follow the instructions in the `scripts` folder. We provide the scripts to reproduce the results on SWE-Bench, RepoExec, and Defects4J datasets.\n\n### SWE-Bench\n```bash\npython3 scripts/run_swe_bench.py --split \"test\"\n```\n\n### Fault Localization\n```bash\npython3 scripts/run_defects4j_fl.py\n```\n\n### Program Repair\n```bash\npython3 scripts/run_defects4j_apr.py\n```\n\n###\n\n# Citing HyperAgent\n\nIf you're using HyperAgent in your research or applications, please cite using this BibTeX:\n```bibtex\n@article{huy2024hyperagent,\n  title={HyperAgent: Generalist Software Engineering Agents to Solve Coding Tasks at Scale},\n  author={Phan, Huy Nhat and Nguyen, Phong X and Bui, Nghi DQ},\n  journal={arXiv preprint arXiv:2406.11912},\n  year={2024}\n}\n```\n\n# Contact us\nIf you have any questions, comments or suggestions, please do not hesitate to contact us.\n- Website: [fpt-aicenter](https://www.fpt-aicenter.com/ai-residency/)\n- Email: bdqnghi@gmail.com\n\n# License\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFSoft-AI4Code%2FHyperAgent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFSoft-AI4Code%2FHyperAgent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFSoft-AI4Code%2FHyperAgent/lists"}