Quick Start

This tutorial takes you from a bootstrapped AGH install to one durable session you can inspect, stop, and resume. It is intentionally repository-aware: you will create the session from the project you actually want AGH to manage.

Before you begin: Complete Installation, export your provider API key in the current shell, and cd into a repository you want the session to use.

1. Start the daemon

agh daemon start

If you want to watch the daemon logs in the current terminal instead of detaching, use:

agh daemon start --foreground

Verify that the daemon is available:

agh daemon status

2. Register the current repository as a workspace

AGH can use the current directory directly, but registering the workspace gives you a stable name you can reuse in later commands.

agh workspace add "$PWD" --name current

Confirm the registration:

agh workspace info current

3. Create your first session

Create a session for the workspace you just registered:

agh session new --workspace current --agent general --name first-run

If you prefer not to register a workspace first, use:

agh session new --cwd "$PWD" --agent general

The key point is explicit workspace context. That keeps the first session tied to the repository you expect, instead of relying on an implicit working directory.

4. Find the session ID

List sessions and note the ID:

agh session list

For scripts or copy-paste into later commands, JSON is often easier:

agh session list -o json

The examples below use sess_1234 as a placeholder for your real session ID.

5. Send a repository-aware prompt

Use a prompt that makes the workspace matter:

agh session prompt sess_1234 "Summarize the top-level structure of this repository and tell me what I should read first."

AGH records the prompt, the agent response, tool calls, permission decisions, and usage events in the per-session event store.

6. Follow the live event stream

agh session events sess_1234 --follow

This is the fastest way to see what AGH means by a durable session: every important step appears as an event instead of disappearing into one terminal transcript.

When you are done following, press Ctrl+C.

7. Stop the session

agh session stop sess_1234

The session keeps its history in ~/.agh/sessions/sess_1234/events.db. Stopping ends live work; it does not delete the durable record.

8. Resume the same session

agh session resume sess_1234

Then inspect the stored history:

agh session history sess_1234

This is the core AGH promise in one loop: the session is durable, inspectable, and resumable.

What You Just Proved

You verified that AGH can:

1. run a local daemon
2. attach work to one explicit repository
3. persist session events durably
4. stop live work without losing history
5. resume the same session later

Next Steps

• Your First Custom Agent shows how to add a workspace-scoped AGENT.md.
• Web UI shows how to inspect the same daemon state in the browser.
• Session Lifecycle explains what AGH is storing and why.