ClientDesk
From a vague idea to a working app—with the artifacts to build it again.
ClientDesk is a small CRM for a solo consultant. It brings clients, meeting notes, upcoming calls and follow-ups into one workspace, with Claude chat that can explain the evidence behind a suggested next step.
This is the reference project for Claude Code for Everyone: Next Steps, taught by Mark Kashef of Prompt Advisers. Follow the same path as the course: plan the product, define its design, build and inspect it, connect its tools, deploy it, and package a skill another person can run.
Interactive A–Z build playbook · Copy the A–Z prompts
Before you join · Download the slides · Try the live app · Start here · Complete build walkthrough · Exact course prompts
Actual hosted reference, using fictional clients. Screenshot dates are sample content. Hosted chat works on desktop and phone and requires the separately supplied course access code.
Start with the result
Open Northstar Studio in the live app or your local copy:
- Read the latest meeting and inspect its original source.
- Prepare a follow-up. Review the proposed title, owner and date before saving.
- Reload to confirm the saved task is still there; complete or reopen it.
- Export a pre-call brief as Markdown.
- With chat configured, ask: “What did Northstar ask for, and what is still undecided? Cite the source.”
- Try a client with no meetings. A useful response should acknowledge missing evidence.
You can also create and search clients, inspect upcoming calls, and import fictional meeting and calendar records. Importing the same source twice updates its existing record instead of creating a duplicate.
Choose your route
For live delivery, use the checkpoint runbook. It records the independent Fable Low rehearsal findings and explains when to show a prepared result.
The reference includes working source and lockfiles. A fresh build from the prompts may produce different code; compare it against the specification and repeat the checks on your own implementation.
Run locally
You need Node.js 24 and npm. Claude Code, signed into your own account, is needed for the guided build and optional local chat. The basic CRM can run without Claude, a cloud database or provider credentials.
Download this repository with GitHub’s Code → Download ZIP, then extract it. Or clone it:
git clone https://github.com/promptadvisers/claude-code-next-steps.git
cd claude-code-next-steps
This repository root is the Walkthrough Assets folder referred to in the slides. Open it as your Claude Code project. In a normal terminal:
node 00-course-map/prepare-demo.mjs
cd 03-build/clientdesk
npm ci
npm test
npm run typecheck
npm run dev
Open http://127.0.0.1:4310. Leave that terminal running. Use a second terminal for further commands.
The preparation script refreshes the fictional course dates and demo context. npm ci installs the locked dependencies. With no .env.local, the app saves practice data locally in SQLite under .data/. Keep that private generated folder out of Git and course distributions.
Prefer a plain-English request? Paste this into Claude Code with this project open:
Read README.md and 00-course-map/START-HERE.md. Check the required software, help me install anything missing, and start the supplied reference app. Explain each step. Use the fictional local data first. Show me how to open Northstar, review a follow-up, save it and confirm it after reload.
How the pieces fit together
flowchart TB
person["Person using desktop or phone"] --> app["ClientDesk web app · Next.js on Vercel"]
app <-->|"Read and save this visitor's workspace"| db[("Supabase · hosted records")]
app -->|"Selected client's evidence + question"| worker["Railway · chat worker"]
worker -->|"One noninteractive request"| claude["Claude Code · claude -p"]
claude -->|"Answer or draft"| worker
worker --> app
cli["ClientDesk CLI"] --> api["ClientDesk workspace API"]
mcp["MCP tools for Claude"] --> api
api --> app
sources["Fictional imports / optional provider reads"] --> app
Vercel serves the app. Supabase stores hosted workspaces. Railway runs Claude Code. In local mode, SQLite replaces Supabase and optional chat uses the Claude installation on your computer.
An API is an interface programs call. A CLI lets you request something through a terminal. MCP exposes named tools an assistant can discover and call. In this project, CLI and MCP both reuse the app's API; they are two entry points, not a mandatory API → CLI → MCP chain. See the connection primer and architecture notes.
Claude chat, in plain English
A worker is a small helper program that handles a request behind the scenes. Railway provides its online computer. Our helper receives a client question, runs Claude and returns the answer. Start with Hosting in plain English for the diagram, hosting vocabulary and explanation of the different access codes.
Headless means Claude runs without its usual interactive conversation screen. The app sends a question and context, Claude returns a result, and the app displays it. -p is Claude Code's print-mode option:
claude -p "Explain what a CRM does in one sentence."
The working integration adds controlled input, structured output, timeouts and tool restrictions. It is more than putting a shell command behind a chat box.
| Mode | Where Claude runs | Setup |
|---|
| Local chat | Your computer, using your signed-in Claude Code account | Local chat guide; opt in with CLIENTDESK_LOCAL_CHAT=1 in the app's private .env.local |
| Hosted course chat | A separate Railway worker, reached through the Vercel app | Plain-English explanation, then the setup guide |
The local subprocess route is disabled on Vercel. The hosted Railway route is a separate implementation and is available on phone and desktop. Print mode still consumes account usage allowance; it is not free or unlimited inference. Check your account's current plan and extra-usage settings before running your own service.
What does chat know?
The app supplies the selected client's profile, up to four recent meetings, ten calendar records, twenty tasks and the last six chat messages. Long text is excerpted. It does not send every client, arbitrary course files, or provider records that have never been imported.
The worker has no database credentials. Claude receives a bounded snapshot from the app, with source IDs. It has no filesystem, MCP or database-write tools in this chat path. Draft follow-ups still require the app's explicit review and save flow. Conversations live in the current page's memory; reloading starts a new chat. Saved CRM records remain in storage.
Everything needed to understand the build
| Location | What it contains |
|---|
| 00-course-map | Ordered walkthrough, exact prompts, six labs, instructor narration, demo preparation and headless examples |
| 01-planning | Brief, complete specification, milestones, decisions, rebuild instructions and fictional source records |
| 02-design | Navy visual direction, Manrope and DM Sans fonts, tokens, brand assets and architecture |
| 03-build/clientdesk | Next.js/React app, TypeScript domain logic, storage, migrations, adapters, CLI, MCP and tests |
| 03-build/clientdesk-chat | Railway worker, Dockerfile, pinned Claude Code dependency, authentication helper and tests |
| 04-verification | Recorded test evidence and screenshots; rerun the checks for your own build |
| 05-deployment | Vercel/Supabase instructions, local and hosted chat guides, deployment receipts |
| .claude | Reusable client-brief skill, examples, template, interface rule and optional hook configuration |
| BUILD-LOG.md |
The prompts are reusable teaching prompts, not a claimed verbatim transcript of development. This public course companion contains the sanitized source and documents, plus the current 160-slide PowerPoint. Instructor authoring files, previous decks, private session notes and account credentials remain in the private archive.
Connect the CLI, MCP and reusable skill
Keep the app running. From 03-build/clientdesk, inspect the supported terminal commands:
npm run cli -- --help
For MCP, start Claude Code from this repository root, review the project's .mcp.json, approve the trusted server and inspect /mcp. Then ask:
Use ClientDesk tools to find Northstar's latest meeting. Cite the source ID, explain which follow-up is supported, and identify what remains undecided. Do not save a task.
The browser has its own practice identity. CLI and MCP share a separate practice session by default, so an import in one workspace will not automatically appear in another.
The /client-brief skill packages a repeatable briefing workflow. Use its argument hints and the current demo context. The end-to-end guide explains how to test and distribute it, including the optional hook example.
Deploy your own copy
Follow stages 9–14 of the complete walkthrough in order:
- Create your own Supabase project, enable anonymous practice sign-in and apply both database migrations in filename order. Check isolation with two identities.
- Deploy
03-build/clientdesk to Vercel with Node 24 and your Supabase configuration. Verify saved records at the hosted URL.
- Deploy
03-build/clientdesk-chat to Railway using its Dockerfile and a persistent /data volume. Complete the documented Claude sign-in on the worker.
- Configure the private service token and course access code. Connect Vercel to the worker using the exact app origin, then redeploy.
- Ask a real question through your hosted app. Verify sources, missing evidence, incorrect access codes, cancellation and phone layout.
Environment variable names and setup details are in the linked deployment guides. Credentials, account sessions, course access codes, local database files and .vercel metadata must stay out of the repository. Your new deployment requires your own accounts and verification.
Verify the result
The public release checks passed on Node 24: 24 app tests, 6 worker tests, both typechecks, a production build and local HTTP persistence/isolation checks. These publication checks did not redeploy the hosted services.
Run from 03-build/clientdesk:
npm test
npm run typecheck
npm run build
# With the local app running in a separate terminal:
npm run test:http
For the worker, run from 03-build/clientdesk-chat:
npm ci
npm test
npm run typecheck
Automated checks cover different parts of the system. Also inspect the real browser, save and reload a task, test a second identity, and obtain an actual hosted Claude answer. A mocked worker test does not prove a deployed account is authenticated. See verification notes and the hosted verification receipt.
Common sticking points
| What you see | What to check |
|---|
| The local app will not start | Use Node 24, run npm ci in the app folder, and check whether port 4310 is already in use. |
| Ask Claude is missing locally | Follow the local opt-in guide, sign in to Claude Code and restart the development server. |
| Hosted chat is unavailable | Check worker health, authentication, course code, matching service tokens and the exact Vercel origin; follow the hosted guide. |
| An imported record is missing in another view | Confirm you are using the same practice identity; browser and CLI/MCP sessions differ. |
| Hosted saves fail | Check both migrations, anonymous sign-in, Supabase environment configuration and the deployed app's actual response. |
| Demo dates look old | Run the preparation script in an exercise copy and follow the guide for using refreshed sample data. Existing saved workspaces are separate. |
Scope and responsible reuse
This is a fictional course practice CRM. It includes durable hosted storage and visitor isolation. Named accounts, account recovery and shared team workspaces are not implemented. Clearing browser identity state may lose access to that practice workspace.
Fireflies and Calendly adapters exist, but live provider reads are optional and are not represented as verified connections. Provider logos identify example services; they do not imply endorsement. Font licenses and asset provenance are included in the design assets.
Use the completed reference to learn, compare and recover from a stalled exercise. Use the specification and your own checks to establish what your rebuilt version actually does.
