Metadata-Version: 2.4
Name: slopper
Version: 0.1.4
Summary: Run Claude Code and Codex agent sessions for Folio on your own machine.
Keywords: agents,claude-code,codex,folio
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pycrdt<0.13,>=0.12.22
Requires-Dist: claude-agent-sdk<0.3,>=0.2.152
Requires-Dist: openai-codex-cli-bin<0.157,>=0.156
Requires-Dist: httpx>=0.28.0
Requires-Dist: websockets>=13.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: python-json-logger>=2.0.0

# 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

```bash
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:

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

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

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

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

3. **Check everything**:

   ```bash
   slopper doctor
   ```

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

   ```bash
   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

| Command | |
|---|---|
| `slopper configure` | Write `~/.slopper/config.toml` (`--server`, `--token`, `--env-id`, `--workspace`) |
| `slopper doctor` | Check the config, the server, the key, git, and both agents' logins |
| `slopper service install` · `uninstall` | Install or remove the service |
| `slopper service start` · `stop` · `restart` · `status` | Control it |
| `slopper service logs [-f]` | Show (or follow) its log |
| `slopper run` | Run in the foreground instead of as a service |

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

## Upgrade

```bash
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.

| Setting | Default | |
|---|---|---|
| `SLOPPER_SERVER_URL` | `http://localhost:8000` | Folio API |
| `SLOPPER_TOKEN` | — | API key this environment registers with |
| `SLOPPER_ENV_ID` | generated once, kept in `~/.slopper/identity.toml` | This machine's name in Folio. Must stay stable: sessions are bound to it |
| `SLOPPER_WORKSPACE_ROOT` | `~/.slopper/workspaces` | One directory per session |
| `SLOPPER_CLONE_SINCE` | `1.month.ago` | How much git history a checkout carries; empty for all |
| `SLOPPER_CODEX_BIN` | the bundled one | A different `codex` binary |
