# Set up kugutsu This page is written for an AI coding agent (Claude Code, Codex or similar) setting kugutsu up for the person it works for. If you are that person, give your agent this line: > Read https://kugutsu.io/setup.md and set up kugutsu on this machine. Agent: follow the steps in order. Where a step says **Ask**, stop and get the person's answer before going on. Run nothing with `sudo`, install no toolchain, and start no graph that spends money or acts outside the machine without the person's yes. Tell them what you are doing as you go, in a line or two per step. ## What you are installing kugutsu runs graphs of agents, rules and programs on the person's own machine. Events (webhooks, schedules, file changes, event streams, a typed prompt) start work; model nodes and whole agent sessions do it; a person reviews what matters before it counts; budgets cap the spend; every step and effect is recorded. It has two parts: - **the daemon** (`kugutsu-daemon`, Rust): runs the graphs and serves the web UI on `127.0.0.1:7300`; - **the command line** (`kugutsu`, Node.js): installs and starts graphs, sets secrets and budgets, decides reviews. It runs model CLIs with their own sign-in (Claude Code's `claude`, OpenAI's `codex`) and never uses an API key it happens to find in the environment. OpenAI-compatible APIs (OpenAI, DeepSeek, OpenRouter, Groq, local Ollama) take a key the person stores with `kugutsu secret set`. ## 1. Check the machine Report what you find in one short list. - **OS**: Linux (x86_64 or aarch64), macOS on Apple silicon, or Windows 11, where the daemon runs in WSL 2 (`wsl --install`). On Windows, do every step below inside the WSL distribution. - **Node.js 24 or later**: `node --version`. - **git**, and the GitHub CLI `gh` signed in (`gh auth status`). - **A model CLI signed in**: `claude --version` (Claude Code) and/or `codex --version`. At least one is needed for graphs with models. - **Rust** (`cargo --version`, stable): needed only for the source install below. **Ask** before installing anything that is missing, and say what it is for. ## 2. Check access kugutsu is in early access: its repository is private while it is tried by its first users. ```sh gh repo view kugutsu-AI/kugutsu-poc --json name ``` If that fails, stop here and tell the person that kugutsu is in early access and their GitHub account needs to be added to the `kugutsu-AI/kugutsu-poc` repository: they ask for it by joining the waitlist at https://kugutsu.io/#waitlist with their GitHub username (and, if they have one, their discovery report). Meanwhile they can still find out what kugutsu would do for them: https://kugutsu.io/discover.md needs nothing installed. ## 3. Install Use the source install unless the person wants the desktop tray app. ### From source (Linux, macOS, WSL) ```sh git clone https://github.com/kugutsu-AI/kugutsu-poc.git ~/kugutsu cd ~/kugutsu npm ci (cd rust && cargo build --release --bins) # a few minutes on a laptop ``` The command line is then `node ~/kugutsu/src/cli.ts`; it uses the daemon it just built. Offer the person a shell alias so `kugutsu` works: ```sh alias kugutsu='node ~/kugutsu/src/cli.ts' ``` ### The tray app (packages) The tray app puts kugutsu in the Windows notification area, the macOS menu bar or a Linux AppIndicator, starts the daemon and opens the UI. Packages are on the repository's `tray-dev` release (built from `main`): ```sh gh release view tray-dev --repo kugutsu-AI/kugutsu-poc --json assets -q '.assets[].name' ``` - **Linux / WSL**: download `kugutsu-daemon_*_amd64.deb` (and, on a Linux desktop, `kugutsu-tray_*_amd64.deb`) with `gh release download tray-dev --repo kugutsu-AI/kugutsu-poc --pattern '' --dir ~/Downloads`. **Ask** the person to install it with `sudo apt install ./.deb`. It puts `kugutsu` and `kugutsu-daemon` in `/usr/bin`. - **macOS**: download `kugutsu_*_aarch64.dmg`; the person opens it and drags kugutsu into Applications, then picks **Install command-line tool…** in the tray menu. - **Windows**: download `kugutsu-tray_*_x64-setup.exe` for the person to run, and install the daemon `.deb` inside WSL as above. Even with packages, clone the repository (as in the source install, without building): its `docs/` and `demos/` are what you read in step 6. ## 4. Start the daemon With the tray app, the tray starts it. Otherwise start it in the background and keep its log (`nohup` cannot run the alias, so a source install names the script): ```sh mkdir -p ~/.kugutsu nohup node ~/kugutsu/src/cli.ts daemon > ~/.kugutsu/daemon.log 2>&1 & # source install nohup kugutsu daemon > ~/.kugutsu/daemon.log 2>&1 & # packages ``` It prints the UI's address with a credential, `http://127.0.0.1:7300/#credential=…`. Give that address to the person to open in their browser, and tell them it is a secret: anyone who has it controls the daemon. To keep it running across logins on Linux or WSL, the repository's README has a systemd user service under "Running the worker as a standing service"; offer it, do not set it up unasked. ## 5. Check it works ```sh kugutsu agents check # the model CLIs: found, runs, signed in kugutsu run ~/kugutsu/demos/add.json # no model: prints sum = 11, sum = 22, sum = 33 kugutsu connections list # what graphs can depend on here ``` Report each result. If `agents check` says a CLI is not signed in, the person signs in (`claude`, then `/login`; or `codex login`); kugutsu never takes over a login. ## 6. Build the first graph **If the person has a discovery report** (`kugutsu-discovery-report.md`, from https://kugutsu.io/discover.md), build its **First pick**. Otherwise ask them for one recurring task and describe it in the report's candidate form (trigger, inputs, steps, review, effects, cost of a mistake) before building. Read before writing a graph: - `docs/quickstart.md`: a graph read line by line, a loop, a review; - `demos/*.json`: working graphs, each with a `notes` field; `triage.json` (webhook and timer to a model), `review-team.json` (models in parallel, then a lead), `ticket-worker-v2.json` (an event stream to agent sessions with a review) are the closest to real work; - `docs/spec/README.md`, then the spec pages for the node types you use. Write the graph as a template, so it shows on the Templates page and can be installed again: ```sh mkdir -p ~/kugutsu-graphs/ # graph.json, prompts/ for system prompts loaded with $file kugutsu templates sources ~/kugutsu-graphs kugutsu check ~/kugutsu-graphs//graph.json kugutsu graph plan ~/kugutsu-graphs//graph.json # what it needs, may do, and is estimated to spend ``` Rules for every graph you write: - **A budget**, declared in the graph, small to begin with (a day's worth of the expected runs). - **A review before any effect outside the machine** (a message sent, a comment posted, a pull request opened) until the person decides the graph has earned less oversight. - **Grant each node only the effects it needs**; leave model nodes without effect grants where you can. - **Bound every agent session.** A node that runs a program of its own (an agent session such as Claude Code or Codex) acts outside the effect grants: it can write files, run commands and reach the network itself, before any review downstream, and those actions are not recorded. What it can reach is its **boundary** (`docs/spec/features/boundaries/`): give it a working directory of its own, no network or only the hosts it needs; `kugutsu limits get` shows what this host enforces. On Linux and WSL the daemon sandboxes such nodes itself. On macOS the sandbox (a Linux VM per program, through Apple's `container`) does not run the agent adapters yet, so a bounded agent session is refused there: on a Mac, build graphs from single model calls and rules, or run agent sessions on a Linux or WSL host. Tell the person what such a node could still do, in one line, when you show the plan. - **Keys go in secrets**, never in the graph file: `kugutsu secret set NAME --nodes node:/` with the value on stdin, typed by the person. Install it without starting it, and check what each agent session will be held to: ```sh kugutsu templates install ~/kugutsu-graphs --graph kugutsu graph limits # its budgets, grants, boundary and record ``` Show the person the plan (what it listens to, what it may do, the budget, what an agent session could still do) and **Ask** before starting it: ```sh kugutsu graph start ``` Then send it one real event (or wait for its schedule), and walk the person through what happened in the UI: the step in the Graph view, the review waiting in the Inbox, the spend under Spend. Tell them what to watch for in the first week, and that anything kugutsu lacked for this job is worth reporting. ## If something fails Report the command, its output (the last 30 lines), and what you tried. The daemon's log is `~/.kugutsu/daemon.log` (the tray app: `daemon.log` in its settings folder). Do not work around a failure by widening a graph's grants, raising its budget or turning its review off without the person's yes.