Circadian Loop

Make a pi agent work on one goal indefinitely. It works, saves everything to disk, sleeps, then wakes with an empty context and carries on. Forever.

Why this exists

An agent's memory is its conversation — and conversations run out. Any job that takes days rather than minutes will fill the context window long before the work is done. The agent gets compacted, loses the thread, and starts redoing what it already finished. So you sit there babysitting it, or you never hand it the long job at all.

Circadian Loop moves the memory off the conversation and onto disk. One cycle is: do a single task → write down what happened → sleep. When it wakes, the context is empty, and that no longer matters — the mission, the task list, your messages and the last cycle's note are all files it reads back on the way in. Cycle 400 starts as clean as cycle 1.

So you can give it work that outlives a conversation. "Patch this repo's dependencies — one safe upgrade per cycle, smallest change that works" and it is still going in week twelve. "Every morning, check the production API's uptime, error rate and latency, and log an incident the moment one crosses the line" and the log keeps filling while you sleep.

And it never blocks on you. Need an answer while you're asleep or at work? The question goes into an inbox file, that one task waits, and the agent moves on to the next. Answer whenever — the next cycle picks that exact task back up first.

Install

Requires pi v0.82+ and Node 22+. No cloning, no build step.

pi install npm:circadian-loop

Restart pi after installing.

pi install git:github.com/nikheal25/circadian-loop

pi install npm:circadian-loop -l

pi -e npm:circadian-loop

Quick start

mkdir my-loop && cd my-loop
pi --approve

Then run the skill:

/skill:circadian-loop

That one command is the whole interface, and it does both jobs:

• No loop.md yet? It interviews you — what the goal is, what rules you want obeyed, how long to sleep between cycles — then writes loop.md and the loop's files and starts. That's the entire setup.
• loop.md already there? It reads it and picks the loop back up. This is also how you restart a loop after quitting pi.

You can also just say it in plain words — "set up a circadian loop", or "follow loop.md" — and the agent will usually load the skill by itself. /skill:circadian-loop is the version that always works.

How it works

You steer with one file. loop.md holds the mission, your rules, and the sleep rhythm. Edit it any time; the next cycle obeys. No restart.

Nothing is hidden. Every file is markdown you can read and edit. There is no database and no state you can't see.

One cycle, in four steps:

1. Wake. The context is empty. The agent reads loop.md, your inbox, the last handoff note and the task list.
2. Work. It does your messages first, then the topmost open task. One task per cycle.
3. Checkpoint. It updates the task list, saves deliverables where they belong in your project, and overwrites handoff.md for its next self.
4. Sleep. It calls sleep, the countdown starts, and when it ends the loop wakes again.

The sleep screen

╭──────────────────────────────────────────────────────────────────╮
│                                                                  │
│  ⠹  Circadian Loop                              waking at 03:40  │
│                                                                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│  5h 48m left                                                 3%  │
│                                                                  │
│  Reviewed 3 new job listings, shortlisted one at Canva and       │
│  parked a question about salary in the inbox.                    │
│                                                                  │
│  ▸ Wake now                                                      │
│    +1h                                                           │
│    −1h                                                           │
│    +15m                                                          │
│    −15m                                                          │
│    Help                                                          │
│    Stop the loop                                                 │
│                                                                  │
│  ↑↓ select · enter apply                                         │
╰──────────────────────────────────────────────────────────────────╯

Help answers "what is this thing actually doing?" — the last cycle's note, the mission, how many tasks are open / waiting / done, what's next, and whether your inbox needs you. With CIRCADIAN_DEBUG=1 it also shows the cycle number and what the last cycle cost in time, tool calls, tokens and dollars. Problems (a missing loop file, no tasks left, an unanswered question — and, with the debug log, a failed compaction or wake) show under Needs your attention.

Stopping and restarting

Pick Stop the loop on the countdown screen, or just quit pi. To pick it up again later, open pi in the same folder and run /skill:circadian-loop. With loop.md already there, it resumes instead of running setup.

Talking to it

Open .pi/loop/inbox.md and type a bullet under Your message box:

## ✍️ Your message box
- Stop looking at contract roles, permanent only

The next cycle reads that before anything else and does it first. Questions the agent has for you appear in the same file under Questions for you — type your answer after Your answer: and it resumes that exact task.

Configuration

Everything lives in loop.md at your project root. Every ## section in it binds the agent; these are the ones you'll actually want to edit:

Add your own ## sections and they bind the agent exactly like the built-in ones.

The sleep tool

The agent calls this itself at the end of a cycle. You never call it.

Evaluation data

When launched with CIRCADIAN_DEBUG=1 (off by default), the extension appends a line to .pi/loop/cycles.jsonl at every boundary. Each line carries an event field saying which kind it is:

The file stays on your machine and is never sent anywhere. It records everything you type, so add .pi/loop/ to your project's .gitignore before you commit — see SECURITY.md.

Limitations

• The agent must cooperate. sleep is a tool it chooses to call. A model that ignores the instruction in loop.md will not loop. Stronger models hold the protocol better.
• A cycle is not a new session. The boundary is a context compaction inside one pi session, so the session file grows even though the context does not. Very long-lived loops produce large session files.
• Costs run while you're away. That is the point, but it is real money. Use ## User rules to constrain what the agent may spend, and, with CIRCADIAN_DEBUG=1, check the Help screen's per-cycle cost.
• One task per cycle by design. If you want throughput, shorten the sleep interval rather than expecting parallel work.
• cycles.jsonl grows without bound, and the Help screen only reads the last 256 KB of it.
• Terminal-first. Headless modes (--print, rpc, json) sleep correctly, but the countdown screen and Help are TUI only.

Docs

Architecture · Troubleshooting · Contributing · Changelog · Security

License

MIT — see LICENSE.