A small AI agent team that researches, drafts and checks the work when you assign a task

How the system fits together

Paperclip (board) + Claude Code adapter + research, production and review tasks + an output folder; optionally a weekly routine.

• 
  Paperclip required

  Task board: holds the agents, tasks, budget and routine

  Tool guide

• 
  Claude Code required

  The adapter the three agents run on; it researches, writes and checks

  Alternative: If you want to use a different coding agent, Paperclip also offers Codex, OpenCode and Hermes adapters; the sign-in requirements for each are in its own documentation

  Tool guide

• 
  Agency Agents role texts optional

  Optional role texts to use as a model when writing the agent instructions

  Alternative: If you do not want to write the role instructions from scratch

  Tool guide

Before you start

Step-by-step setup

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/9 steps.

1. Step 1 · In the terminal

   Check your Node.js version

   I finished this step

   What for: Confirm that the package requires Node 24.11.0 or later.

   1. Open a terminal and type the command below.
   2. If the version shown is v24.11.0 or newer, go to the next step.
   3. If it is older, install Node 24. If your other projects need a different Node version, use a version manager to keep separate versions.
   macOS · LinuxFolder: Any folder

   › node --versionCopy

   How you know it worked

   • The terminal prints v24.11.0 or a higher version.
   If you get stuck: problems specific to this step

   • The version shows v22 or v20
     The package requires Node 24.11.0 or later; install Node 24. The server section of the official setup page has a line that installs Node 20 (setup_20.x), which contradicts the page's own Node 24 requirement; do not copy that line.
   Based on: Paperclip: setup guide, Paperclip: npm package listing (version and Node requirement)Get help with this step →
2. Step 2 · In the terminal

   Set up pnpm with Corepack

   I finished this step

   What for: The official setup page treats this as a separate step; do not skip it.

   1. Run the three commands below in order. The official page uses pnpm@latest in the last command; this guide pins the version (the README requires at least 9.15).
   2. Finally, check the pnpm version.
   macOS · LinuxFolder: Any folder

   › npm install -g corepack@0.36.0Copy

   Version pinned (as of August 28, 2026). Check the vendor documentation before moving to a newer version.

   macOS · LinuxFolder: Any folder

   › corepack enableCopy

   macOS · LinuxFolder: Any folder

   › corepack prepare pnpm@9.15.9 --activateCopy

   macOS · LinuxFolder: Any folder

   › pnpm --versionCopy

   How you know it worked

   • pnpm --version prints 9.15.9.
   If you get stuck: problems specific to this step

   • Permission error (EACCES) during npm install -g
     You do not have write permission for the global package folder. Do not use sudo; install Node with a version manager that runs under your user, or point npm's global folder to your own user.
   • EBADENGINE warning during npm install -g (a Node version warning for corepack)
     corepack@0.36.0 requires Node 22.22.2+, 24.15+ or 26+ (the engines field in the npm registry). On a Node 24 release older than 24.15 this warning may appear; it is a warning, not an error, and the installation can continue. If you like, upgrade Node to the latest 24 release.
   Based on: Paperclip: setup guideGet help with this step →
