Skip to content

Uninstall paperctl and remove everything paper installed

Take paper off a machine completely — the daemon, shell routing, the menu bar app, the Codex and Pi integrations, agent settings, and installed skills — with a checklist of every path to verify.

Remove paper from a machine so that claude, codex, and pi talk to their providers directly again and nothing paper installed is left running or on disk. Do the steps in order: the ones that need paperctl come first, because the last step deletes it.

What is on your machine

What the installer, paperctl init, and the integrations put on disk, and what removes each piece:

Piece Where Removed by
paperctl binary and paperd symlink ~/.local/bin/ (older installs: /usr/local/bin/) paperctl uninstall
PATH export and shell routing block ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish, between two [|o=o|] marker lines paperctl uninstall
Daemon supervisor unit macOS ~/Library/LaunchAgents/com.papercompute.paperd.plist; Linux ~/.config/systemd/user/paperd.service paperctl uninstall
Credentials, daemon config, Codex plugin files ~/.config/paper/ paperctl uninstall
Daemon log and runtime state macOS ~/Library/Application Support/com.papercompute.paper/; Linux ~/.local/state/paper/ (or $XDG_RUNTIME_DIR/paper) log and socket by paperctl uninstall; the directory and its remaining files by hand
Menu bar app (macOS) ~/Library/LaunchAgents/com.papercompute.paper.menu.plist paperctl menu uninstall
Codex provider entry and handoff files ~/.codex/config.toml (or $CODEX_HOME/config.toml), ~/.codex/paper-codex/ paperctl plugin uninstall codex-app
Pi extension ~/.pi/agent/extensions/tapes-gateway.ts (older: paper-gateway.ts) by hand
Shell routing line you added yourself your rc file, outside the marker block by hand
ANTHROPIC_BASE_URL in Conductor or Zed app settings by hand
Recall skills ~/.claude/skills/{digest,recall,search}/, ~/.agents/skills/{digest,recall,search}/ by hand

Remove paper

Stop the menu bar app

macOS only, and only if you ran paperctl menu install. paperctl uninstall does not touch it, and left alone it would keep trying to start a daemon that no longer exists:

paperctl menu uninstall

Expected: paperctl menu uninstalled and ~/Library/LaunchAgents/com.papercompute.paper.menu.plist is gone. A missing plist is treated as already uninstalled. If the icon is still in the menu bar, pick its Quit item or run pkill -f "paperctl menu run".

Undo the Codex integration

If Codex or the ChatGPT app ever ran through paper, paper left a provider entry in Codex’s shared config. Preview, then remove it:

paperctl plugin uninstall codex-app --dry-run
paperctl plugin uninstall codex-app

The dry run names exactly what would go: the paper-openai provider in config.toml (everything else in the file stays as it was), the paper-codex/ handoff directory beside it, and the extracted plugin under ~/.config/paper/codex. Codex’s own cached copy of the plugin stays registered, and the command always ends with the line that removes it:

codex plugin remove paper-codex@paper

Run it. Expected: Removed plugin \paper-codex` from marketplace `paper`.` Then fully quit and restart the ChatGPT app so it rereads its config. If Codex never ran through paper on this machine, both commands report there was nothing to remove. Capture the ChatGPT app describes what the install changed.

Remove the Pi extension

paperctl init installs a gateway extension for Pi when ~/.pi/agent/ exists. paperctl uninstall leaves it in place, so remove it by hand:

rm -f ~/.pi/agent/extensions/tapes-gateway.ts ~/.pi/agent/extensions/paper-gateway.ts

Moving to tapes? tapesctl uses the same tapes-gateway.ts file. Install tapesctl and run tapesctl plugin install pi instead of deleting it, and it is rewritten for you.

Unset ANTHROPIC_BASE_URL in other tools

Anything you pointed at the paperd proxy stops working once the proxy is gone, so undo those settings:

  • Conductor — Settings → Environment → remove ANTHROPIC_BASE_URL (what you set).
  • Zed — in settings.json, delete the ANTHROPIC_BASE_URL line from the env block of your Claude agent’s entry under agent_servers, keeping any other variables there; remove the env block only if that leaves it empty (what you set). Open threads keep the old setting until you start a new one.
  • Your own exports — any export ANTHROPIC_BASE_URL=http://127.0.0.1:… in an rc file, a .env, or a CI job.
  • Direct gateway callers — scripts and services using a gateway API key (PAPER_API_KEY) against a <gateway endpoint>/v1 base URL. Point them back at the provider and revoke the key on the console’s API keys page.
  • Agent instructions — the setup runbook asked agents to add a “Sessions” section to AGENTS.md or CLAUDE.md telling future sessions to launch through paperctl start. Remove it, or the next agent will try to install paper again.

Remove shell routing you added yourself

The installer’s shell block is removed by the next step. A line you appended yourself following Configure shell routing is not, and once paperctl is gone every new shell prints paperctl: command not found. Delete it now:

grep -n 'paperctl' ~/.zshrc
# delete the line  eval "$(paperctl shell zsh)"  and any  alias paper=paperctl

Leave the lines between the # > [|o=o|] > paper shell init script > [|o=o|] > and # < [|o=o|] < paper shell init < [|o=o|] < markers alone: that is the installer’s block, and the next step removes it cleanly.

