# wakeloop — a minimal harness for an autonomous LLM agent

One Python file, ~300 lines, three tools (shell, file writer, message queue),
plain-file memory, hard budget caps, and a guarantee that every wake leaves a
written trace.

This is the reference implementation from **The Wake Loop Handbook**
(https://thewakeloop.com/handbook/), written and operated by an autonomous
agent. The handbook's chapter 9 is an annotated walkthrough of this file.

## Quick start

```bash
pip install anthropic
export ANTHROPIC_API_KEY=sk-ant-...

mkdir -p workspace
cat > workspace/mandate.md <<'EOF'
Your goal: <what you want the agent to pursue>.
Constraints: <spending rules, honesty rules, platform rules>.
EOF

python3 wakeloop.py          # runs exactly one wake, then exits
```

Talk to the agent by appending to `workspace/inbox.txt`; it reads and clears
the queue at the start of each wake. Read its replies in `workspace/outbox.txt`
(wire that file to Telegram/email however you like).

## Scheduling wakes (systemd)

`/etc/systemd/system/wakeloop.service`:
```ini
[Unit]
Description=wakeloop agent — one wake

[Service]
Type=oneshot
User=agent
WorkingDirectory=/opt/wakeloop
Environment=WAKELOOP_WORKSPACE=/opt/wakeloop/workspace
EnvironmentFile=/opt/wakeloop/env     # ANTHROPIC_API_KEY=...
ExecStart=/usr/bin/python3 /opt/wakeloop/wakeloop.py
```

`/etc/systemd/system/wakeloop.timer`:
```ini
[Unit]
Description=wake the agent every 2 hours

[Timer]
OnCalendar=00/2:00
Persistent=true

[Install]
WantedBy=timers.target
```

```bash
systemctl enable --now wakeloop.timer
journalctl -u wakeloop.service -f     # watch it work
```

Cron works too: `0 */2 * * * cd /opt/wakeloop && python3 wakeloop.py >> wake.log 2>&1`

## Safety notes (read these)

- The bash tool gives the model a real shell. Run the harness as a dedicated
  low-privilege user, in a container, or on a throwaway VPS. The workspace
  path check in `write_file` is an accident guardrail, not a security boundary.
- Keep the spending rule in the mandate ("no money without approval") and keep
  the API key's budget capped at the provider level.
- If the agent will post anywhere public, put the disclosure/honesty rules in
  the mandate. See handbook ch. 7.

## License

MIT.