> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# First Projects

> So you've [run OpenHands](/overview/quickstart). Now what?

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.

<Info>
  Start small and iterate. This helps you understand how OpenHands interprets and responds to different prompts.
</Info>

## 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".

<Info>
  Break your goals into small, manageable tasks.. Keep pushing your changes often. This makes it easier to recover
  if something goes off track.
</Info>

## Expand Existing Code

Want to add new functionality to an existing repo? OpenHands can do that too.

<Note>
  If you're running OpenHands on your own, first add a
  [GitHub token](/openhands/usage/settings/integrations-settings#github-setup),
  [GitLab token](/openhands/usage/settings/integrations-settings#gitlab-setup) or
  [Bitbucket token](/openhands/usage/settings/integrations-settings#bitbucket-setup).
</Note>

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.

<Info>
  OpenHands can explore the codebase, but giving it context upfront makes it faster and less expensive.
</Info>

## 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.

<Info>
  Focus on small, meaningful improvements instead of full rewrites.
</Info>

## 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.

<Info>
  Be as specific as possible. Include expected behavior, file names, and examples to speed things up.
</Info>

## 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](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most
out of OpenHands.