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 uninstallExpected: 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-appThe 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@paperRun 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.tsMoving 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 theANTHROPIC_BASE_URLline from theenvblock of your Claude agent’s entry underagent_servers, keeping any other variables there; remove theenvblock 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>/v1base 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.mdorCLAUDE.mdtelling future sessions to launch throughpaperctl 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=paperctlgrep -n 'paperctl' ~/.bashrc
# delete the line eval "$(paperctl shell bash)" and any alias paper=paperctlgrep -n 'paperctl' ~/.config/fish/config.fish
# delete the line paperctl shell fish | source and any alias paper=paperctlLeave 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 uninstallIt 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 scriptssystemctl --user list-units --all | grep paperd || echo "no paperd unit"
rm -rf ~/.local/state/paper "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/paper" # leftover runtime filesThen 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# Stop and remove the daemon unit
systemctl --user disable --now paperd.service 2>/dev/null
rm -f ~/.config/systemd/user/paperd.service
systemctl --user daemon-reload
# Credentials, config, log, runtime state
rm -rf ~/.config/paper ~/.local/state/paper "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/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 onlyThen 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.