Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Paseo Productivity Plugins — AGENTS.md

This repository contains trusted local Paseo plugins for workspace notes and review workflows, reusable prompts, Linear issue work, and development-port management. Each plugin is independently installable on a local or remote Paseo daemon, and the repository is maintained for source distribution to other Paseo users.
This repository contains trusted local Paseo plugins for workspace notes and board workflows, Linear issue work, and development-port management. Each plugin is independently installable on a local or remote Paseo daemon, and the repository is maintained for source distribution to other Paseo users.

## Non-Negotiable Core Principles

Expand All @@ -19,8 +19,7 @@ User instructions take precedence. Preserve unrelated files and running processe

## Project Glossary

- **Workspace Companion**: Notes, one unified workspace board, and transcript-aware manual QA plans.
- **Prompt Library**: Globally stored reusable prompts exposed in the sidebar and composer attachment picker.
- **Workspace Companion**: Workspace-tab notes and one unified workspace board.
- **Linear**: Direct GraphQL integration for reading and explicitly confirmed issue mutations.
- **Dev Ports**: Same-user workspace process discovery, safe termination, and Tailscale Serve controls.
- **Board state**: `running` and `error` are derived from Paseo activity; `unreviewed`, `recheck`, and `approved` are plugin-owned review markers.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ For UI changes, test a wide desktop view and a compact view. Use Paseo theme col
- Keep Node APIs, credentials, shell commands, Git access, and filesystem access in `*.server.ts` files.
- Validate RPC inputs and outputs with Zod.
- Use Paseo's SDK for normal workspace and agent operations.
- Never log credentials, transcript contents, or private prompt-library entries.
- Never log credentials, transcript contents, or private workspace notes.

Paseo plugin changes require a source reload:

Expand Down
20 changes: 8 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
# Paseo plugins

