diff --git a/index.mdx b/index.mdx index 1713f95e..64d064d7 100644 --- a/index.mdx +++ b/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: OpenHands - Code Less, Make More +description: OpenHands - Code Less, Make More. icon: book-open mode: wide --- diff --git a/openhands/usage/start-building.mdx b/openhands/usage/start-building.mdx index 0ebf2189..4bfaca49 100644 --- a/openhands/usage/start-building.mdx +++ b/openhands/usage/start-building.mdx @@ -4,69 +4,90 @@ description: So you've [run OpenHands](/openhands/usage/quick-start). Now what? icon: code --- -OpenHands can assist with a range of engineering tasks. However, the technology is still new, and we’re far from having -agents that can handle complex tasks independently. It’s important to understand what the agent does well and where it -needs support. +Like any tool, it works best when you know how to use it effectively. Whether you're experimenting with a small +script or making changes in a large codebase, this guide will show how to apply OpenHands in different scenarios. -## Hello World +Let’s walk through a natural progression of using OpenHands: +- Try a simple prompt. +- Build a project from scratch. +- Add features to existing code. +- Refactor code. +- Debug and fix bugs. -Start with a simple "hello world" example. It might be trickier than it seems! +## First Steps: Hello World -Prompt the agent with: +Start with a small task to get familiar with how OpenHands responds to prompts. + +Click `New Conversation` and try prompting: > Write a bash script hello.sh that prints "hello world!" -The agent will write the script, set the correct permissions, and run it to check the output. +OpenHands will generate script, set the correct permissions, and even run it for you. + +Now try making small changes: -You can continue prompting the agent to refine your code. This is a great way to -work with agents. Start simple, and iterate. +> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world". -> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world" +You can experiment in any language. For example: -You can also use any language you need. The agent may need time to set up the environment. +> Convert hello.sh to a Ruby script, and run it. -> Please convert hello.sh to a Ruby script, and run it + + Start small and iterate. This helps you understand how OpenHands interprets and responds to different prompts. + -## Building From Scratch +## Build Something from Scratch -Agents excel at "greenfield" tasks, where they don’t need context about existing code and -they can start from scratch. +Agents excel at "greenfield" tasks, where they don’t need context about existing code. Begin with a simple task and iterate from there. Be specific about what you want and the tech stack. -For example, we might build a TODO app: +Click `New Conversation` and give it a clear goal: > Build a frontend-only TODO app in React. All state should be stored in localStorage. -Once the basic structure is in place, continue refining: +Once the basics are working, build on it just like you would in a real project: > Allow adding an optional due date to each task. -Just like normal development, commit and push your code often. -This way you can always revert back to an old state if the agent goes off track. -You can ask the agent to commit and push for you: +You can also ask OpenHands to help with version control: -> Commit the changes and push them to a new branch called "feature/due-dates" +> Commit the changes and push them to a new branch called "feature/due-dates". -## Adding New Code + + Break your goals into small, manageable tasks.. Keep pushing your changes often. This makes it easier to recover + if something goes off track. + -OpenHands is great at adding new code to an existing codebase. +## Expand Existing Code -For instance, you can ask OpenHands to add a GitHub action that lints your code. It might check your codebase to -determine the language, then create a new file in `./github/workflows/lint.yml`. +Want to add new functionality to an existing repo? OpenHands can do that too. -> Add a GitHub action that lints the code in this repository. + +If you're running OpenHands on your own, first add a +[GitHub token](/openhands/usage/run-openhands/gui-mode#github-setup), +[GitLab token](/openhands/usage/run-openhands/gui-mode#gitlab-setup) or +[Bitbucket token](/openhands/usage/run-openhands/gui-mode#bitbucket-setup). + + +Choose your repository and branch via `Open Repository`, and press `Launch`. + +Examples of adding new functionality: -Some tasks need more context. While OpenHands can use commands like ls and grep to search, providing context upfront -speeds things up and reduces token usage. +> Add a GitHub action that lints the code in this repository. > Modify ./backend/api/routes.js to add a new route that returns a list of all tasks. > Add a new React component to the ./frontend/components directory to display a list of Widgets. > It should use the existing Widget component. -## Refactoring + + OpenHands can explore the codebase, but giving it context upfront makes it faster and less expensive. + + +## Refactor Code -OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase, -it's more effective to break up long files and functions or rename variables. +OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase, it's more +effective in focused refactoring tasks. Start by launching a conversation with +your repo and branch. Then guide it: > Rename all the single-letter variables in ./app.go. @@ -74,27 +95,37 @@ it's more effective to break up long files and functions or rename variables. > Break ./api/routes.js into separate files for each route. -## Bug Fixes + + Focus on small, meaningful improvements instead of full rewrites. + + +## Debug and Fix Bugs -OpenHands can help track down and fix bugs, but bug fixing can be tricky and often requires more context. -It’s helpful if you’ve already diagnosed the issue and just need OpenHands to handle the logic. +OpenHands can help debug and fix issues, but it’s most effective when you’ve narrowed things down. + +Give it a clear description of the problem and the file(s) involved: > The email field in the `/subscribe` endpoint is rejecting .io domains. Fix this. > The `search_widgets` function in ./app.py is doing a case-sensitive search. Make it case-insensitive. -For bug fixing, test-driven development can be really useful. You can ask the agent to write a new test and iterate +For bug fixing, test-driven development can be really useful. You can ask OpenHands to write a new test and iterate until the bug is fixed: > The `hello` function crashes on the empty string. Write a test that reproduces this bug, then fix the code so it passes. -## More + + Be as specific as possible. Include expected behavior, file names, and examples to speed things up. + + +## Using OpenHands Effectively OpenHands can assist with nearly any coding task, but it takes some practice to get the best results. Keep these tips in mind: * Keep your tasks small. -* Be specific. -* Provide plenty of context. +* Be clear and specific. +* Provide relevant context. * Commit and push frequently. -See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most out of OpenHands. +See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most +out of OpenHands.