Metadata-Version: 2.4
Name: liquid-ppm
Version: 0.3.0
Summary: ppm CLI — your hosted project manager (Slack bot + daily digests)
Project-URL: Homepage, https://github.com/Liquid4All/ppm
Author: Liquid AI
License-Expression: MIT
Keywords: claude-code,cli,project-management
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<p align="center"><img src="PPM_LOGO.png" alt="ppm" width="220" /></p>

# ppm — your project manager

A hosted PM agent for your projects. It sweeps **GitHub**, **Linear**, and your
**coding sessions**, measures activity against the goals you set per project, and:

- DMs you a **daily digest** every weekday morning — what moved, what's blocked,
  what needs your attention, what drifted
- keeps an always-current **status rollup** (Slack App Home, `ppm status`)
- **triages** anything unmapped — assigned issues and new-work candidates land in
  an inbox you resolve by adopt or ignore, never silently dropped
- lets you **chat** with it in Slack: "what needs my attention?", "put X on hold",
  "create a project for Y"

You own your projects' goals and lifecycle status; the agent only ever writes two
fields per project (`focus`, `last-activity`) and *suggests* everything else.

## Getting started

1. **DM the `ppm` bot** in Slack — it creates your account, matches your Linear by
   email, and verifies your GitHub handle against the org.
2. **Connect this machine** when it offers (or any time — DM "add a device").
   Install the CLI with [uv](https://docs.astral.sh/uv/) (the published command
   is `ppm`; the PyPI distribution is `liquid-ppm`):

   ```bash
   uv tool install liquid-ppm                                  # from PyPI
   uv tool install git+https://github.com/Liquid4All/ppm.git  # pre-publish, from git
   ```

   Then enroll the device:

   ```bash
   ppm login --code <code-from-slack>
   ```

   `login` enrolls the device, registers the Claude Code skill, and installs the
   session-pusher hooks. After that, each Claude Code session on this machine
   uploads a **capped slice of its raw transcript** (the most recent ~10 MiB,
   plus a short extract: first prompt + summaries) to **your own scope** in the
   hosted service over the authenticated API — no cloud credentials live on your
   machine, only the device token. That transcript text is what feeds your digest.
   The bot pings you in Slack the moment the device connects, with project
   suggestions drawn from your repos, Linear, and sessions.
3. **Confirm your projects** in the DM (it proposes; you decide), give each a
   couple of sentences of goal — that's the yardstick the digest measures against
   — and ask for a test digest.

## CLI

```
ppm status                    current rollup
ppm digest [YYYY-MM-DD]       digest markdown
ppm projects list|show|set    manage projects (set: --status, --watch)
ppm projects create --name X --repos org/a,org/b --linear "Team (owner)" --goal "..."
ppm projects note <name> <t>  append a dated note to a goal body
ppm projects link <name> <mapping> [--owner]
ppm linear                    Linear teams/projects available for linking
ppm triage [adopt|ignore <id>]
ppm devices [add|revoke <id>]
ppm import <PROJECTS.md> [--commit]   migrate a markdown project list
ppm review                    pull digest+status, open Claude Code over them
ppm update                    self-update (uv tool upgrade liquid-ppm)
ppm instructions              full reference (agents: run this first)
```

`login` also registers a `ppm` skill in Claude Code, so any local Claude session
can read and act on your projects through the same API the Slack bot uses — one
write contract everywhere.

## How it works

- **Backend** ([Liquid4All/ppm-backend](https://github.com/Liquid4All/ppm-backend)):
  FastAPI on Fly, Neon Postgres (identity, projects, runs), Tigris S3 (immutable
  activity snapshots, digests, transcripts). A daily pipeline fetches org activity
  once, then runs each user's digest agent (Claude, narrow buffered-write tools,
  validators before publish). Every agent action is audit-logged with a retained
  transcript.
- **This repo**: the zero-dependency Python CLI + session pusher (`uv tool install
  liquid-ppm`). The full system design lives in [HOSTED-DESIGN.md](HOSTED-DESIGN.md).
- **Trust model**: your sessions and personal data stay in your own scope. The
  session pusher uploads a capped slice of raw transcript to *your* scope (see
  Getting started); the *digest agent* then references that work as project +
  one-line topic, and what's shared with teammates is never raw excerpts. Uploads
  go only to `https://ppm-backend.fly.dev` over HTTPS — the client refuses any
  other host unless you explicitly set `PPM_ALLOW_INSECURE_API=1` for local dev.
  Team features (channel digests, publish-up progress sharing) are designed in
  HOSTED-DESIGN.md §5 and arrive next.

## Support

Questions, ideas, bugs — **@jbuchananr** on Slack.
