Skip to main content
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. 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.

​
First Steps: Hello World

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!”
OpenHands will generate script, set the correct permissions, and even run it for you. Now try making small changes:
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:
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.

​
Build Something 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. 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 basics are working, build on it just like you would in a real project:
Allow adding an optional due date to each task.
You can also ask OpenHands to help with version control:
Commit the changes and push them to a new branch called “feature/due-dates”.
Break your goals into small, manageable tasks.. Keep pushing your changes often. This makes it easier to recover if something goes off track.

​
Expand Existing Code

Want to add new functionality to an existing repo? OpenHands can do that too.
If you’re running OpenHands on your own, first add a GitHub token, GitLab token or Bitbucket token.
Choose your repository and branch via Open Repository, and press Launch. Examples of adding new functionality:
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.
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 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.
Split the build_and_deploy_widgets function into two functions, build_widgets and deploy_widgets in widget.php.
Break ./api/routes.js into separate files for each route.
Focus on small, meaningful improvements instead of full rewrites.

​
Debug and Fix Bugs

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 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.
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 clear and specific.
  • Provide relevant context.
  • Commit and push frequently.
See Prompting Best Practices for more tips on how to get the most out of OpenHands.
⌘I