slopper

Run Folio agent sessions — Claude Code or Codex — on your own machine.

slopper is the environment a Folio session runs in. It registers with your Folio server, picks up the sessions assigned to it, checks out the project's repositories into a workspace per session, and runs the agent there. Every tool call that needs your approval shows up in the session in Folio; the agent waits until you answer.

Runs on macOS and Linux, Python 3.11+. Both agent CLIs are installed with the package.

Install

uv tool install slopper        # or: pipx install slopper

Set up

1. Sign the agents in, once per machine, as the user the service will run as:

   claude login                  # Claude Code
   codex login                   # Codex (optional)
   

2. Point it at Folio with an API key from Folio's settings:

   slopper configure --server https://api.folio.example.com --token <api-key>
   

   This writes ~/.slopper/config.toml, readable only by you.

3. Check everything:

   slopper doctor
   

4. Run it as a service — started now, at every login, and again if it crashes:

   slopper service install
   

   • macOS: a LaunchAgent (~/Library/LaunchAgents/slopper.plist) in your login session, so it can use the Claude login in your Keychain. Logs: ~/Library/Logs/slopper/slopper.log.
   • Linux: a systemd user unit (~/.config/systemd/user/slopper.service). Logs: journalctl --user -u slopper. To keep it running while you are logged out (a headless machine): sudo loginctl enable-linger $USER.

Commands

Only one environment runs per user account; a second slopper run refuses to start while the service is running.

Upgrade

uv tool upgrade slopper && slopper service restart

The service runs the installed interpreter by path, so it picks up the new version on restart — there is nothing to reinstall.

Configuration

~/.slopper/config.toml holds the settings; environment variables of the same name override it.