# Set up yak and yaks.app

> `yak` is a command line, and `@yaks` a set of open-source TypeScript packages, for one graph that you and your agents both read and write.

This page is for an agent setting up yak and yaks.app, for itself or for the person it works for. Run each command as written, in order; `yak serve` keeps running, so start it in the background. Two steps need the person: signing in to yaks.app opens a page in their browser, and adding a connector to Claude or ChatGPT on the web is done in their settings. For those, tell them the one thing to open, click or paste.

yak runs on [Deno](https://deno.com). If `deno --version` fails, install Deno first, then put it on this shell's PATH, where the installer below puts `yak` too:

```sh
curl -fsSL https://deno.land/install.sh | sh -s -- -y
export PATH="$HOME/.deno/bin:$PATH"
```

## yak is a command line for the tools your graph declares

A config names a SQLite file and a list of plugins. Each plugin is an `@yaks` package, and every tool it declares is a `yak` command and an MCP tool.

- **Every tool is a command.** Its arguments and help come from the tool's input schema, so a new tool needs no new release of yak.
- **No server needed.** A command opens the graph in its own process, runs one tool and exits.
- **Every call is recorded.** A call from you and a call from an agent go through the same checks, rules and effects, and each is kept in the graph.
- **`yak serve` answers HTTP.** The browse app at `/`, the tools for agents at `/mcp`, and `/query` and `/apply` for programs, on this machine only.
- **Your agents join it.** `yak hooks install` makes each Claude Code session an entity in the graph, told the tasks it holds when it starts. Any MCP client can call the tools at `/mcp`.
- **Other graphs too.** `--config` opens the graph another config names, and `--host` calls the graph on another machine.

## yaks.app hosts web apps on the same packages

yaks.app builds, hosts and shares web apps. You ask Claude or ChatGPT for an app, and yaks.app keeps it online at its own address, with its data in a graph made of these packages.

- **One toolkit in two places.** On your machine, `yak` keeps a graph in a SQLite file. On yaks.app, the same `@yaks/graph` keeps each app's data in a Cloudflare Durable Object.
- **Your assistant builds the app.** Add yaks.app to Claude or ChatGPT and ask for what you need. It writes the app, and yaks.app serves it at an address like `yourname.yaks.app/recipes`.
- **The same `yak` reaches it.** `yak auth yaks.app` signs you in. Then `yak app_list` lists your apps and `yak app_errors --app recipes` shows what broke in one, from the command line that runs your own graph.
- **An app's commands run in your terminal.** A yaks app can declare commands of its own, and `yak <app> <command>` runs them as you.
- **Your graph passes on what it doesn't have.** A command your own graph doesn't declare goes to yaks.app, so `yak app_list` works on a machine that keeps a graph of its own.

## Install yak, then start your graph

The installer runs on [Deno](https://deno.com) and puts `yak` on your PATH, at one release with every package it loads.

### Install yak

```sh
deno run -A jsr:@yaks/cli/install
```

It installs the newest release at least a day old, since Deno waits a day for a new one. To update to the newest, even one published today:

```sh
deno run -A --minimum-dependency-age=0 --reload=jsr:@yaks/cli jsr:@yaks/cli/install
```

### Start your graph

```sh
yak init
```

It writes `~/.yak/yak.json`, with the graph's SQLite file beside it, and never replaces a config that is already there.

### Add a task, and list them

```sh
yak task new 'Add the sign-up page'
yak task list
```

### Browse it in a terminal

```sh
yak browse
yak browse T-1
```

Opens [@yaks/browse](https://github.com/yak-sh/yak/tree/main/packages/browse) on your graph in this terminal: your tasks at home, and with an id, that entity's page.

### Open it in a browser

```sh
yak serve
```

Serves the graph at `http://127.0.0.1:8787`, on this machine only, until you stop it: the same app at `/` to read and edit it, `/mcp` for agents and `/query` for programs.

### Bring your agents

```sh
yak hooks install
```

Each Claude Code session becomes a session entity in the graph. Any MCP client can call the graph's tools at `http://127.0.0.1:8787/mcp`.

### Reach yaks.app

```sh
yak auth yaks.app
```

Prints an address to open in a browser. Sign in there with your email, then paste back the address the browser lands on, and the same `yak` calls your yaks.app account.

### Connect Claude or ChatGPT

Add yaks.app to your assistant as a connector at `https://yaks.app/mcp`, and sign in with your email. [Its setup page](https://yaks.app/agent) has the steps for each assistant, written so the assistant can follow them.

### Put an app online

```sh
yak app_new --slug notes --title Notes
yak app_files --app notes --path index.html --content @index.html
yak app_deploy --app notes
```

With an `index.html` in this folder, these make the app, write that file as its page, and put it online at `yourname.yaks.app/notes`. Or ask Claude or ChatGPT for the app you want, and it calls the same tools.

## Read more

- [yak.sh as Markdown](https://yak.sh/index.md): the home page: tasks, edges, queries, rules, effects and memories, each with the commands it runs
- [Connect your AI agent to yaks.app](https://yaks.app/agent.md): the steps for Claude, ChatGPT, Claude Code, Codex, Cursor and other assistants
- [yaks.app for agents](https://yaks.app/llms.txt): the guide to everything a yaks app can do, a page per subject
- [The yak command](https://github.com/yak-sh/yak/blob/main/packages/cli/README.md): configs, plugins, `yak serve`, `--host` and signing in
- [The @yaks packages](https://github.com/yak-sh/yak/blob/main/packages/README.md): what each package is for, with a README each

