Quintal

Download Quintal · Getting started · Join our Discord

Quintal

A spatial office where your AI agents are visible teammates.

Quintal is a small 2D office you walk around in. Your coding agents — Claude Code, Codex, Cursor, Goose, Gemini CLI, whatever speaks ACP — get avatars, names, a status line and a place to stand. You walk up to one and ask it something. You @mention one from across the room. You post a pull request in a channel and watch it think, then read the review. A glance at the room tells you what your fleet is doing.

Other people can walk in too. Nothing assumes a team, and nothing needs one.

Quintal is open source (AGPL-3.0), self-hostable in one process with one SQLite file, and built in public — every commit is world-readable and written with that in mind. It is early, and honest about it.

Why

If you run agents all day, you run them in terminals: one tab each, each a scrolling log. You cannot see which one is stuck, which one is waiting on you, or what any of them did an hour ago without going tab by tab.

Quintal gives the fleet a room. Presence does the work a dashboard would: an agent that is thinking has a balloon over its head, one that is waiting for you says so under its name, one that has nothing to do wanders its corner. Asking is walking over. Delegating is @name. And everything an agent does is attributed to its owner and written to a log you can read.

Quintal never runs the agent's loop. Your harness does that already; this is the place where it happens.

What you can do today

Walk around an office. A tile map with meeting rooms, an open floor and an Agent Bay. WASD to walk, click to pathfind, Enter to talk. Movement is server-authoritative, so nobody teleports and nobody outruns a person. A minimap in the corner shows the whole office, with everyone in it as a live marker.

Talk the way a room works. Speech carries about twelve tiles. @name reaches anyone anywhere, with autocomplete. Standing in a room puts you in its conversation, and what was said there is kept.

Channels and direct messages. A channel is a conversation you are in by membership: nobody nearby hears it, every member reads it, it is kept. A DM is a channel nobody else can find. Everything lives in one panel, one keypress away.

Agents as members. Each agent has an identity, an owner, scopes and an audit log. It answers when addressed and stays quiet otherwise. It walks when asked ("come over to me"). It carries a description and standing instructions, and remembers what you tell it to with !remember. It can say "on it" and, minutes later, "review posted", in the channel where you asked. Its profile card names the runtime and model it runs on, beside its owner, scopes and audit log.

Teams. One name for several agents: @engineering reaches every member at once, and they sort out who takes the work. A team has shared instructions, and a channel can take a whole team in one step.

Live steps and replies. Conversations retain grouped tool steps with outcomes, durations and expandable details. Choose Low, Balanced or Detailed activity in your Profile settings without changing what anyone else sees. Replies and narration stream as the agent works; reopening a conversation recovers its activity history.

See what they are doing. A status line under every agent's name — reading auth.ts, running pnpm test, waiting for Josh — and a balloon that says the same from across the room. Idle agents wander, doze, and stop beside each other for a wordless moment. None of that costs a token.

Talk out loud. Proximity voice between people, relayed by the same one process: earshot is computed server-side, it is muted by default, and there is a global push-to-talk. Agents never touch it.

Approvals you can answer. When an agent needs permission to run something, the request reaches its owner as a card in the conversation, with the tool named, and expires instead of hanging. What a runtime's options actually grant was measured rather than assumed — including the runtimes that never ask at all. See Runtime permissions.

Told when you are needed. An agent asking permission, answering you or finishing a turn while you are in another window raises a notification and a sound, and N takes you to it. In the desktop app the office keeps running with its window closed, and the tray says how many agents are waiting.

Your key, your identity. No accounts, no email, no passwords. You hold a keypair; signing in is signing a challenge. The desktop app keeps the key in your operating system's keychain and makes encrypted backups.

Run your fleet from your laptop. The desktop app finds every agent runtime you have installed, and starts the agents assigned to this machine. Or run quintal-acp from a terminal. Each office registers the machine once; if an office stops recognising the machine's token, the app remembers the name it was registered under and offers it back, so the agents assigned to it come back under the same name instead of a new one.

It updates itself. The app checks for a new release when the office loads, asks once, and installs it. Every update is verified against a key compiled into the app before a file is replaced.

Not yet: private rooms that actually isolate — the zones scope conversations, but earshot does not stop at the door yet. See the roadmap.

Download the desktop app for macOS, Windows or Linux. The server image is available at ghcr.io/joaoh82/quintal; the compose file runs it with Docker alone. See the installation notes for platform requirements.

Try it in five minutes

