Your first agent session
Open a repo, let Claude implement a small change, let Codex review it, then you approve the diff and tests.
Outcome: one bounded change in your repository that you verified — not an unattended cross-provider demo.
This is the first workflow Harmony can honestly walk: local Core, your CLIs, human review. Harmony Cloud is optional and separate (choose your setup).
Prerequisites
- A workspace open on a real repository
- Provider CLIs installed and authenticated outside Harmony. Typical pair:
Claude Code (
claude) and Codex CLI (codex). See connect a provider.
You do not need a Harmony account. Token spend stays with those providers. Network is required for their APIs, not for Harmony Core itself.
Pick the right first task
Choose something you could do yourself in ten minutes and would recognise as correct immediately. Good candidates:
- Add a test for a function that already exists.
- Rename a symbol consistently across a few files.
- Fix a bug whose cause you already understand.
Poor candidates for a first run: anything open-ended, anything touching build configuration, anything you cannot verify quickly, anything that needs both agents to agree automatically.
TIP
You are testing the loop, not the model. A task you can check in seconds tells you far more about whether Harmony is working than an ambitious one does.
1. Launch Claude Code
From the orchestration bar, click Claude, or in the TUI:
/provider
Pick Claude when the list appears. Harmony launches the claude binary on
PATH (or ~/.claude/bin). It does not log you in.
Expected result: a pane at Claude Code's ready prompt, working directory set to your repository.
If the pane exits immediately, authenticate outside Harmony with that vendor's own login, then relaunch. Harmony cannot see whether you are signed in.
2. Give Claude a bounded change
State the outcome and the constraint:
Add a unit test for parseConfig in src/config.ts covering the case where the
file is missing. Do not change parseConfig itself.
3. Watch the approvals
Depending on your permission settings, the agent will ask before doing things that change your machine or repository.
IMPORTANT
Read approval prompts rather than clicking through them. Harmony does not apply repository changes perfectly in the background. The prompt is the point at which you can still say no cheaply. See permissions and approvals.
4. Launch Codex to review — not to overwrite
Open a second pane and launch Codex CLI the same way (status-bar Codex, or
/provider then Codex). Confirm codex works in your own terminal first.
Ask Codex to review, not to silently restyle the tree:
Review the current git diff. List risks and missing tests. Do not apply edits
unless I ask.
This is two CLIs you already pay for, in two panes. It is not a verified automatic Claude→Codex pipeline. Harmony does not merge their work for you.
5. You verify the work
git diff
Then run the project's own tests. Do not accept "the agent said it passed" as evidence — run them.
Approve remaining Harmony prompts only after you are satisfied. Reject or stop the turn if the diff is wrong.
6. Confirm the task is recorded
harmony tasks list
Expected result: the task appears with its state. This is the durable record in the daemon, independent of whether the pane is still open.
7. What durability you can actually prove
Close the desktop window entirely, then reopen it:
harmony desktop
Expected result: local PTYs the daemon still holds reattach, with scrollback. After a reboot, layout and history restore from disk; the agent conversation continues only if that provider CLI still has a resume binding. See durable sessions.
Common recovery
| Symptom | Likely cause | Where to go |
|---|---|---|
| Agent never responds | Not authenticated | Provider problems |
| Agent edits the wrong files | Working directory is not your repo | Relaunch the workspace from the repo root |
Task does not appear in harmony tasks list | Session did not register | Daemon problems |
| Approval prompts never appear | Permission mode is permissive / YOLO | Review permissions and approvals |
| Codex overwrote Claude's work | You asked it to implement, not review | git checkout / git restore the files; keep review prompts bounded |
Next
- First TUI session
- First orchestration run (experimental)
- Tasks, plans, and runs