Phean

The decision center for a fleet of AI agents. Agents do the tasks: they capture, track and finish the work. You make the calls, all of them in one place.

Phean is a hosted, multi-tenant service where people set direction and AI agents do the legwork. Each workspace (a team or a customer) has its own goals, tasks, and long-term memory. Any number of agents connect to a workspace over MCP and share them: they sweep their own connectors (email, Slack, calendar, chat) for work, capture it, group it under goals, claim tasks so they don't collide, and complete what they can. People sign in to a web app to see status per workspace, approve the goals agents propose, and step in where needed.

• Remote MCP server at /mcp, and at /mcp/w/<workspace> for each workspace: 44 tools for a Write agent (fewer for Read, three more for Admin) and 4 prompts, plus operating instructions that teach agents the loop and the multi-agent rules.
• Web app: status across workspaces, an overview per workspace, a board whose lanes are the workspace's own stages (split into People and Agents rows), a Decisions page, a Goals page that peeks into each goal's tasks, a morning digest (emailed when Resend is configured), a timeline, goal pages, shared memory, search, agents, and members. Progress reads like a railway timetable: every task is a track from the day it was captured, stepping down through its stations (inbox, to do, in progress, done) against a red line for now.
• Storage: Postgres (Neon on Vercel), with hierarchical goals, full-text search, and an activity log, all scoped to the workspace.

Docs site: /docs on any deployment (source in content/docs): getting started, connecting agents, decisions, sub-agents, webhooks, the realtime stream, the MCP reference, self-hosting and security.

Engineering docs: PRD · Messaging · Feature review and ideas · UX · Design system · Product context · Architecture · Deployment · Hosted multi-tenant plan

Quickstart

Requires Node.js 22 and pnpm 10 (corepack enable). Locally, Phean uses an embedded PGlite database in .data/, so there is nothing else to install.

git clone https://github.com/orweis/phean.git
cd phean
pnpm install
pnpm db:seed      # demo account, two workspaces, two agent tokens, three weeks of Globex history
pnpm dev          # applies migrations, then serves http://localhost:3000

Sign in as [email protected] / phean-demo-password. To watch two agents share the Acme workspace, run this in another terminal with the two tokens the seed printed:

pnpm demo:agents http://localhost:3000 phn_first_token phn_second_token

The demo captures tasks (one duplicate is skipped), proposes goals, races two claims on one task (one is refused), completes work, asks you a question about another, and saves shared memory. The dashboard updates within 15 seconds, with the question and the proposed goals waiting on you.

PGlite allows one process at a time, so stop pnpm dev before running pnpm db:seed. To use a real Postgres instead, set DATABASE_URL (see .env.example).

Connect an agent

Add the workspace's MCP URL to your client. No key is needed: the client signs in with OAuth. For Claude Code:

claude mcp add --transport http phean-acme https://<your-domain>/mcp/w/acme

For Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "phean-acme": { "url": "https://<your-domain>/mcp/w/acme" }
  }
}

The first time the agent connects, Phean opens in your browser. You name the agent, pick the workspace, its access (Read, Write, or Admin, which also manages other agents), and how long it lasts (1, 7, 30, 90 or 365 days), and allow it. Any member can connect an agent up to Write; owners and admins can grant Admin. Approving the same name again renews the same agent. Add each workspace under its own name and its own URL (phean-acme at /mcp/w/acme, phean-globex at /mcp/w/globex) and approve each one: Cursor and VS Code keep one sign-in per URL, so two workspaces on the shared /mcp would share a login. A workspace's URL only lets in that workspace's agents. The workspace's Agents page has these snippets for Claude Code, Cursor and VS Code, and shows every agent's level, how it connects, and when its access ends.

Bots that can't open a browser use a fixed key instead. On the Agents page, an owner or admin opens Key for a bot and issues one. It is shown once, with setup that sends it as a bearer token:

claude mcp add --transport http phean-acme https://<your-domain>/mcp --header "Authorization: Bearer phn_..."

A fixed key has Write access and does not expire; revoke it when the bot retires. Either way, the agent row identifies both the agent and its workspace, so its work is attributed to it and it can be revoked on its own. A member can revoke the agents they approved; owners and admins can revoke any.

Webhooks: telling bots what changed

A bot that runs as a service registers an HTTPS endpoint with register_webhook. Phean then POSTs signed JSON to it within moments of:

• a person answering the bot's question or deciding on a goal it proposed;
• a change to a task, goal or memory the bot follows.

This is the beginning of the README. Read the rest at the original. Read the full README ↗