Pipes Setup

Guided, conversational installer. Run steps automatically — only pause for user input (Notion token, pipe shape). Use AskUserQuestion for all decisions.

Principle: Fix what you can. Only ask when it genuinely requires user action (creating a Notion integration, pasting a token, choosing a pipe shape).

1. Initialize Project

npx pipes init

This creates pipes.config.ts, pipes/, and .pipes-runtime/ in the current directory.

If this fails, ensure Node.js ≥20 is installed.

2. Notion Credentials

Check for existing token:

npx pipes doctor

If the doctor output shows the Notion token is missing:

1. Tell the user: "To connect to Notion, you need an integration token."
2. Direct them to https://www.notion.so/profile/integrations
3. Ask them to create a new internal integration named "Pipes"
4. Use AskUserQuestion: "Paste your Notion integration token (starts with ntn* or secret*)"
5. Save the token as an environment variable. Ask how they prefer to store it:
   • Add NOTION_API_TOKEN=<token> to a .env file in the project root (recommended for local dev)
   • Or export it in the shell: export NOTION_API_TOKEN=<token>

Validate:

npx pipes doctor

Expected: [ok] Notion auth. If it fails, revisit the token value.

3. Design the Pipe

Ask first, build second. The user should decide what they want to build before any code is written.

Present these pipe ideas with the framing: "Each state in the pipe runs a specialized inline agent function — that's what makes Pipes a pipe, not just a script."

Offer these examples (lead with the more novel/interesting ones):

• PR review pipe — a planner reads the diff → a security agent scans for vulnerabilities → a performance agent checks bottlenecks → a summarizer writes the final review comment
• Research-to-report — a web researcher gathers sources → an analyst synthesizes findings → a writer drafts the report → an editor polishes it
• Spec-to-code pipe — a product agent writes a spec from a one-liner → an architect designs the approach → a coder implements it → a QA agent runs tests
• On-call triage — a shell agent pulls logs and metrics → an analyst diagnoses the root cause → Claude proposes a fix → a notifier posts to Slack
• Content repurposing — Claude reads a long-form article → a social agent writes posts → a newsletter agent formats an issue → an SEO agent writes metadata
• Feature development — plan → implement → verify → summarize
• Custom — describe your own states and logic

Once the user picks a direction, propose a concrete state list: state IDs, what each state does, and what kind of agent logic it needs. Confirm the state list, then use the add-factory skill to create the TypeScript pipe file.

4. Register the Pipe

After the pipe file is created under pipes/, it loads automatically in the default project layout. Use pipes.config.ts only when you want a custom project name or non-default pipe locations:

import {defineConfig} from 'notionflow'

export default defineConfig({
  name: 'Asmara Tasks',
})

Pipes walks up parent directories to find pipes.config.ts, so you can run commands from anywhere inside the project tree.

Use --config <path> on any project-scoped command to override config resolution explicitly.

5. Test It

Run one tick to process any queued tasks:

npx pipes tick --pipe <pipe-id>

Watch the output. It should execute each pipe state through its inline agent function.

If you want to provision a Notion board for queue-driven workflows, run:

npx pipes pipe create --id <pipe-id> --config pipes.config.ts

Or provision a board for an existing pipe:

npx pipes integrations notion provision-board --board <pipe-id>

Important: Tell the user they must share the database with the "Pipes" integration in Notion (click "..." on the database → "Connect to" → select "Pipes").

6. Verify

npx pipes doctor
npx pipes pipe list

All should show configured resources. Setup complete.

The user can now:

• Add tasks via Notion or npx pipes integrations notion create-task
• Run npx pipes tick to process queued tasks
• Build more pipes with the add-factory skill

Troubleshooting

doctor shows NOTION_API_TOKEN missing: Ensure NOTION_API_TOKEN is set as an environment variable or in a .env file at the project root. Pipes does not read global config files.

tick processes nothing: Run npx pipes doctor to confirm the project is resolved and auth is valid. Check that at least one pipe exists under the top-level pipes/ directory, or that pipes.config.ts points to the custom location you intended.

Pipe load error: Check that the TypeScript file exports a valid pipe object and that the file lives under the default pipes/ directory or matches the pipes declarations in pipes.config.ts. Relative declarations resolve from the project root (directory containing pipes.config.ts).

Notion page not updating: Ensure the integration is connected to the database in Notion (Share → Connect to → Pipes).

Config not found: Run commands from inside the project directory, or pass --config <path> to point to your pipes.config.ts explicitly.