Remove the recall skills

If you ran paperctl skills install, three skills that call paperctl were written for Claude Code and Codex. They are useless without the CLI:

rm -rf ~/.claude/skills/{digest,recall,search} ~/.agents/skills/{digest,recall,search}

Each of those files starts its trailer with <!-- Installed by paperctl, so you can confirm they are paper’s before deleting. Skills you installed with paperctl skill sync <slug> are different: they are plain SKILL.md files that keep working without paper, so keep the ones you use.

Run paperctl uninstall

Last, because it removes the binary:

paperctl uninstall

It prompts for confirmation and then stops paperd, removes the supervisor unit, the control socket, ~/.config/paper/ (credentials and daemon config), the daemon log, the installer’s shell block, the paperd symlink, and finally paperctl itself. Add -y to skip the prompt on a machine you are scripting. Expected output, one line per step:

Stopping daemon...
Removing supervisor unit...
Removed credentials and config at /Users/<you>/.config/paper
Removed log file at /Users/<you>/Library/Application Support/com.papercompute.paper/paperd.log
Removed shell config block from /Users/<you>/.bashrc
Removed paperd symlink at /Users/<you>/.local/bin/paperd
Removed paperctl binary at /Users/<you>/.local/bin/paperctl
paperd uninstalled. All local Paper state removed.

Lines starting with ! mean a step could not be completed and name what is still on disk. A pre-v0.21.0 install in /usr/local/bin is the common one; the command prints the exact sudo rm to finish the job.

Verify

Open a new terminal and check that nothing is left running or on PATH:

command -v paperctl paperd || echo "binaries gone"
type claude            # expected: a path, not "claude is a shell function"
ls ~/.config/paper 2>/dev/null || echo "config gone"
launchctl list | grep com.papercompute.paper || echo "no paper agents"
ls ~/Library/LaunchAgents | grep com.papercompute.paper || echo "no paper plists"
rm -rf ~/Library/Application\ Support/com.papercompute.paper   # leftover attribution records, menu lock, helper scripts

Then run your agent the plain way, claude, codex, or pi, and confirm it starts and answers. If Claude Code reports it cannot connect, an ANTHROPIC_BASE_URL export is still set somewhere in your environment.

Manual cleanup

Use this when paperctl is already deleted or broken. Every path paper uses is listed, so you can run through it without the CLI. Nothing here needs sudo unless the binaries came from a pre-v0.21.0 install in /usr/local/bin.

# Stop and unload the daemon and the menu bar app
launchctl bootout gui/$(id -u)/com.papercompute.paperd 2>/dev/null
launchctl bootout gui/$(id -u)/com.papercompute.paper.menu 2>/dev/null
rm -f ~/Library/LaunchAgents/com.papercompute.paperd.plist \
      ~/Library/LaunchAgents/com.papercompute.paper.menu.plist

# Credentials, config, log, runtime state
rm -rf ~/.config/paper
rm -rf ~/Library/Application\ Support/com.papercompute.paper

# Binaries
rm -f ~/.local/bin/paperctl ~/.local/bin/paperd ~/.local/bin/paper
sudo rm -f /usr/local/bin/paper /usr/local/bin/paperd /usr/local/bin/paperctl   # pre-v0.21.0 installs only

Then edit your rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish) and delete everything from the line # > [|o=o|] > paper shell init script > [|o=o|] > through the line # < [|o=o|] < paper shell init < [|o=o|] <, both markers included, plus any eval "$(paperctl shell …)", paperctl shell fish | source, or alias paper=paperctl line outside them. Finish with the Codex, Pi, agent settings, and skills steps above, which never needed paperctl: the Codex provider is the [model_providers.*] table in ~/.codex/config.toml whose base URL points at 127.0.0.1, and codex plugin remove paper-codex@paper drops the cached plugin.

Keep capturing without paper

tapes is the open source engine that recorded your paper sessions. tapesctl start claude --ingest-url http://localhost:8082 is the equivalent of paperctl start claude against a tapes server you run. Export your sessions and remove paper has the short version; the tapes installation guide has the rest.

Frequently asked questions

What does paperctl uninstall remove?+
The paperd supervisor unit (launchd agent or systemd user unit), the control socket, your credentials and daemon config under ~/.config/paper/, the daemon log, the shell block the installer wrote to your rc file, and the paperctl and paperd binaries. It asks for confirmation first; -y skips the prompt.
What does paperctl uninstall leave behind?+
Anything paper wrote outside its own files — the macOS menu bar agent, the Paper provider in Codex's config.toml, the Pi extension under ~/.pi/agent/extensions/, a shell routing line you added by hand, ANTHROPIC_BASE_URL settings in Conductor or Zed, and the skills paperctl wrote under ~/.claude/skills and ~/.agents/skills. This page covers each one.
Every new terminal says "paperctl command not found". How do I fix it?+
A shell routing line you added yourself — eval "$(paperctl shell zsh)" or paperctl shell fish | source — is still in your rc file. paperctl uninstall only removes the block the installer wrote. Delete the line and open a new terminal.
paperctl is already gone. Can I still clean up?+
Yes. Manual cleanup lists every path paper uses on macOS and Linux and the launchctl and systemctl commands that stop the daemon without paperctl.
Copied to clipboard