Project Magic

See every project your AI agents are building, without asking each one.

When AI coding agents build your software, they keep the backlog and the build plan as markdown in each repository. Project Magic reads those files, the branches and the pull requests across all your repositories, and shows what is planned, what is in flight, what is done, and what is waiting on you. When you need to change something, an edit made in Project Magic is an ordinary commit to the backlog, made as you.

• One place for every project. A card per repository: what is in progress and on which branch, what is in review, what is blocked and why, the plan's progress and its next task.
• What is waiting on you. Items that are built (merged, waiting on a person's acceptance check) or blocked carry what they wait on, so your own queue is on the front page.
• The files stay the record. Status is derived from the backlog, the plan, branches and pull requests. Nothing is kept anywhere else, and agents and people read the same files.
• Per project: the backlog as a list in priority order, a board, the plan, what has shipped (found from git history), every branch with what it is working on, and the documents.
• Editing: change an item, add one, drag to reorder, remove one. Each edit is a commit on a projectmagic branch whose pull request is merged straight away, so main is never behind.

It runs on your own accounts: a GitHub App, a Postgres database and a host for a SvelteKit app. Setting up takes under an hour.

Status: in use by its author. Teams are built: tenants, invitations, and roles that follow GitHub permissions (specs/tenants.md, PM20).

Contents

• How it works
• The conventions
• Setting up
• Adding a repository
• Developing
• Where things are
• Licence

How it works

1. The agents in each repository follow a few conventions (below): every backlog item is a ### heading that starts with an id and has a status line under it, branches name the item they work on, and pull requests say what they build.
2. A GitHub App reads the repositories it is installed on. A push or a pull request reaches Project Magic by webhook within seconds, and a sync fetches the branches, their pull requests and the tracked files in two GraphQL calls, parsing only files it hasn't seen before. A daily cron re-syncs everything in case a webhook was missed.
3. Status is derived, in order (spec.md §7.2): an item removed from main's backlog, or marked done, is done; one with an open pull request is in review; one marked todo or blocked that has an active branch is in progress; otherwise its status line says. When the backlog and the plan disagree, the disagreement is shown, never resolved for you.
4. Edits go through git. Project Magic commits the change to a branch named projectmagic with your own GitHub token, opens a pull request, and squash-merges it. If the merge is refused (a review is required, say), the pull request stays open and the edit shows as pending.

spec.md is the full specification, and docs/architecture.md draws the system as three C4 diagrams.

The conventions

A repository connected to Project Magic gets a short form of these in its AGENTS.md and CLAUDE.md (see Adding a repository). The full block is in specs/conventions.md, to paste into a repository set up before that. In short:

### OR12 Invoices as PDF — MONEY
**Status:** in progress · **Size:** M · **Branch:** `feat/or12-invoices` · **Plan:** 3.4

Why it matters, what is decided, what is left.

• Items are ### headings starting with an id: letters and a number (OR12, A1a), or a plan task's number (3.4). Ids are never reused. ## headings are sections, and order is priority. A heading without an id is a note.
• The status line comes first under the heading and begins with **Status:**: todo, in progress, blocked, in review, built or done. Waiting: says what a blocked or built item waits on; Branch:, Plan: and Size: are optional.
• Branches are named <type>/<ref>-<slug>, such as feat/or12-invoices, and are pushed as soon as work starts.
• Pull requests say Backlog: OR12 and/or Plan: 3.4 in their description.
• The plan (PROGRESS.md, optional) is any table whose first column is # and that has a Status column whose cells begin with done, todo, in progress, blocked, built or skipped.
• The branch name projectmagic is reserved for Project Magic's edits.

An existing backlog can be migrated in one pass; specs/conventions.md has a checklist.

Setting up

You need:

• Node.js 24 and npm, to build and to run it locally;
• a GitHub account, to own the GitHub App;
• a Postgres database: Neon's free tier is enough, and its pooled connection string is what the app expects;
• a host for a SvelteKit app: it is configured for Vercel (the webhook needs a public URL, and the daily sync uses Vercel Cron).

1. Get the code

git clone https://github.com/seethespark/projectmagic.git
cd projectmagic
npm ci
cp .env.example .env

2. Register a GitHub App

GitHub → Settings → Developer settings → GitHub Apps → New GitHub App:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