Getting started

[stntmaniiac]

I wanted to try out AO with my projects. I have installed as per README.md and I have the main Orchestrator running. Initially it has an empty dashboard and not much you can do from UI. How do you actually make it start working? I tried creating new issues in the github repo, thinking maybe it just gets those issues and start working on it on its own. Also tried creating standalone claude sessions in the repo, didnot see the seesion in the dashboard. Created an session with ao spawn, it created an session, visible in UI. It said its in working state for sometime, not sure what it was working on. After a moment, it got stuck and was waiting for response.

I didnot actually find a simple example on working on a particular issue to start with. The readme just has how to setup, yaml structure etc. Please forgive me if this sounds naive, but am I missing something?

[wengseng300]

This repo definitely need a much better guide on how to start using it. I just downloaded the .exe and proceed to uninstall it shortly. I tried adding a project and selected my local project, it says something about the project is not git repo. I select another project that had committed to repo, then it says project id failed storage-path validation. The error message don't make any sense and doesn't tell what to do. I thought this repo is going on the issue of my projects in my machine, so I don't get why is it requesting a github repo. While the interface seems promising, there isn't much working example on how to really use it

[tamish560]

The flow is: add a git repo as a project, then use ao spawn to create an agent session pointed at a specific issue or task.

ao spawn needs a prompt or issue reference. If you point it at a GitHub issue (by number or URL), the agent picks up the issue context and starts working. The "waiting for response" state usually means the agent hit a point where it needs human input, like approving a file change or confirming an approach.

The empty dashboard is expected on first install. You need to:

1. Add a project (your local git repo)
2. Spawn an agent with a task: ao spawn --issue 42 or ao spawn --prompt "fix the failing test in auth.go"
3. The agent works in an isolated git worktree, not your working directory
4. When it's done, you review the diff and it creates a PR or commits to a branch

The error about "not a git repo" means the folder you selected doesn't have a .git directory. AO requires a git repository because it uses worktree isolation for each agent session.

The "project id failed storage-path validation" error happens when the project path has spaces or special characters that AO's path sanitizer rejects. Try with a simpler path like ~/projects/myapp.

A better getting-started guide is something we're working on. The README covers setup but the first-run experience needs more hand-holding.

[tamish560]

on the issues the second commenter hit:

the "project is not git repo" error means the folder you selected doesn't have a .git directory. AO requires the project to be a git repo (it uses git worktrees for session isolation). run git init in that folder first, make at least one commit, then add it as a project in AO.

the "project id failed storage-path validation" error usually means the project name has characters that can't be used in a filesystem path (spaces, dots, special chars). AO derives a project id from the folder name and uses it for worktree paths under ~/.ao/data/worktrees/. if your folder is named something like "my app (v2)" it'll fail. rename the folder to something simple like my-app or use dashes only.

for a clean first run: create a fresh folder, git init, commit a README, add it as a project in AO, then ao spawn "add a hello world endpoint". that'll give you a session you can watch go from working to PR without hitting any edge cases.