Add your first project

A project gives your work a home in Choro: the local folder you want to work on, its agent conversations, and the tools you use to inspect the result. Start by adding a folder you recognize, then check its files before asking an agent to make changes.

Choose the right folder

Use the main folder for the project. For a website, this is usually the folder containing its README, source files, and package or build configuration. Selecting only a nested folder such as src can leave useful context outside the project; selecting your entire Documents folder makes the scope much broader than intended.

If the project lives in a remote repository, have a local copy available first. You can browse a folder without Git, while workflows that create branches or commits need a Git repository.

1. Add the project

1. Click the folder-shaped Add project button beside Search at the top of the left sidebar. The default keyboard shortcut is ⌘O.

2. In the macOS folder picker, navigate to your project, select its main folder, and click Open. If macOS asks Choro for access to that folder, allow it so Choro can read the project.

3. Find the project in the left sidebar and select it. Check the project name at the top of the workspace before continuing.

2. Check that the expected files are present

Open Code from the right-hand toolbar. In the Files panel, open a familiar file such as README.md. Its contents should match the project you intended to add. This quick check catches a wrong folder before an agent starts working.

Demo example: Northstar Client Portal is selected in the left sidebar. Its README is open in the center, and the Files panel on the right shows the project’s folders and files. The folder-shaped Add project button is beside Search at the top left. Names and content in this screenshot are fictional demo data.

Your folder will have different files. The useful checks are the same: the selected project is correct, the file tree is familiar, and an opened file contains what you expect.

3. Start a conversation in this project

Open New Agent and confirm the selected project before sending your first message. A small orientation question helps establish context before you request a change. For example:

Explain how this project is organized and identify its main entry point. Do not change any files yet.

Read the answer and compare its file references with the Code view. Once the scope is right, continue with a specific task and explain what a successful result should look like. If Choro asks you to connect a coding provider first, complete that setup before expecting an agent response.

If something looks wrong

• The file tree looks unrelated: check the selected project and folder. You may have opened a parent folder or a different project with a similar name.

• Some expected files are outside the tree: confirm that you chose the project root rather than a nested subfolder.

• Choro cannot access the folder: check that the folder still exists and that macOS has allowed Choro to access its location, then try opening it again.

• A Git action is unavailable: adding a folder does not create its Git history. Check that you opened the repository you intended to use before trying a Git-dependent workflow.

What to do next

You can return to the project from the sidebar and keep its conversations alongside its files. When you are ready, start with one small, reviewable change so you can learn the full flow from request to inspection.