3. Step 3 · In the terminal

   Install and start Paperclip

   I finished this step

   What for: Get the board running on your local computer.

   1. Open the terminal without administrator or root rights (the embedded database refuses to run under an administrator account).
   2. Run the command below. The version is pinned to the one that was current on npm on the guide's last check date.
   3. When the setup finishes, open http://localhost:3100 in your browser.
   4. Paperclip collects anonymous usage telemetry (README). To turn it off, use the second command below: the environment variable goes on the same line, in front of the command (macOS/Linux). Add the same variable to the later run command as well.
   macOS · LinuxFolder: Any folder (data is kept in .paperclip in your home folder)

   › npx paperclipai@2026.1012.0 onboard --yesCopy

   Version pinned (as of October 12, 2026). Check the vendor documentation before moving to a newer version.

   macOS · LinuxFolder: Any folder (instead of the command above)

   › PAPERCLIP_TELEMETRY_DISABLED=1 npx paperclipai@2026.1012.0 onboard --yesCopy

   Version pinned (as of October 12, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • The terminal says the server is running at http://localhost:3100.
   • The Paperclip interface opens in the browser.
   If you get stuck: problems specific to this step

   • On macOS (Apple Silicon) the embedded database does not start; libzstd or liblz4 error
     Follow the macOS note on the official setup page: create the missing library links and restart.
   • The database does not start because you are an administrator
     Run the command again in a normal terminal without administrator or root rights.
   Based on: Paperclip: setup guide, Paperclip: command-line setup, version pinning, updates, Paperclip: npm package listing (version and Node requirement), Paperclip: GitHub repository (license)Get help with this step →
4. Step 4 · In an app

   Create the company, the goal and the three agents; know the risks

   I finished this step

   What for: Make research, production and review separate agents; all of them use the same Claude Code adapter and the same output folder.

   !You check this step yourself; the system should not move past it without your approval.

   1. Important risk: in the Claude adapter, skipping permission prompts is ON by default, and the working folder (cwd) is not an isolation boundary, only the starting directory. The agent can run commands on your computer without asking and can access the accounts and keys installed on it. Work under a separate user or environment with no sensitive keys and no connected accounts, and write the prohibitions explicitly into the task text.
   2. In the interface, create a new company and write a one-sentence goal, for example: Produce a content draft package for the brand every week, ready for approval.
   3. The first agent you create automatically becomes the CEO; you cannot choose its role. Create the REVIEW agent first; add the research and production agents afterward. The documentation describes the CEO as the agent that opens tasks and distributes the work. As a precaution from this guide (not a setting in the documentation), write into the review agent's instructions: do not open tasks on your own, do not add other agents, only do the review task assigned to you.
   4. Set the adapter of all three agents to Claude Code and set the working folder to the SAME absolute path (an empty folder you create for this job); the files are handed over in this folder.
   5. Do not leave the model field empty; choose the model you will use yourself and check the price on Anthropic's page. Lower the Timeout (sec) value in Advanced Run Policy; the turn limit is called maxTurnsPerRun in the documentation (default 300) and may appear under a different name in the interface. On the Harness/Runtime page, click Run test on the Test your agent card; it should say Connection successful.
   6. The setup flow has no budget field. Enter the company's monthly budget in the Audit > Budgets tab; a per-agent cap needs the CLI command in the documentation (budget agent:update) or the API, which this guide does not cover. Instead of a per-agent cap, rely on the turn and time limits and the company budget. In this version the 80% warning card looks as if it has stopped things, but the warning does not stop anything.
   7. Keep Heartbeat on interval off in Run Policy (it is already off for a new agent); keep Wake on demand on in Advanced Run Policy: assignments and the routine reach the agent through it. The agent does not run for nothing when there is no work.

   How you know it worked

   • Three agents appear in the interface, each showing the Claude Code adapter and the same working folder.
   • The Test your agent card says Connection successful.
   • The model, turn and time limits are filled in; the company budget appears in Audit > Budgets.
   If you get stuck: problems specific to this step

   • Run test says Claude was not found or you are not signed in
     On the same computer, confirm in a terminal that the claude command works and that you are signed in; Paperclip uses the installed CLI as is.
   • The agent cannot find the working folder
     Check that the folder really exists and that the path is written in full (absolute).
   • The agent ran a command I did not expect or touched something outside the folder
     This is the expected risk: permission skipping is on and cwd is not isolation. Pause the agent, set it up again under a separate user or in an environment without sensitive keys, and narrow the task text.
   Based on: Paperclip: creating a company, Paperclip: agents (current site documentation), Paperclip: creating your first agent, Paperclip: Claude Code adapter, Paperclip: costs and budgets (current site documentation), Paperclip: GitHub repository (license)Get help with this step →
5. Step 5 · In an app

   Define the three tasks, set the output folder and assign the first job

   I finished this step

   What for: Make each role produce one concrete file; then run the chain once by hand.

   1. Research task: Come up with 5 sourced topic ideas on the brand's subject for this week; write them with their source URLs to the arastirma.md file.
   2. Production task: Write a draft package for the 2 strongest topics in arastirma.md and put it in the taslak.md file. Do not send anything outside, do not use any account.
   3. Review task: Compare arastirma.md with taslak.md and list unsourced claims and missing files in the kontrol.md file. Do not change any file.
   4. Assign only the research task first. When the file appears, assign the production task, and when that is done, the review task. The documentation does not promise any ordering between tasks; because an assignment wakes the agent immediately, if you assign them all at once the review agent works on an empty folder.
   5. Add to the task text: If this week's file already exists, do not regenerate it; only complete what is missing.

   How you know it worked

   • The tasks appear as assigned on the board.
   • You can see the assigned agent running and writing a note in the task comments.
   If you get stuck: problems specific to this step

   • The task is assigned but the agent never starts
     Check that the agent is not paused, has not been stopped because of the budget, and that Wake on demand is on in Advanced Run Policy; if needed, run it by hand with Run now on the agent's page.
   Based on: Paperclip: managing tasks, Paperclip: agent execution model, Paperclip: Claude Code adapterGet help with this step →
6. Step 6 · In an app

   Read the output and the review note, then approve

   I finished this step

   What for: Do not move on to the routine before you see the expected files.

   !You check this step yourself; the system should not move past it without your approval.

   1. Check that the arastirma.md, taslak.md and kontrol.md files have been created in the working folder.
   2. Read the review note: if it lists an unsourced claim or a missing file, have that fixed first.
   3. Read and approve the drafts yourself. If you want to publish, you do it by hand with your own tools.
   4. Look at the Audit > Costs tab: runs are split into API and subscription, and the provider's quota windows are shown. The documentation does not say how subscription runs count toward the dollar budget, so keep an eye on your quota on the Claude side as well.

   How you know it worked

   • The three files are in the folder.
   • The review note contains a concrete list or a nothing-missing result.
   If you get stuck: problems specific to this step

   • No file was created, but the task looks finished
     Look at the error the agent wrote in the task comments; check that the working folder is correct and has write permission.
   Based on: Paperclip: costs and budgets (current site documentation), Paperclip: managing tasks
7. Step 7 · In an app

   Optionally, put the research task on a weekly routine

   I finished this step

   What for: Have only the research stage open itself every week; you assign the rest.

   1. Create a new routine in the Routines section; write a title and instructions (the instructions become the text of the research task opened every week).
   2. For the schedule, use the ready-made weekly option or a custom cron. The default in the documentation is daily at 10:00 (0 10 * * *); weekly example: 0 9 * * 1 for Monday at 09:00. The time zone is taken from your browser; check it.
   3. Select the research agent as the default agent. If you do not select an agent, the routine is saved but stays paused.
   4. Leave the concurrency setting at its default (a single queued job) and skip missed runs.
   5. Save and enable the routine. The routine opens a task or may reopen the previous one; the rule in the task text about not regenerating this week's file if it exists protects against that. You assign the production and review tasks yourself in order, as in step 4. To try it right away, use the routine's Run now button.

   How you know it worked

   • The routine card shows as enabled and displays the next run time.
   • When the time comes, the research task is opened or reopened, and according to the documentation the assignment wakes the agent immediately.
   If you get stuck: problems specific to this step

   • The routine cannot be enabled; a default agent required warning appears
     Assign a default agent to the routine, then enable it again.
   • The routine did not run while the computer was off
     This is expected: the routine fires while Paperclip is running. How missed runs are handled depends on the catch-up option in the routine settings.
   • The task was opened but the agent did not wake up
     According to the documentation, the routine assigns the task to the agent and the assignment wakes the agent immediately. If it did not wake up, check that the agent is not paused, has not been stopped because of the budget, and that Wake on demand is on in Advanced Run Policy; if needed, run it by hand with Run now on the agent's page.
   Based on: Paperclip: routines and triggers, Paperclip: agent execution model, Paperclip: managing tasksGet help with this step →
8. Step 8 · In the terminal

   Stop, shut down and restart

   I finished this step

   What for: Know how to stop the system whenever you want and pick up where it left off later.

   1. To stop temporarily, pause the routine and pause the agents from the board; a paused agent takes no work.
   2. To shut it down completely, close the terminal window Paperclip is running in, or stop the process there.
   3. If you restarted your computer, start it again with the command below (if you turned off telemetry, add PAPERCLIP_TELEMETRY_DISABLED=1 in front of the command); your company, agents and tasks stay in the data folder.
   4. On macOS or Linux, if you want it to start automatically at every login, use the service setup on the official services page. Windows setup is not covered in the official documentation, and this guide does not cover that operating system.
   macOS · LinuxFolder: Any folder

   › npx paperclipai@2026.1012.0 runCopy

   Version pinned (as of October 12, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • A paused agent takes no new work.
   • When you start it again, http://localhost:3100 comes back with the same data.
   If you get stuck: problems specific to this step

   • The service command does not work
     The service needs launchd on macOS and user systemd on Linux; if neither is available, run the run command in an open terminal.
   Based on: Paperclip: setup guide, Paperclip: service commands and supported systems, Paperclip: managing agentsGet help with this step →
9. Step 9 · In a code editor

   Shortcut: write three role files inside Claude Code

   I finished this step

   What for: Without installing a separate app, delegate the work in your current session to research, production and review roles.

   1. Create the .claude/agents folder in the project's root folder. If you are creating the folder for the first time, close and restart Claude Code; a running session does not see a newly created agents folder.
   2. Write three Markdown files: arastirmaci.md, uretici.md and kontrolcu.md. Each file has name and description fields at the top and that role's instructions below.
   3. If you leave the tools field empty, the subagent inherits all tools. Give the review role only read tools (Read, Glob, Grep); give the producer the write tools it needs explicitly.
   4. The research and review roles have no Write tool, so they cannot write files. Ask Claude in the session to save the results as arastirma.md and kontrol.md, or give those two roles the Write tool. The producer writes the taslak.md file.
   5. Describe the job in the session and ask Claude to delegate it to these roles. Read the result yourself.
   .claude/agents/arastirmaci.md · markdownCopy

   ---
   name: arastirmaci
   description: Prepares a sourced research note on the topic
   tools: Read, Glob, Grep, WebSearch, WebFetch
   ---
   
   You are the research role. Write the source URL next to every claim.
   Return the result as plain text for the arastirma.md file.

   The format is adapted from the official example; the role text is original to this guide.

   .claude/agents/uretici.md · markdownCopy

   ---
   name: uretici
   description: Writes a draft package from the research note
   tools: Read, Write, Edit
   ---
   
   You are the production role. Write the taslak.md file from the arastirma.md file.
   Do not send anything outside.

   The format is adapted from the official example; the role text is original to this guide.

   .claude/agents/kontrolcu.md · markdownCopy

   ---
   name: kontrolcu
   description: Checks the prepared draft against the sources
   tools: Read, Glob, Grep
   ---
   
   You are the review role. Compare the research note with the draft.
   List unsourced claims and missing sections item by item.
   Do not change any file.

   The format is adapted from the example file in the official documentation; the role text is original to this guide.

   How you know it worked

   • The three role files are in the folder.
   • Claude Code shows in the session that it delegated the work to the roles.
   • At the end of the session, arastirma.md, taslak.md and kontrol.md are in the folder.
   If you get stuck: problems specific to this step

   • Claude never uses the role
     If you created the agents folder for the first time while the session was open, restart Claude Code. Also write the description field so it says when the role should be delegated to, and mention the role's name in your request.
   Based on: Claude Code: subagentsGet help with this step →

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

• No costPaperclip software

  Open source, MIT licensed; there is no charge for the software itself. source

• SubscriptionClaude Code usage

  If you use it with a subscription sign-in, it comes out of your own plan's quota; if you use an API key, you are billed per use. Do not leave the model field empty; choose the model you will use yourself. Paperclip's Audit > Costs tab separates API and subscription runs and shows the quota windows; the documentation does not say how subscription runs count toward the dollar budget. Check the price on Anthropic's page. source

• No costTelemetry

  Paperclip collects anonymous usage telemetry; it is turned off with PAPERCLIP_TELEMETRY_DISABLED=1. This is not a cost item, just for your information. source

• HostingWhere it runs

  There is no extra cost on your own computer. If you set up a server so it runs while your computer is off, the server rental is a separate cost. source

• Setup serviceSetup support

  If you like, you can get help with role and task design and the setup steps; the scope is agreed in a call. source

Sources

• Paperclip: setup guide · Official documentation · read October 17, 2026
• Paperclip: command-line setup, version pinning, updates · Official documentation · read October 17, 2026
• Paperclip: service commands and supported systems · Official documentation · read October 17, 2026
• Paperclip: routines and triggers · Official documentation · read October 17, 2026
• Paperclip: agent execution model · Official documentation · read October 17, 2026
• Paperclip: Claude Code adapter · Official documentation · read October 17, 2026
• Paperclip: managing agents · Official documentation · read October 17, 2026
• Paperclip: managing tasks · Official documentation · read October 17, 2026
• Paperclip: creating a company · Official documentation · read October 17, 2026
• Paperclip: npm package listing (version and Node requirement) · Vendor page · read October 17, 2026
• Paperclip: GitHub repository (license) · Source code · read October 17, 2026
• Claude Code: subagents · Official documentation · read October 17, 2026
• Agency Agents: role texts repository · Source code · read October 17, 2026
• Paperclip: agents (current site documentation) · Official documentation · read October 17, 2026
• Paperclip: creating your first agent · Official documentation · read October 17, 2026
• Paperclip: costs and budgets (current site documentation) · Official documentation · read October 17, 2026