# Show HN: Agent World – workflows and playbooks for multi-provider coding agents

> Source: <https://github.com/hodkep/agent-world/>
> Published: 2026-11-18 09:31:57+00:00

**Key takeaway:** Agent World gives each coding agent its own git worktree and an app-owned interactive `claude` or `agy` session, leaving `~/.claude` unmodified and blocking agent removal while uncommitted changes exist.

[Website](https://agent-world.in/) · [User guide](https://agent-world.in/docs/getting-started/) · [Changelog](https://github.com/hodkep/agent-world/blob/main/CHANGELOG.md) · [Latest release](https://github.com/hodkep/agent-world/releases/latest)

**Run and steer your coding agents from one place, shown as characters working in a pixel-art IT office.**

<sub>▶ The 52-second film (with a voiceover): every agent on its own branch, plans that wait for your word.</sub>

Each project is an office floor. Each agent is a character with its own git worktree and a real, interactive `claude` (Claude Code) or `agy` (Antigravity) session that the app owns. You see at a glance who is thinking, running, waiting for you or asleep, and you step in without hunting through terminals.

- **Control over spectacle.** Every visual state maps to a real agent state you can act on.
- **Own the session, don't scrape it.** The app launches and hooks the agents it shows. Your`claude` is unmodified, and nothing global in`~/.claude` is changed.
- **Never lose work.** Uncommitted changes block removal. Nothing is deleted silently.

1. **Download** the installer for your computer from the[releases page](https://github.com/hodkep/agent-world/releases) : on a Mac, the`arm64` dmg for Apple silicon (M1 and later) or the`x64` dmg for Intel. Open it and drag**Agent World** into Applications. If GitHub is slow for you, the same dmg is also on the project's mirror:[Apple silicon](https://dl.agent-world.in/latest/Agent-World-arm64.dmg) ,[Intel](https://dl.agent-world.in/latest/Agent-World-x64.dmg) . On Linux (beta, x64) take the deb or the AppImage from the releases page, or from the mirror:[deb](https://dl.agent-world.in/latest/Agent-World-amd64.deb) ,[AppImage](https://dl.agent-world.in/latest/Agent-World-x86_64.AppImage) ; the steps are in[INSTALL.md](https://github.com/hodkep/agent-world/blob/main/INSTALL.md#linux-beta) .
2. **Open it once.** The Mac app is not signed with an Apple Developer ID yet, so macOS blocks the first launch. On macOS 15 and later, try to open it, then go to System Settings > Privacy & Security and press**Open Anyway** . Older macOS and the terminal route are in[INSTALL.md](https://github.com/hodkep/agent-world/blob/main/INSTALL.md) .
3. **Follow the setup screens.** Nothing has to be installed first: the app carries its own`git` , and setup installs the Claude Code CLI for you and has you sign in once, in a terminal inside the app. Agent World runs your own`claude` and never handles your login. Antigravity (`agy` ) is optional.
4. **Hire.** Pick a project folder, click**+ Agent** , name it, and the character walks in.

Prefer Homebrew? These do steps 1 and 2:

```
brew tap hodkep/tap
brew trust --cask hodkep/tap/agent-world
brew install --cask hodkep/tap/agent-world
```

The cask removes the quarantine mark, so there is no Open Anyway step (that skips macOS's first-launch check for this app only). Homebrew 6 and later loads nothing from a tap that is not its own until you trust it, which is the `brew trust` line: once on each Mac, and needed again for `brew upgrade` if you skipped it (more in [INSTALL.md](https://github.com/hodkep/agent-world/blob/main/INSTALL.md)). Steps 3 and 4 still apply.

More in the [user guide](#user-guide).

Each agent works at a desk, and what the character does is what the agent does: thinking, researching, implementing, running, delegating or waiting for you. An agent that is asleep leaves the floor and stays in the agents panel. Click a character, or its tile in the panel, to open its chat.

The number beside the chat is the agents of the project: rest the pointer on it and a panel of tiles opens, one for each agent with its picture, name and what it is doing, and a red mark on the ones that wait for you. The number counts those to look at.

The project button works the same way: rest on it and a panel of your recent folders opens, each with its picture, how many agents work there and a red number when one of them waits for you. One click switches project.

The conversation of each agent is built from Claude's saved transcript and the real terminal: tool cards, edits as diffs, pictures, and dialogs for what the agent asks. Rewind, queue messages, or run a command with `!`. **Restart agent** starts the program again on the same conversation.

Agents draw diagrams in their replies and ask with forms. Click a box to pick it and ask about it, open the diagram large to zoom and draw on it, and answer a form with its button: the agent is told what the form held.

The message box shows markdown as you type it, with the marks hidden on every line but the one the caret is in. Commands, skills and files are tinted wherever they are in the message, and what is sent is what you typed.

`/btw` asks a side question without interrupting the agent: the answer shows in its own card in the chat.

A request shows above the character and in the panel. Allow or deny it in one click, or answer in the agent's own terminal. After five minutes it falls back to Claude's own dialog.

Each agent works on its own branch (`aw/<name>`) in its own git worktree, and the Code tab shows what it changed. With workflows on, git itself holds an agent's push of its branch, before the pull request, until the plan, the review and its findings are settled; you release it from the agent's chat.

A run is drawn as a flow diagram in the agent's **Workflow** tab, each step a card with where it stands.

A workflow is a plan you approve (with a note for the agent if you want one), checks that run, a review of the branch against the plan, and the pull request. The Runs tab charts how often each workflow ran and how well each stage was followed, over a ledger of runs grouped by what there is to do about them. A run belongs to the todo its agent is on, and the todo shows how its run stands. To make a workflow, describe it to the builder, a read-only agent that proposes one; to change one, start the builder from it. Either way you can edit the draft step by step before you save it, and every save is kept in the workflow's history. What the holds stop, and what they do not, is spelled out in [Enforced and only asked](https://github.com/hodkep/agent-world/blob/main/docs/guide/workflows.md#enforced-and-only-asked).

Skills, instructions and prompts kept once for every program, and a playbook that says which agent is told what, and when. The chat shows what the library did for each message.

One board for you and your agents: lists, tasks that need you, tasks an agent has claimed or finished. A `todo#14` in an agent's reply is a link to the task. A task can have subtasks, shown as a checklist with a progress bar on its card, and labels you add, rename and recolour; a task opens in tabs.

A small window of Markdown notes that stays above every other window (Option+Shift+Command+N). Each project has its own notes, checklists are drawn with boxes, and a line becomes a task, with its indented lines as subtasks, or is asked of an agent.

Your Claude 5-hour and weekly limits are the tanks on the lawn behind the office. Hover them to see what is left and when it resets; the **Usage** button in the top bar opens the full picture and counts the limits that are running low.

The **Tokens** tab of Usage shows where the tokens went, counted exactly as Claude Code and agy report them: fresh input, what the cache served, what was written to it and output, by provider, account, agent, project or model. The **Weekly Rewind** shows the week's cost and tokens with their rise or fall from the week before.

Sign in more than one Claude Code subscription, hire agents on any of them, and move agents between accounts without signing in again.

A drawer of your own shells under the office, starting in the project's folder. Each project keeps its own, and they are still there when you come back.

Cmd+/ lists every key: stepping between agents and projects, the tabs of the side panel, Notes, the terminals and more.

Hire `agy` (Antigravity) agents next to Claude Code ones. Setup finds both programs on your computer, and each agent gets its own worktree, chat, library and todos whichever program it runs.

Short, task-shaped pages, one for each area, each with a picture.

| Page | What it covers | 
|---|---|
| [Getting started](https://github.com/hodkep/agent-world/blob/main/docs/guide/getting-started.md) | Install, setup and your first agent | 
| [The office](https://github.com/hodkep/agent-world/blob/main/docs/guide/the-office.md) | Reading the office, hiring, waking, answering requests | 
| [Chat and dialogs](https://github.com/hodkep/agent-world/blob/main/docs/guide/chat-and-dialogs.md) | Talking to an agent and answering what it asks | 
| [Customize the look](https://github.com/hodkep/agent-world/blob/main/docs/guide/customize-the-look.md) | Asking an agent to restyle the app, keeping or undoing it, and widgets | 
| [Code and preview](https://github.com/hodkep/agent-world/blob/main/docs/guide/code-and-preview.md) | Changes, files, the terminal, tools, preview, finishing a branch | 
| [Workflows](https://github.com/hodkep/agent-world/blob/main/docs/guide/workflows.md) | Plans, checks, review, landing, Runs, Insights, the builder, and runs on the todo board | 
| [Library and playbook](https://github.com/hodkep/agent-world/blob/main/docs/guide/library-and-playbook.md) | Skills, instructions, prompts and when agents use them | 
| [Todos](https://github.com/hodkep/agent-world/blob/main/docs/guide/todos.md) | The shared board | 
| [Settings and updates](https://github.com/hodkep/agent-world/blob/main/docs/guide/settings-and-updates.md) | Preferences, accounts, providers, updates | 
| [Troubleshooting](https://github.com/hodkep/agent-world/blob/main/docs/guide/troubleshooting.md) | A blocked first launch, sign-in, a repository with no commits, no git | 

The app owns each session, so it does not have to guess what an agent is doing.

```
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1a1726', 'primaryTextColor': '#e4e4ee', 'primaryBorderColor': '#f2c230', 'lineColor': '#a4a2b8', 'secondaryColor': '#221e33', 'tertiaryColor': '#12101a', 'fontSize': '14px'}}}%%
flowchart LR
  you([You]) <--> app["<b>Agent World</b><br/>the office, chat and panels"]
  app -- "starts a terminal it owns" --> agent["<b>Agent session</b><br/>your own claude or agy"]
  agent -- "reports what it does:<br/>hooks, office tools, git hooks" --> app
  app -- "creates and cleans up" --> wt[("<b>git worktree</b><br/>branch aw/name under<br/>~/.agent-world/worktrees")]
  agent -- "edits and commits" --> wt
```

- **Hooks, not scraping.** Each agent is started with a per-session settings file that reports what it does (a tool call, a request, a stop) to the app. Nothing in`~/.claude` is changed.
- **Its own worktree.** Every agent works on a branch`aw/<name>` in`~/.agent-world/worktrees/<repo-slug>/<name>` , so agents do not overwrite one another. Removing one deletes its worktree only when nothing is uncommitted.
- **git held from outside.** An agent's`git` is pointed, through git's own environment variables, at the app's hooks folder, so a commit or a merge can be held whatever program made it. No file of your repository or your git configuration is touched, and your own terminal is untouched.
- **Short headless calls.** The usage limits, and the branch review when workflows are on, use short headless calls to your own`claude` or`agy` on your own account.

The latest version is on the [releases page](https://github.com/hodkep/agent-world/releases/latest); [CHANGELOG.md](https://github.com/hodkep/agent-world/blob/main/CHANGELOG.md) lists what changed in each.

- **macOS** is the platform it has been used on. The Mac app is not signed with an Apple Developer ID yet, so the first launch needs**Open Anyway** , and the app tells you when a newer version is out but cannot install it itself. The release workflow signs and notarises the build once the Apple signing secrets are set.
- **Linux** has a beta: an AppImage and a deb for x64, started on Ubuntu by the release build, and the deb installed and run in an Ubuntu 24.04 container; it has not been tried on a real Ubuntu desktop yet. The app tells you when a newer version is out but does not install it. See[INSTALL.md](https://github.com/hodkep/agent-world/blob/main/INSTALL.md#linux-beta) .
- **Windows** is not supported yet: there are no installers for it.
- **Programs:** Claude Code and Antigravity (`agy` ).
- **Next:** signed Mac builds, more agent programs behind the same seam ([docs/providers-design.md](https://github.com/hodkep/agent-world/blob/main/docs/providers-design.md) ), and further looks for the office.

Read [CHANGELOG.md](https://github.com/hodkep/agent-world/blob/main/CHANGELOG.md) for what changed.

You need Node.js 22 or newer and [pnpm](https://pnpm.io) 10.

```
pnpm install
pnpm dev            # the app, restarting on every change
pnpm build          # the production bundle in out/
pnpm test           # unit tests
pnpm typecheck
pnpm dist           # installers for this computer in dist/
```

`pnpm test:e2e` builds the app and runs the end-to-end tests with fake agents, so it needs no sign-in. The `pilot/` and `real/` suites run real agents, cost real tokens and need a signed-in CLI: see [CONTRIBUTING.md](https://github.com/hodkep/agent-world/blob/main/CONTRIBUTING.md).

Contributions are welcome. [CONTRIBUTING.md](https://github.com/hodkep/agent-world/blob/main/CONTRIBUTING.md) has the test rules, the commit format, and the one command that retakes every picture here (`pnpm shots`). [PRODUCT.md](https://github.com/hodkep/agent-world/blob/main/PRODUCT.md) says what the app is for and [DESIGN.md](https://github.com/hodkep/agent-world/blob/main/DESIGN.md) how it looks. The design notes are in [docs/providers-design.md](https://github.com/hodkep/agent-world/blob/main/docs/providers-design.md) (how an agent program is added) and [docs/workflows-design.md](https://github.com/hodkep/agent-world/blob/main/docs/workflows-design.md) (workflows, checks and the review). Security problems: [SECURITY.md](https://github.com/hodkep/agent-world/blob/main/.github/SECURITY.md). Everyone taking part follows the [code of conduct](https://github.com/hodkep/agent-world/blob/main/.github/CODE_OF_CONDUCT.md).

[Apache License 2.0](https://github.com/hodkep/agent-world/blob/main/LICENSE) from 0.2.0; versions up to 0.1.2 were published under the MIT licence and stay under it. The core is open: use it, change it, and send improvements. The maintainer may also offer separate commercial editions with extra features. The name and logo are not covered by the license: see [TRADEMARK.md](https://github.com/hodkep/agent-world/blob/main/TRADEMARK.md). Agent World is not affiliated with Anthropic or Google. The Claude and Antigravity marks in the app belong to their owners: see [NOTICE.md](https://github.com/hodkep/agent-world/blob/main/NOTICE.md).
