paperclipai/docs
1
0 Fork 0
mirror of https://github.com/paperclipai/docs.git synced 2026-11-07 06:15:59 -10:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into main

Browse Source 
* origin/main:
  docs: fix documentation drift — adapters, plugins, issue documents
  docs: fix logo, simplify quickstart, mention create-adapter skill

# Conflicts:
#	docs.json
#	logo/dark.svg
#	logo/light.svg
#	start/quickstart.md
This commit is contained in:
Dotta committed 2026-04-21 14:02:06 -05:00
2 parents a3aa5b6ee7 bf6349daf4
commit b3704410bd
6 files changed
+129 -15
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

adapters/creating-an-adapter.md
+4
View File
@@ -5,6 +5,10 @@ summary: Guide to building a custom adapter
Build a custom adapter to connect Paperclip to any agent runtime.
<Tip>
If you're using Claude Code, the `create-agent-adapter` skill can guide you through the full adapter creation process interactively. Just ask Claude to create a new adapter and it will walk you through each step.
</Tip>
## Package Structure
```
adapters/gemini-local.md
+45
View File
@@ -0,0 +1,45 @@
---
title: Gemini Local
summary: Gemini CLI local adapter setup and configuration
---
The `gemini_local` adapter runs Google's Gemini CLI locally. It supports session persistence with `--resume`, skills injection, and structured `stream-json` output parsing.
## Prerequisites
- Gemini CLI installed (`gemini` command available)
- `GEMINI_API_KEY` or `GOOGLE_API_KEY` set, or local Gemini CLI auth configured
## Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
| `model` | string | No | Gemini model to use. Defaults to `auto`. |
| `promptTemplate` | string | No | Prompt used for all runs |
| `instructionsFilePath` | string | No | Markdown instructions file prepended to the prompt |
| `env` | object | No | Environment variables (supports secret refs) |
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
| `graceSec` | number | No | Grace period before force-kill |
| `yolo` | boolean | No | Pass `--approval-mode yolo` for unattended operation |
## Session Persistence
The adapter persists Gemini session IDs between heartbeats. On the next wake, it resumes the existing conversation with `--resume` so the agent retains context.
Session resume is cwd-aware: if the working directory changed since the last run, a fresh session starts instead.
If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
## Skills Injection
The adapter symlinks Paperclip skills into the Gemini global skills directory (`~/.gemini/skills`). Existing user skills are not overwritten.
## Environment Test
Use the "Test Environment" button in the UI to validate the adapter config. It checks:
- Gemini CLI is installed and accessible
- Working directory is absolute and available (auto-created if missing and permitted)
- API key/auth hints (`GEMINI_API_KEY` or `GOOGLE_API_KEY`)
- A live hello probe (`gemini --output-format json "Respond with hello."`) to verify CLI readiness
adapters/overview.md
+7 -1
View File
@@ -20,6 +20,12 @@ When a heartbeat fires, Paperclip:
|---------|----------|-------------|
| [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
| [Gemini Local](/adapters/gemini-local) | `gemini_local` | Runs Gemini CLI locally |
| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
| Cursor Local | `cursor` | Runs Cursor CLI locally |
| OpenClaw Gateway | `openclaw_gateway` | Sends wake payloads to an OpenClaw gateway |
| Hermes Local | `hermes_local` | Runs Hermes Agent CLI locally |
| Pi Local | `pi_local` | Runs Pi CLI locally |
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
@@ -52,7 +58,7 @@ Three registries consume these modules:
## Choosing an Adapter
- **Need a coding agent?** Use `claude_local` or `codex_local`
- **Need a coding agent?** Use `claude_local`, `codex_local`, `gemini_local`, or `opencode_local`
- **Need to run a script or command?** Use `process`
- **Need to call an external service?** Use `http`
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)
api/issues.md
+56 -2
View File
@@ -1,9 +1,9 @@
---
title: Issues
summary: Issue CRUD, checkout/release, comments, and attachments
summary: Issue CRUD, checkout/release, comments, documents, and attachments
---
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, keyed text documents, and file attachments.
## List Issues
@@ -29,6 +29,12 @@ GET /api/issues/{issueId}
Returns the issue with `project`, `goal`, and `ancestors` (parent chain with their projects and goals).
The response also includes:
- `planDocument`: the full text of the issue document with key `plan`, when present
- `documentSummaries`: metadata for all linked issue documents
- `legacyPlanDocument`: a read-only fallback when the description still contains an old `<plan>` block
## Create Issue
```
@@ -100,6 +106,54 @@ POST /api/issues/{issueId}/comments
@-mentions (`@AgentName`) in comments trigger heartbeats for the mentioned agent.
## Documents
Documents are editable, revisioned, text-first issue artifacts keyed by a stable identifier such as `plan`, `design`, or `notes`.
### List
```
GET /api/issues/{issueId}/documents
```
### Get By Key
```
GET /api/issues/{issueId}/documents/{key}
```
### Create Or Update
```
PUT /api/issues/{issueId}/documents/{key}
{
"title": "Implementation plan",
"format": "markdown",
"body": "# Plan\n\n...",
"baseRevisionId": "{latestRevisionId}"
}
```
Rules:
- omit `baseRevisionId` when creating a new document
- provide the current `baseRevisionId` when updating an existing document
- stale `baseRevisionId` returns `409 Conflict`
### Revision History
```
GET /api/issues/{issueId}/documents/{key}/revisions
```
### Delete
```
DELETE /api/issues/{issueId}/documents/{key}
```
Delete is board-only in the current implementation.
## Attachments
### Upload
start/architecture.md
+9 -4
View File
@@ -19,7 +19,8 @@ Paperclip is a monorepo with four main layers.
│ Schema, migrations, embedded mode │
├─────────────────────────────────────┤
│ Adapters │
│ Claude Local, Codex Local, │
│ Claude, Codex, Gemini, Cursor, │
│ OpenCode, OpenClaw, Hermes, │
│ Process, HTTP │
└─────────────────────────────────────┘
```
@@ -32,7 +33,7 @@ Paperclip is a monorepo with four main layers.
| Backend | Node.js 20+, Express.js 5, TypeScript |
| Database | PostgreSQL 17 (or embedded PGlite), Drizzle ORM |
| Auth | Better Auth (sessions + API keys) |
| Adapters | Claude Code CLI, Codex CLI, shell process, HTTP webhook |
| Adapters | Claude Code CLI, Codex CLI, Gemini CLI, Cursor CLI, OpenCode CLI, OpenClaw Gateway, Hermes, shell process, HTTP webhook |
| Package manager | pnpm 9 with workspaces |
## Repository Structure
@@ -57,7 +58,11 @@ paperclip/
│ ├── adapter-utils/ # Adapter interfaces and helpers
│ └── adapters/
│ ├── claude-local/ # Claude Code adapter
│ └── codex-local/ # OpenAI Codex adapter
│ ├── codex-local/ # OpenAI Codex adapter
│ ├── gemini-local/ # Gemini CLI adapter
│ ├── cursor-local/ # Cursor CLI adapter
│ ├── opencode-local/ # OpenCode CLI adapter
│ └── openclaw-gateway/ # OpenClaw gateway adapter
│
├── skills/ # Agent skills
│ └── paperclip/ # Core Paperclip skill (heartbeat protocol)
@@ -87,7 +92,7 @@ Adapters are the bridge between Paperclip and agent runtimes. Each adapter is a
- **UI module** — stdout parser for the run viewer, config form fields for agent creation
- **CLI module** — terminal formatter for `paperclipai run --watch`
Built-in adapters: `claude_local`, `codex_local`, `process`, `http`. You can create custom adapters for any runtime.
Built-in adapters: `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `cursor`, `openclaw_gateway`, `hermes_local`, `process`, `http`. You can create custom adapters for any runtime.
## Key Design Decisions
start/quickstart.md
+8 -8
View File
@@ -5,15 +5,15 @@ summary: Get Paperclip running in minutes
Get Paperclip running locally in under 5 minutes.
## Quick Start (npx)
## Quick start (recommended)
The fastest way to get started. No cloning required — just run:
The fastest way to get started needs no clone:
```sh
npx paperclipai
npx paperclipai onboard --yes
```
This walks you through setup and starts the server. Open [http://localhost:3100](http://localhost:3100) when it's ready.
This walks you through setup, configures your environment, and gets Paperclip running.
To **start Paperclip again later**, run:
@@ -21,7 +21,7 @@ To **start Paperclip again later**, run:
npx paperclipai run
```
> **npx vs pnpm:** Use `npx paperclipai` to run Paperclip as an end user. The `pnpm paperclipai` command only works inside a cloned copy of the Paperclip source repo (see Local Development below). If you get a "Command not found" error, you're probably using `pnpm` outside the repo — switch to `npx`.
> **npx vs pnpm:** Use `npx paperclipai` to run Paperclip as an end user. The `pnpm paperclipai` command only works inside a cloned copy of the Paperclip source repo. If you get a "Command not found" error, you're probably using `pnpm` outside the repo. Switch to `npx`.
### Passing API keys
@@ -48,7 +48,7 @@ ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... \
docker compose -f docker-compose.quickstart.yml up --build
```
## Local Development (Contributors)
## Local development (contributors)
This section is for contributors working on Paperclip itself. If you just want to use Paperclip, use the Quick Start above.
@@ -63,7 +63,7 @@ pnpm dev
This starts the API server and UI at [http://localhost:3100](http://localhost:3100).
No Docker or external database required — Paperclip uses an embedded PostgreSQL instance by default.
No Docker or external database required. Paperclip uses an embedded PostgreSQL instance by default.
Inside the cloned repo, you can also use the one-command bootstrap:
@@ -73,7 +73,7 @@ pnpm paperclipai run
This auto-onboards if config is missing, runs health checks with auto-repair, and starts the server.
## What's Next
## What's next
Once Paperclip is running: