Quickstart
From an empty folder to a supervised run in a few minutes. Every step works from
the desktop app or the lk CLI — pick a tab. The terminal UI (lk with
no arguments) covers the same ground if you'd rather stay on the keyboard.
Pick a project folder to work in. A git repository is recommended — checkpoints and rollback need git — but any folder works.
1. Install loopkeep
Install the runtime with the standalone installer, or the desktop app that
bundles it — see Install for both. The background service, the Claude
adapter, and lk come together; the desktop app also starts the service for you
on launch. One requirement: the Claude Code CLI installed and signed in,
since the default engine drives the claude command.
2. Add your first project
Click the project switcher at the top of the sidebar (or Add project) and
pick your folder. If it isn't a loopkeep project yet, the app offers to set it
up: Initialize creates a .loopkeep/ folder and registers it. A folder that
already has .loopkeep/ is added directly.
What gets created:
.loopkeep/
├── policy.yaml # starter policy: actions notify by default, deploy-tagged actions ask first
└── workflows/
└── nightly.md # a nightly maintenance workflow (cron, 03:00)3. Trust the project
Until you trust a project, its project policy and automatic triggers stay off —
the same idea as direnv: configuration that arrived with a repository doesn't get
to run things until you approve it. Manual runs and your personal (home) policy
work either way. If .loopkeep/policy.yaml changes later, the project drops back
to untrusted and asks you to re-approve.
A banner at the bottom of the window flags an untrusted project. Open Policies, read the rules, and choose Save & trust (or Re-trust, or the banner's Trust on Policies).
4. Run a workflow by hand
This starts the starter workflow immediately, without waiting for its schedule. Each run works in its own git worktree and commits a checkpoint after every step, so nothing touches your working tree until you decide it should.
Open Workflows, find nightly, and click ▶ Run. The app opens the new
run so you can follow it; Runs lists every run and its state. Closing the app
window does not stop a run — the background service keeps it going.
5. Approve from the inbox
When a run proposes an action your policy marks ask-first — the starter
policy does this for anything tagged deploy — the run stops and an item appears
in the inbox. The approval screen shows the raw diff or command first; the
agent's own summary never stands alone. Everything else runs unattended and shows
up as a notification, so you review outcomes on your schedule, not the agent's.
Open Inbox. Items Waiting on you sit at the top: Approve the action, Steer it (send an instruction to course-correct without stopping the run), or Abort the run. Notify items collect under Updates, where Acknowledge clears them.
Next steps
- Write your own workflow and pick its triggers.
- Tour the desktop app — the sidebar, projects, and every setting.
- Open the terminal UI — the same dashboard, right in your terminal.
- Tune what asks first — and check why something reached you.
- Pair with the Console to manage devices and enable GitHub and Slack triggers.