Tutorial: getting started with Ori

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# Tutorial: getting started with Ori

By the end of this tutorial, you will have built Ori, started it with its bundled demo agent, and held a complete conversation in your browser — including a streamed answer, a visible plan, tool calls and a permission you grant yourself. No prior knowledge of ACP is required.

## Prerequisites

- Go 1.26 or newer (`go version`)
- Node.js 24 or newer with npm (`node --version`)
- A web browser

## Step 1 — Install the frontend dependencies

From the repository root, type:

```bash
make deps
```

You should see npm resolve the packages and end with a line like:

```
added 158 packages, and audited 159 packages in 9s
```

We have just installed everything the SPA build needs.

## Step 2 — Build and start Ori with the demo agent

Type:

```bash
make run-mock
```

You should see the SPA build, the Go build, then:

```
INFO starting agent command="[bin/ori-mock-agent]" cwd=…
INFO agent session ready sessionId=mock-1
INFO ori listening addr=:8888
```

We have just started the full application: the server is up and already connected, over ACP, to `ori-mock-agent` — a small deterministic agent that needs no account and no network.

## Step 3 — Open the panel

Open [http://localhost:8888](http://localhost:8888) in your browser.

You should see the Ori panel: a header showing `online · mock-1`, an empty conversation, and a message box at the bottom.

## Step 4 — Send your first message

Type `hello` in the message box and press Enter.

You should see a spinner appear at the bottom of the thread with rotating status phrases (*Pondering…*, *Brewing ideas…*), then, streaming in one after the other:

- your own message, aligned to the right;
- a **💭 Thinking…** block showing the agent's reasoning live while it streams (it collapses into *💭 Thought for a moment* once the turn ends — click it to reopen);
- a **Plan (0/2)** checklist;
- a tool call card **📖 Reading README.md** whose badge turns to **done**;
- the beginning of the agent's answer.

We have just run the first half of a prompt turn: the agent streams updates and the panel renders each kind in its own shape.

## Step 5 — Grant the permission

The panel now shows a **🔐 Write hello.txt** card with two buttons.

Click **Allow once**.

You should see a second tool call card **✏️ Writing hello.txt** with a green diff, then the agent's final answer — `Done! You said: hello` followed by a small checklist — and the plan showing **Plan (2/2)**.

We have just completed the whole loop: the agent asked for a permission, your click travelled back to it through the backend, and it finished its turn.

## What now?

You have run Ori end to end with the demo agent. To go further:

- To talk to a real agent → [How to run Ori with Claude Code](../how-to/run-with-claude-code.md)
- To plug in another agent → [How to use another ACP agent](../how-to/use-another-agent.md)
- To understand what happened between the browser and the agent → [Explanation: architecture](../explanation/architecture.md)