Guildlings 한국어

Docs

Everything Guildlings does, on one page.

Installing it

Windows

Windows 10 (1809 or later) or 11, 64-bit. Download the installer and run it; it installs for your Windows user only, so it does not ask for an administrator. The Windows build is not code-signed yet, so the first run shows a blue "Windows protected your PC" panel: press More info → Run anyway. Guildlings then lives in the tray by the clock — on Windows 11, under the ^ arrow if the icon is hidden. Click it to show the characters, right-click it for the menu and Settings…. Closing the settings window keeps it running.

macOS

macOS 11 or later, Apple silicon or Intel — one file for both. Open the .dmg, drag Guildlings to Applications and open it from there. It is notarized by Apple, so it opens without a warning. It lives in the menu bar at the top of the screen: click it to show the characters, right-click it for the menu.

On both, the first launch opens Settings → Devices, where you choose the tools to watch (next section). Guildlings starts when you sign in to your computer — untick it under the version in Settings → General if you would rather start it yourself. It checks for updates every few hours and each time you open Settings, downloads them in the background, and installs them the next time it starts, when you quit from the tray, or at once with Install under Settings → General. Nothing pops up; after an update, Settings → General says updated to and the new version, once.

A Linux server Soon

A machine with no screen runs the relay node, which sends its sessions to your other machines. Linux on x86-64, no root needed: 

curl -fsSL https://github.com/poorants/guildlings/releases/latest/download/install-node.sh | sh

It puts guildlings-node in ~/.local/bin, prints a link to approve in any browser with your Natdal account, and runs as a systemd user service. Run it again to upgrade. Then turn its hooks on with guildlings-node hooks on. If the service should keep running after you log out, the script tells you the one loginctl enable-linger line to run.

Turning the hooks on

Guildlings finds your sessions from the files your coding tools already write. A hook adds what files cannot tell: the moment a session stops to ask for your permission, which tool it is using right now, and the newest thing you told it. Without hooks the characters still stand and walk, but a session waiting on you looks like one that has paused — the blocked alert needs the hook.

  1. Open Settings → Devices. Under This PC (This Mac on a Mac) there is one row for each coding tool found on the computer: Claude Code, Codex CLI, Antigravity (agy), Cursor, Gemini CLI, Copilot CLI, Windsurf.
  2. Tick the tools you want watched. A tick adds Guildlings' lines to that tool's own settings file and leaves everything else in it alone. Nothing is ticked for you, and a tool you install later shows up unticked.
  3. Start a session in that tool. Its row says connected once the hook has been heard from, and a character walks onto your taskbar or the Dock's edge.

Claude Code: the lines go into ~/.claude/settings.json, and a copy of that file is saved beside it first. Guildlings also takes the status line's place in order to read the session's cost and limits, and passes your own status line through, so it looks the same as before.

Codex: the lines go into ~/.codex/hooks.json, and Codex runs a new hook only after you approve it once. Until it does, the row says approve once in Codex. In Codex, type /hooks and pick Trust — the Copy /hooks button on that row puts the command on your clipboard.

If a row says config changed, some of Guildlings' lines were taken out of that tool's file; Put it back restores them. To take a hook out, untick the tool: Guildlings removes its own lines, and gives Claude Code back its own status line. Uninstalling on Windows takes every hook out for you. On a Mac, untick the tools before you move Guildlings to the Trash, so no tool is left calling an app that is gone.

What the characters are telling you

One live session is one character. Its body is its state:

  • Walking, with a swing of its weapon now and then — working.
  • Standing still — thinking.
  • Standing still with a small zZ drifting over its head — its turn is finished and it is waiting for your next message.
  • A red outline, and a speech bubble that does not fade — waiting on you: a permission prompt, naming the tool it wants, or a question. It keeps calling until you answer. This needs the hook.
  • Grey and faded — not observed: the session is there, but Guildlings has nothing yet on what it is doing.
  • Small characters walking behind it — the subagents that session started, each with its own state. Up to five follow; the rest are counted as "+n".

The speech bubbles are the characters' own lines, not your text. Click a character for the whole turn: the order it was given, what it is doing now, the last eight things it did and how long each took, the branch, the permission mode, the model and the tokens — with a tab for each subagent. Escape, a click outside, or a click on the character again closes it. Right-click a character to choose its face. Drag one to move its party to another monitor; which monitors they stand on is set in Settings → General. To put them all away for a while, press Ctrl+Alt+H (Ctrl+Option+H on a Mac) or untick Characters in the tray menu; the same again brings them back.

Your other machines Soon

Guildlings is in early access and Plus is not on sale. Today's version still keeps this — and the relay node on a Linux server — behind Plus; it opens to everyone in an upcoming version.

  1. Install Guildlings on each computer, or the relay node on a Linux server.
  2. On each one, press Sign in under Settings → Plan and approve it in the browser with the same Google or GitHub account. That computer stays signed in; there is no password of ours.
  3. The other machines appear under Settings → Devices, and their sessions stand on your taskbar next to the local ones, tagged with the machine's name. They connect device to device, end-to-end encrypted.

Untick a machine to let it rest: it is not connected, and the usage already copied from it is kept. Each machine sets its own hooks. Remove, then confirm, takes a machine off your account and cuts it off at once — do that for a computer you sold or lost. For personal use there is no device limit in practice; one account is capped at 20 devices in use at a time.

The usage dashboard

One panel with what your agents used and roughly what it cost. Press Ctrl+Alt+G (Ctrl+Option+G on a Mac), or Open now in Settings → Dashboard. It opens on the monitor under your cursor; the hotkey again, Escape, or a click outside closes it.

Both hotkeys — Ctrl+Alt+G for the dashboard and Ctrl+Alt+H for the characters — are on from the start. Change or clear either under Hotkeys at the top of Settings → Dashboard. If another app already holds a key, its row says so; choose another.

  • Period: today, this week or this month.
  • One card per machine, this one included, and the total last. With no other machine connected there is one card, this computer's. A machine that is not answering keeps its card, marked with how old its numbers are.
  • Each card: cost, tokens with input, output and cache kept apart, the cache hit rate, models, tools and turns, and the five-hour window — time left, and how fast you are using it.
  • Dollar figures are estimates (~$) at list prices. A model whose price is not known is left out of the cost and marked ·?; Cursor does not record token counts, so its sessions show as ·?.

The record is a file on your computer, written from the day you install it, and it is free and kept for good — so last month is still there after your coding tool has deleted its own transcripts.

Getting help

  • Refunds: Settings → Plan → Request refund, within fourteen days of a payment. See the refund policy.
  • Anything else: press Contact support in Settings → General — it opens a mail to guildlings@natdal.app with your system and the app version filled in. If the app will not open, write there yourself: say whether it is Windows or macOS and which version, the Guildlings version, and what you did just before it happened; a screenshot helps.
  • Bugs can also go to the issue tracker on GitHub.