Agent World
Website · User guide · Changelog · Latest release
Your agents skip the process. Agent World makes them follow it.
Coding agents jump straight to editing, ignore the skills you wrote and commit to the wrong branch. Agent World runs your own Claude Code or Antigravity sessions through a process you write down: plan, build, checks, review, pull request. Git holds an agent's edits, commits and push until the plan and the review are settled, and nothing is pushed until you press **Run**. One playbook says which skills and instructions each agent is told, and when, and the app measures whether agents read them and flags the rules they ignore. A manager for skills, MCP servers and tools shows what is installed and what is used, and the built-in Preview lets agents open, click and screenshot the page they just built.
The holds stop an agent that follows its instructions from getting ahead of you. They are a guard rail, not a lock against an agent set on getting round them ([what they stop and what they do not](docs/guide/workflows.md#enforced-and-only-asked)).
A real run: the plan to check before the build starts, and the card that waits for you before anything is pushed.
- **Control over spectacle.** Every state in the app maps to something real 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.
##
Quick start
1. **Download** the installer for your computer from the [releases page](../../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](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](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](INSTALL.md)). Steps 3 and 4 still apply.
More in the [user guide](#user-guide).
## Features
###
Workflows and the push hold
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. Each agent works on its own branch (`aw/`) in its own git worktree, and the Code tab shows what it changed. With workflows on, git itself holds an agent's edits until the plan is approved, and holds its commits and its push of its branch, before the pull request, until the plan, the review and its findings are settled; you release the push with **Run** on the card in 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. 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](docs/guide/workflows.md#enforced-and-only-asked).
###
Library and playbook
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.
The **Usage** tab judges each rule on the prompts that looked related to it: how often it was reminded, read and said no to, with a fix for the ones that are flagged (write a narrower "when", make it firm, make it a step).
###
Skills, MCP servers and tools
The **Playbook and tools** window lists every skill, MCP server and tool the programs know, in one place. **Skills**: add the ones you already have, install new ones from a GitHub repository, write instructions and prompts; each shows where it lives and who used it in the last 30 days. **MCP servers**: the servers the programs' own files name, in a panel for each place; connect one to see what it offers, test an entry before you save it, or take it out of one project or every place. **Tools**: Claude Code's own tools and those of each server, each set to Allow, Ask or Deny for the agents the app runs.
###
Preview
**Preview** shows a web page beside the chat: the dev server an agent started appears on its own, and so can a page file or a site. Resize it to Desktop, Tablet or Mobile, and use **Select element** to click something on the page and send it to the agent as words and a picture. Agents can drive their own Preview page with a browser tool: they open pages, read them, click, resize to a phone and take screenshots, in a frame that names the agent and has a cross to disconnect it. A site on the internet opens only once you allow it, and a page whose certificate fails shows a warning first.
###
Todos
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.
###
Also: the office

▶ The 52-second film (with a voiceover): every agent on its own branch, plans that wait for your word.
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.
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.
###
Chat
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.
###
Diagrams and forms in the chat
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.
###
A message box that draws markdown
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.
###
Side questions with /btw
`/btw` asks a side question without interrupting the agent: the answer shows in its own card in the chat.
###
Permissions answered in the world
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.
###
Notes
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.
###
Usage limits
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.
###
Tokens and the Weekly Rewind
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.
###
Accounts
Sign in more than one Claude Code subscription, hire agents on any of them, and move agents between accounts without signing in again.
###
Terminals for each project
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.
###
Shortcuts
Cmd+/ lists every key: stepping between agents and projects, the tabs of the side panel, Notes, the terminals and more.
###
Antigravity beside Claude
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.
## User guide
Short, task-shaped pages, one for each area, each with a picture.
| Page | What it covers |
| --- | --- |
| [Getting started](docs/guide/getting-started.md) | Install, setup and your first agent |
| [The office](docs/guide/the-office.md) | Reading the office, hiring, waking, answering requests |
| [Chat and dialogs](docs/guide/chat-and-dialogs.md) | Talking to an agent and answering what it asks |
| [Customize the look](docs/guide/customize-the-look.md) | Asking an agent to restyle the app, keeping or undoing it, and widgets |
| [Code and preview](docs/guide/code-and-preview.md) | Changes, files, the terminal, tools, preview, finishing a branch |
| [Workflows](docs/guide/workflows.md) | Plans, checks, review, landing, Runs, Insights, the builder, and runs on the todo board |
| [Library and playbook](docs/guide/library-and-playbook.md) | Skills, instructions, prompts and when agents use them |
| [Todos](docs/guide/todos.md) | The shared board |
| [Settings and updates](docs/guide/settings-and-updates.md) | Preferences, accounts, providers, updates |
| [Troubleshooting](docs/guide/troubleshooting.md) | A blocked first launch, sign-in, a repository with no commits, no git |
##
How it works
The app owns each session, so it does not have to guess what an agent is doing.
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1a1726', 'primaryTextColor': '#e4e4ee', 'primaryBorderColor': '#f2c230', 'lineColor': '#a4a2b8', 'secondaryColor': '#221e33', 'tertiaryColor': '#12101a', 'fontSize': '14px'}}}%%
flowchart LR
you([You]) <--> app["Agent World
the office, chat and panels"]
app -- "starts a terminal it owns" --> agent["Agent session
your own claude or agy"]
agent -- "reports what it does:
hooks, office tools, git hooks" --> app
app -- "creates and cleans up" --> wt[("git worktree
branch aw/name under
~/.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/` in `~/.agent-world/worktrees//`, 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.
##
Status and roadmap
The latest version is on the [releases page](../../releases/latest); [CHANGELOG.md](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](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](docs/providers-design.md)), and further looks for the office.
Read [CHANGELOG.md](CHANGELOG.md) for what changed.
##
Build from source
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](CONTRIBUTING.md).
##
Contributing
Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the test rules, the commit format, and the one command that retakes every picture here (`pnpm shots`). [PRODUCT.md](PRODUCT.md) says what the app is for and [DESIGN.md](DESIGN.md) how it looks. The design notes are in [docs/providers-design.md](docs/providers-design.md) (how an agent program is added) and [docs/workflows-design.md](docs/workflows-design.md) (workflows, checks and the review). Security problems: [SECURITY.md](.github/SECURITY.md). Everyone taking part follows the [code of conduct](.github/CODE_OF_CONDUCT.md).
##
Licence
[Apache License 2.0](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](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](NOTICE.md).