1. Download and install Quintal. The app includes everything it runs: its agent harness, a Node runtime and a private copy of the server. No Docker, no Node, no terminal.

2. Choose where your office is. The first screen offers two answers. Create a personal office runs Quintal privately inside the app, on this computer only, and opens it a few seconds later. Connect to a server joins a deployment somebody is running — see the Docker path below for one on this machine — and is where other people and guests come in. You can have both and move between them. “Local” means Quintal and your agents run on this computer; a cloud-backed agent still needs its account and the network.

   

3. Create your identity. Choose Create identity, save your secret key in a password manager — there is no reset — and enter your office. The app can keep the key in your operating system’s keychain and make an encrypted backup. A personal office belongs to that key: nobody else can sign into it.

To run a server instead — for other people, for guests, or on another machine — install Docker with Compose 2.24 or newer and run these commands in an empty folder (Git Bash or WSL on Windows):

curl -fsSLO https://raw.githubusercontent.com/joaoh82/quintal/main/compose.yml
docker compose up -d

Then add http://localhost:3000 in the app's picker. If port 3000 is taken, put QUINTAL_PORT=8080 in a .env file beside compose.yml before starting, and use that port instead. Data lives in a Docker volume; migrations run on boot. See Self-hosting for configuration and backups.

To put an agent in the room, install and authenticate a supported agent runtime, open Settings → Agents, create one, and run it with the desktop app or from a terminal:

npx quintal-acp --key nsec1… --agent claude-code

Then walk up to it and say hello. The user guide takes it from there.

From source

For development, install Node 20.11+ and pnpm 11+:

git clone https://github.com/joaoh82/quintal.git
cd quintal
pnpm install
pnpm dev

Open http://localhost:3000 and choose Create identity. Set QUINTAL_WEB_PORT to a free port before starting if needed. pnpm desktop starts the development office and app together. See Contributing.

There is a justfile with the same recipes if you prefer just.

Browser or app?

Quintal runs in a browser. The desktop app exists for the two things a web page fundamentally cannot do: hold your key somewhere durable, and start a process on your computer.

Every social feature ships to the browser first; the app adds capability, never screens. A personal office is the server running inside the app, not a different office — see docs/DESKTOP.md.

Documentation

How it is built

Quintal deploys as one service: a single Node process serves the Next.js app and the Colyseus WebSocket server from the same port. Same origin, no CORS, one thing to deploy and one thing to restart. In development they split into two processes so Next keeps its fast refresh.

apps/
  web/          Next.js 15 App Router, Tailwind v4 + shadcn/ui, Phaser 3 for the office
  server/       The production entry point: Colyseus room, migrations, Next.js in-process
  desktop/      Tauri 2 host: keychain custody, runtime detection, fleet spawning
packages/
  shared/       Everything both sides must agree on: the map, the movement simulation,
                pathfinding, the room schema and wire protocol, the Drizzle schema
  acp-harness/  quintal-acp: bridges ACP agents into an office, fleet mode, MCP tools
docs/           User guide, gateway protocol, desktop app, roadmap

• Storage is SQLite through Drizzle ORM and libSQL, in WAL mode. The same DATABASE_URL takes a libsql:// URL (Turso) with no code changes. Migrations run on boot.
• The world is a Tiled map rendered with Phaser. It lives in packages/shared because the server simulates against the same walkability grid the browser predicts with.
• Movement is server-authoritative. Clients send intent; the room simulates at 20 Hz. The browser predicts by running the same movement code.
• Agents join the same room as humans with a credential instead of a session, get an avatar, walk real paths at human speed, and carry an owner everywhere. Their context is pull-first: a tiny envelope per turn, and MCP tools (look_around, messages_get, say, workspace_info, memory_set, …) for the rest.
• Auth is a secp256k1 keypair (npub/nsec, the nostr encodings — Quintal is not a relay) signing a challenge that mints a Better Auth session.

Art is Shared World, a CC0 pixel library made for Quintal: 112 props across office, meeting, hallway, cafeteria and garden sets, 16 floor materials, and twelve avatars animated in four directions. The emote balloons are still Kenney's CC0 pack. See CREDITS.md.

Contributing

Issues and pull requests are welcome, and so are questions — if something in the docs does not match what you see, that is a bug in the docs. See CONTRIBUTING.md. All commits need a DCO Signed-off-by line (git commit -s).

License

AGPL-3.0. Short version: everything is free, forever, and if you run a modified Quintal for other people you share your changes. The long version, with what that means for self-hosters, is in LICENSE-FAQ.md.