A PM agent that turns raw inputs — tickets, transcripts, docs — into polished artifacts. PRDs, user stories, release notes, status updates. Every external write requires your approval before it executes.
git clone <repository-url> && cd Meridian
# Install everything
npm install && npm --prefix web install
# Interactive setup — creates .env and your first workspace
npm run setup
# Start both servers (API + web)
npm run devOpen http://localhost:3001 and type your first prompt.
- Node.js 20+
- Anthropic API key (
ANTHROPIC_API_KEY)
| Skill | Status | What it does |
|---|---|---|
| PRD Drafting | Live | Turn raw inputs into structured PRDs with citations |
| User Stories | Coming | Decompose feature briefs into stories with acceptance criteria |
| Status Updates | Coming | Generate stakeholder updates from tickets and blockers |
| Release Notes | Coming | Changelog/diff to user-facing release notes |
- You type a prompt in the web UI
- The agent reads your workspace context and picks the right skill
- It streams its work back over SSE — you see every step live
- External writes (tickets, Slack posts) surface as approval cards — you approve or decline
- Everything is logged as JSONL in
/sessionsfor full auditability
| Command | Description |
|---|---|
npm run dev |
Start API (:8787) + web (:3001) together |
npm run dev:api |
Start API server only |
npm run setup |
Interactive setup wizard |
npm run typecheck |
TypeScript check (root) |
npm run evals |
Run evaluation harness |
npm --prefix web run dev |
Start web app only |
npm --prefix web run typecheck |
TypeScript check (web) |
src/agent/ Agent loop, tools, skill loader, session store
src/api/ Hono server, SSE streaming, approval endpoints
src/extensions/ External connectors (Linear, Slack — stubs for now)
web/ Next.js 15 frontend (App Router, React 19)
sessions/ JSONL session logs (auto-created)
skills/ Markdown skill definitions
workspaces/ Per-workspace CONTEXT.md files
evals/ Evaluation dataset and harness
Each workspace has a CONTEXT.md in workspaces/<id>/. The agent reads
this on every run. Include:
- Product vision — one-liner
- North-star metric — what success looks like
- Conventions — priority labels, terminology
- Key resources — tracker URL, docs links
The setup wizard creates your first one. Edit it anytime.
| Variable | Required | Default | Notes |
|---|---|---|---|
ANTHROPIC_API_KEY |
Yes | — | Claude API key |
PM_AGENT_MODEL |
No | claude-sonnet-4-6 |
Model for agent runs |
PM_AGENT_MAX_TURNS |
No | 30 |
Max agent loop turns |
PORT |
No | 8787 |
API server port |
Port conflict: Change PORT in .env (API) or edit web/package.json
dev script port (web).
Agent not responding: Check ANTHROPIC_API_KEY in .env. If a session
hangs, look for an unapproved action in the UI.
Stale sessions: Sessions are JSONL files in /sessions. Delete any to
clear history.
Architecture & contributor docs
- User submits prompt via Next.js web app
POST /sessionshits the Hono APIrunAgent()starts the Agent SDKquery()loop- Tools execute — gated tools emit
approval_requestedover SSE - User approves via
POST /approvals/:id - Agent continues; response streams back via SSE
- Every event persisted to JSONL before streaming
Single agent + skills. System prompt = core (<1000 tokens) + workspace
CONTEXT.md + at most one skill fragment. settingSources: [] for hermetic
runs.
| Primitive | Gating |
|---|---|
| Read (Glob, Grep) | Auto-allowed |
| Write (drafts) | Human approval |
| Search (past sessions) | Auto-allowed |
| Act (tickets, posts) | Human approval |
Line types: user, assistant, tool_call, tool_result, meta.
Meta lines hold skill state, branch pointers, token usage — never sent
to the model.
Markdown with YAML frontmatter (name, triggers, allowed-tools) + system prompt fragment. Loaded on intent detection only.
- In-memory approval map — single node only (no horizontal scaling yet)
- No auth — Clerk middleware slot exists but isn't wired
- Connectors are stubs — Linear and Slack return placeholder responses
- Session search is full-text scan of JSONL files