Set Up Agent Quest on macOS: From Installation to Your First Agent

Check the prerequisites

You need Git, Bun 1.1 or later, and a Claude Code or Codex installation that writes supported session logs on this Mac. Check the tools in Terminal:

git --version
bun --version

If Bun is missing, follow the installation instructions linked from the repository. Agent Quest depends on Bun even if you prefer npm commands for running scripts. You also need access to GitHub and package downloads during setup.

Choose a directory where you keep projects, and open Terminal there. If you already installed Agent Quest, use that checkout instead of cloning a second copy into the same location.

Clone and install

git clone https://github.com/FulAppiOS/Agent-Quest.git
cd Agent-Quest
bun install
bun start

The first command downloads the project. The second enters its directory. bun install installs the workspace dependencies. bun start starts the backend and browser client together; keep this terminal open while you use the dashboard.

With the default configuration, the backend uses port 4444 and the browser interface uses port 4445. Open http://localhost:4445 on this Mac if the browser does not open automatically. Seeing the village confirms that the interface loaded; it does not yet confirm that a coding session was detected.

Make the first session recognizable

In your usual coding tool, open a familiar project and ask for a read-only explanation of a file. Leave Agent Quest running and give the log discovery a moment to update. Find the new or resumed session in the party bar, then select it and compare its project and activity with your terminal.

The expected result is a matching session, not a particular hero costume or an exact animation time. If the village loads without agents, follow the troubleshooting guide rather than repeating the installation. Historical log files alone do not necessarily represent a currently active session.

Stop and return later

For the manual setup, press Control-C in the terminal running bun start when you want to stop the dashboard. To return, open Terminal in the same Agent Quest directory and run bun start again. Stopping this dashboard does not replace stopping tasks in your coding tool.

The repository also offers a guided macOS installer and an optional agentquest launcher. Those are conveniences; the manual setup above does not require them. The update shortcut is intended for installed copies tracking the main branch. If you edit Agent Quest itself, use a normal Git workflow and preserve your local changes before updating.

Once one session is visible, the multiple-agent guide explains how to keep separate projects identifiable.