Version: 0.8.6 Last Updated: April 11, 2026
A guide to what Piper Morgan can do in the current alpha release.
Piper Morgan just closed its M1 “Foundation” milestone. If you tested an earlier build, here’s what changed:
See ALPHA_KNOWN_ISSUES.md for the full list of fixes and for M2 carryover issues you should know about.
| Task | How |
|---|---|
| Start Piper | python main.py → opens http://localhost:8001 |
| Check system health | python main.py status |
| Run setup wizard | python main.py setup or visit /setup in browser |
| Set preferences | python main.py preferences |
The easiest way to get started. Visit http://localhost:8001/setup after starting Piper.
What it does:
About the provider choice: you only need one provider to use Piper. Whichever you already have an account and key for is fine. You can swap later from Settings.
Known wrinkle: See #946 — setup may occasionally pick up a stale key from the system keychain. If it does, clear old “Piper” entries from Keychain Access. A consent prompt is coming in M2.
For terminal lovers: python main.py setup walks through the same process.
Run python main.py status anytime to verify:
The main interface. Type naturally and Piper responds.
Piper uses a two-layer approach:
The floor is the default. Handlers only win when they’re confident they can do the concrete thing you’re asking for.
Natural language Piper handles well:
| Category | Examples |
|---|---|
| Identity | “What’s your name?” “What can you do?” “Are you working?” |
| Time | “What day is it?” “What did we do yesterday?” “What’s on my agenda?” |
| Projects | “What projects am I working on?” “Status of [project]?” “Which should I focus on?” |
| Todos | “List todos” / “list my todos” / “show todos” — all now match the same pattern and return real data (or an honest “no todos” if your list is empty) |
| Actions | “Create a GitHub issue about X” “Give me a status report” “Complete todo 1” |
| Open-ended | “How should I think about this roadmap?” “What would you do here?” — these now reach the conversational floor and get real answers |
Fabrication discipline: the floor is instructed not to invent data it doesn’t have. If you ask about todos that don’t exist, you should get “I don’t see any todos in your list right now” — not a plausible-but-fake list. This is a first pass; if you catch a fabrication, please report it (issue #960).
Context quirk: A one-word reply like “OK” or “sure” after a multi-turn exchange may occasionally lose context (#922). If Piper seems confused, restate the request fully. A deeper fix is in M2.
You can complete todos by number or by name:
complete todo 1complete the deployment plan todomark the review todo doneAs of April 11, these actually persist to the database. Previously a three-layer bug meant the handler looked successful (23 tests passed) but the write never made it through the repository stack. Fixed.
To verify: complete a todo, reload the Todos view, confirm it’s marked complete.
Create standup reports through conversation.
How to use:
/standupCurrently disabled. The conversational floor handles first interactions instead. This was a late-M1 decision: the onboarding wizard was hijacking sessions that would have been better served by natural conversation. It may return in a later milestone in a different form.
All three work similarly with full CRUD and sharing:
| Action | How |
|---|---|
| View | Click “Your Stuff” → Lists/Todos/Projects |
| Create | Click “+ Create” button |
| Edit | Click item → Edit |
| Delete | Click item → Delete (if you’re owner/admin) |
| Share | Click item → Share → Enter email + role |
| Complete (todos) | “complete todo 1” / “complete the X todo” in chat, or check off in UI |
Sharing roles:
Upload and manage documents.
| Action | How |
|---|---|
| Upload | Files page → Upload (PDF, DOCX, TXT, MD, JSON up to 10MB) |
| Download | Click file → Download |
| Delete | Click file → Delete |
Files are user-isolated — you only see your own.
Projects and todos show lifecycle status badges:
Where: Settings → Integrations
Check the health of all your connected services:
Click “Test All” for a comprehensive check, or test individual integrations.
Setup: Settings → Integrations → Slack → Connect (OAuth)
What works:
Setup: Settings → Integrations → Calendar → Connect (OAuth)
What works:
Setup: Settings → Integrations → GitHub → Enter PAT token
What works:
Friendly pre-flight: if you ask Piper to create an issue before configuring GitHub, you now get a clear “GitHub isn’t connected yet — here’s how to set it up” message instead of a generic error. (Previously this produced an unhelpful “Something unexpected happened.”)
Setup: Added during setup wizard (API key)
What works:
Run python main.py preferences to set your preferences across 5 dimensions:
| Dimension | What it affects |
|---|---|
| Communication | How Piper phrases responses |
| Work style | Task recommendations |
| Decision making | How much guidance vs. options |
| Learning | Explanation depth |
| Feedback | How Piper gives suggestions |
Piper learns from your interactions over time:
This is experimental — feedback welcome on whether personalization feels accurate.
Piper is designed to be accessible:
| Data | Protection |
|---|---|
| API keys | Encrypted in system keychain |
| Passwords | Bcrypt hashed (12 rounds) |
| Sessions | JWT tokens with expiration |
| Resources | Owner-based access control |
All sensitive operations are logged:
| Command | Purpose |
|---|---|
python main.py |
Start server |
python main.py --verbose |
Start with detailed logging |
python main.py --no-browser |
Start without opening browser |
python main.py setup |
Run setup wizard |
python main.py status |
Check system health |
python main.py preferences |
Set user preferences |
python main.py migrate-user |
Migrate user data |
| Command | Purpose |
|---|---|
/standup |
Start interactive standup |
/help |
Get help |
For alpha testers who want to know what’s under the hood:
Last Updated: April 11, 2026