Four local plugins for [Paseo](https://paseo.sh): workspace notes and QA planning, reusable prompts, Linear issue work, and development-port controls.
Three local plugins for [Paseo](https://paseo.sh): workspace notes and an agent board, Linear issue work, and development-port controls.

> [!WARNING]
> Paseo plugins are experimental, trusted code. Server-side plugin code runs without a sandbox on the daemon machine. Read the source before installing it, and expect Paseo API changes to require updates.

## Included plugins

| Plugin | What it adds | Extra requirement |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| [Workspace Companion](plugins/workspace-companion) | Markdown notes, a draggable agent board with workspace archiving, and transcript-aware manual QA plans | A configured Paseo coding-agent provider for QA generation |
| [Prompt Library](plugins/prompt-library) | A reusable prompt library in the sidebar and composer attachment picker | None |
| [Linear](plugins/linear) | Issue search, comments, status changes, and priority changes | A Linear personal API key |
| [Dev Ports](plugins/dev-ports) | Workspace port discovery, safe process stopping, browser links, and private Tailscale Serve controls | Linux daemon; Tailscale is optional |
| Plugin | What it adds | Extra requirement |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------- |
| [Workspace Companion](plugins/workspace-companion) | Markdown notes with auto-saving preview checklists, plus a draggable board and workspace archiving | None |
| [Linear](plugins/linear) | Paged issue search, Markdown issue detail, comments, assignee, status, and priority changes | A Linear personal API key |
| [Dev Ports](plugins/dev-ports) | Workspace port discovery, safe process stopping, browser links, and private Tailscale Serve controls | Linux daemon; Tailscale is optional |

Each plugin is independently installable. You do not need to enable all four.
Each plugin is independently installable. You do not need to enable all three.

## Quick start

Expand All @@ -38,7 +37,6 @@ In Paseo, open **Settings → Plugins** and enable plugins. Then install only th

```bash
paseo plugin install "$PWD/plugins/workspace-companion"
paseo plugin install "$PWD/plugins/prompt-library"
paseo plugin install "$PWD/plugins/linear"
paseo plugin install "$PWD/plugins/dev-ports"
paseo plugin ls
Expand All @@ -58,7 +56,6 @@ bun install --frozen-lockfile
bun run test
bun run typecheck
paseo plugin reload workspace-companion
paseo plugin reload prompt-library
paseo plugin reload linear
paseo plugin reload dev-ports
```
Expand All @@ -72,7 +69,6 @@ Plugin state is stored under the daemon's Paseo home, normally `~/.paseo/plugin-
- Linear mutations require an explicit confirmation in the UI.
- Dev Ports only shows same-user listeners inside registered Paseo workspaces. It sends `SIGTERM` and never force-kills a process.
- Dev Ports creates private Tailscale Serve mappings. It never enables Tailscale Funnel.
- Workspace Companion sends the focused agent transcript and current workspace changes to the provider configured for QA planning.

Read [SECURITY.md](SECURITY.md) before installing the plugins on a shared daemon.

Expand All @@ -89,7 +85,7 @@ The suite uses Bun workspaces. Each plugin keeps its own Paseo manifest, strict

## Paseo compatibility

Paseo does not currently provide a stable plugin distribution format. This repository distributes source directories that the daemon compiles locally. Use a recent Paseo release and consult the official [plugin quickstart](https://paseo.sh/docs/plugins) and [plugin reference](https://paseo.sh/docs/plugins/reference) when the API changes.
Paseo's plugin API is experimental. This repository distributes source directories that the daemon compiles locally. Use a recent Paseo release and consult the official [plugin quickstart](https://paseo.sh/docs/plugins) and [plugin reference](https://paseo.sh/docs/plugins/reference) when the API changes.

## License

Expand Down
5 changes: 2 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,15 @@ Review the plugin directory before installing it. On shared daemons, treat plugi

## Plugin permissions

- `workspace-companion` reads workspace Git metadata and the focused agent's projected transcript when you manually generate a QA plan. It stores notes, board state, and QA plans under Paseo's plugin-data directory.
- `prompt-library` reads and writes its own prompt store under Paseo's plugin-data directory. Attached prompts become part of the message sent to the selected agent.
- `workspace-companion` stores notes and board state under Paseo's plugin-data directory. Refining a note sends its current contents to the selected workspace agent.
- `linear` sends requests to Linear with the configured personal API key. Writes require an explicit confirmation in the panel.
- `dev-ports` reads Linux socket and `/proc` metadata, can send `SIGTERM` to a verified same-user workspace process, and can create or remove Tailscale Serve mappings that it owns.

None of the plugins should log credentials or stored content.

## Credentials

Never commit a Linear key or a QA-provider secret. Keep credentials in the daemon environment or the documented user-only configuration files. Restrict credential files to the daemon user:
Never commit a Linear key. Keep it in the daemon environment or the documented user-only configuration file. Restrict credential files to the daemon user:

```bash
chmod 600 ~/.config/paseo-plugins/*.env
Expand Down
15 changes: 0 additions & 15 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

23 changes: 2 additions & 21 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,14 @@ bun run typecheck
Install a plugin with an absolute directory path:

```bash
paseo plugin install "$PWD/plugins/prompt-library"
paseo plugin install "$PWD/plugins/workspace-companion"
paseo plugin ls
```

The plugin should report `running`. If it does not, inspect its retained log:

```bash
paseo plugin logs prompt-library
paseo plugin logs workspace-companion
```

## Install on a remote host
Expand Down Expand Up @@ -70,24 +70,6 @@ paseo plugin reload linear

The plugin reads the key when it handles a request. It does not return or log the key.

## Configure Workspace Companion QA

QA generation starts a temporary Paseo agent. By default it uses `codex/gpt-5.6-sol`, `auto-review`, and high thinking. If that provider or model is not available on your daemon, create:

```text
~/.config/paseo-plugins/workspace-companion.env
```

Set the provider and optional mode values:

```bash
PASEO_QA_PROVIDER=codex/gpt-5.5
PASEO_QA_MODE=auto-review
PASEO_QA_THINKING=high
```

Use provider, mode, and thinking IDs reported by your Paseo installation. Reload Workspace Companion after changing the file.

## Configure Dev Ports

Dev Ports requires a Linux daemon with `ss` and `/proc`. Port discovery and safe process stopping work without Tailscale.
Expand Down Expand Up @@ -130,7 +112,6 @@ Removing a plugin removes Paseo's installation record. It does not delete the cl
| Plugin failed to load | Run `bun run typecheck`, then inspect `paseo plugin logs <id>`. |
| Edited code is stale | Run `paseo plugin reload <id>`. |
| Linear says it is not configured | Put the key in the daemon environment or the documented credential file, then reload. |
| QA generation fails immediately | Configure a provider, model, mode, and thinking option that exist on the daemon. |
| Dev Ports shows no listeners | Confirm the daemon is Linux, `ss` is installed, and the process directory belongs to a registered workspace. |
| Tailscale access is denied | Set the daemon user as the Tailscale operator once. |

Expand Down
Loading